Merge serde attributes and improve docs

crates/ruma-api-macros/src/attribute.rs

@@ -22,8 +22,10 @@ impl Parse for MetaValue {
     }
 }
 
-/// Like syn::MetaNameValue, but expects an identifier as the value. Also, we don't care about the
+/// Like syn::MetaNameValue, but expects an identifier as the value.
-/// the span of the equals sign, so we don't have the `eq_token` field from syn::MetaNameValue.
+///
+/// Also, we don't care about the the span of the equals sign, so we don't have the `eq_token` field
+/// from syn::MetaNameValue.
 pub struct MetaNameValue<V> {
     /// The part left of the equals sign
     pub name: Ident,
@@ -50,7 +52,9 @@ pub enum Meta {
 }
 
 impl Meta {
-    /// Check if the given attribute is a ruma_api attribute. If it is, parse it.
+    /// Check if the given attribute is a ruma_api attribute.
+    ///
+    /// If it is, parse it.
     pub fn from_attribute(attr: &syn::Attribute) -> syn::Result<Option<Self>> {
         if attr.path.is_ident("ruma_api") {
             attr.parse_args().map(Some)

crates/ruma-api/src/lib.rs

@@ -216,14 +216,16 @@ use error::{FromHttpRequestError, FromHttpResponseError, IntoHttpError};
 #[derive(Clone, Copy, Debug)]
 #[allow(clippy::exhaustive_enums)]
 pub enum SendAccessToken<'a> {
-    /// Add the given access token to the request only if the `METADATA` on the request requires it
+    /// Add the given access token to the request only if the `METADATA` on the request requires
+    /// it.
     IfRequired(&'a str),
 
-    /// Always add the access token
+    /// Always add the access token.
     Always(&'a str),
 
-    /// Don't add an access token. This will lead to an error if the request endpoint requires
+    /// Don't add an access token.
-    /// authentication
+    ///
+    /// This will lead to an error if the request endpoint requires authentication
     None,
 }
 

crates/ruma-appservice-api/src/lib.rs

@@ -87,7 +87,9 @@ pub struct Registration {
     /// A list of users, aliases and rooms namespaces that the application service controls.
     pub namespaces: Namespaces,
 
-    /// Whether requests from masqueraded users are rate-limited. The sender is excluded.
+    /// Whether requests from masqueraded users are rate-limited.
+    ///
+    /// The sender is excluded.
     #[serde(skip_serializing_if = "Option::is_none")]
     pub rate_limited: Option<bool>,
 
@@ -123,7 +125,9 @@ pub struct RegistrationInit {
     /// A list of users, aliases and rooms namespaces that the application service controls.
     pub namespaces: Namespaces,
 
-    /// Whether requests from masqueraded users are rate-limited. The sender is excluded.
+    /// Whether requests from masqueraded users are rate-limited.
+    ///
+    /// The sender is excluded.
     pub rate_limited: Option<bool>,
 
     /// The external protocols which the application service provides (e.g. IRC).

crates/ruma-client-api/src/error.rs

@@ -15,7 +15,9 @@ use serde_json::{from_slice as from_json_slice, Value as JsonValue};
 /// Separate module because it's a lot of code.
 mod kind_serde;
 
-/// An enum for the error kind. Items may contain additional information.
+/// An enum for the error kind.
+///
+/// Items may contain additional information.
 #[derive(Debug, Clone, PartialEq, Eq)]
 #[non_exhaustive]
 pub enum ErrorKind {
@@ -25,7 +27,9 @@ pub enum ErrorKind {
     /// M_UNKNOWN_TOKEN
     UnknownToken {
         /// If this is `true`, the client can acquire a new access token by specifying the device
-        /// ID it is already using to the login API. For more information, see [the spec].
+        /// ID it is already using to the login API.
+        ///
+        /// For more information, see [the spec].
         ///
         /// [the spec]: https://matrix.org/docs/spec/client_server/r0.6.1#soft-logout
         soft_logout: bool,

crates/ruma-client-api/src/r0/account/request_3pid_management_token_via_email.rs

@@ -30,9 +30,10 @@ ruma_api! {
         #[serde(skip_serializing_if = "Option::is_none")]
         pub next_link: Option<&'a str>,
 
-        /// Optional identity server hostname and access token. Deprecated since r0.6.0.
+        /// Optional identity server hostname and access token.
-        #[serde(flatten)]
+        ///
-        #[serde(skip_serializing_if = "Option::is_none")]
+        /// Deprecated since r0.6.0.
+        #[serde(flatten, skip_serializing_if = "Option::is_none")]
         pub identity_server_info: Option<IdentityServerInfo<'a>>,
     }
 
@@ -40,10 +41,12 @@ ruma_api! {
         /// The session identifier given by the identity server.
         pub sid: SessionIdBox,
 
-        /// URL to submit validation token to. If omitted, verification happens without client.
+        /// URL to submit validation token to.
         ///
-        /// If you activate the `compat` feature, this field being an empty string in JSON will give
+        /// If omitted, verification happens without client.
-        /// you `None` here.
+        ///
+        /// If you activate the `compat` feature, this field being an empty string in JSON will
+        /// result in `None` here during deserialization.
         #[serde(skip_serializing_if = "Option::is_none")]
         #[cfg_attr(
             feature = "compat",

crates/ruma-client-api/src/r0/account/request_3pid_management_token_via_msisdn.rs

@@ -33,9 +33,10 @@ ruma_api! {
         #[serde(skip_serializing_if = "Option::is_none")]
         pub next_link: Option<&'a str>,
 
-        /// Optional identity server hostname and access token. Deprecated since r0.6.0.
+        /// Optional identity server hostname and access token.
-        #[serde(flatten)]
+        ///
-        #[serde(skip_serializing_if = "Option::is_none")]
+        /// Deprecated since r0.6.0.
+        #[serde(flatten, skip_serializing_if = "Option::is_none")]
         pub identity_server_info: Option<IdentityServerInfo<'a>>,
     }
 
@@ -43,10 +44,12 @@ ruma_api! {
         /// The session identifier given by the identity server.
         pub sid: SessionIdBox,
 
-        /// URL to submit validation token to. If omitted, verification happens without client.
+        /// URL to submit validation token to.
         ///
-        /// If you activate the `compat` feature, this field being an empty string in JSON will give
+        /// If omitted, verification happens without client.
-        /// you `None` here.
+        ///
+        /// If you activate the `compat` feature, this field being an empty string in JSON will
+        /// result in `None` here during deserialization.
         #[serde(skip_serializing_if = "Option::is_none")]
         #[cfg_attr(
             feature = "compat",

crates/ruma-client-api/src/r0/account/request_password_change_token_via_email.rs

@@ -30,9 +30,10 @@ ruma_api! {
         #[serde(skip_serializing_if = "Option::is_none")]
         pub next_link: Option<&'a str>,
 
-        /// Optional identity server hostname and access token. Deprecated since r0.6.0.
+        /// Optional identity server hostname and access token.
-        #[serde(flatten)]
+        ///
-        #[serde(skip_serializing_if = "Option::is_none")]
+        /// Deprecated since r0.6.0.
+        #[serde(flatten, skip_serializing_if = "Option::is_none")]
         pub identity_server_info: Option<IdentityServerInfo<'a>>,
     }
 
@@ -40,10 +41,12 @@ ruma_api! {
         /// The session identifier given by the identity server.
         pub sid: SessionIdBox,
 
-        /// URL to submit validation token to. If omitted, verification happens without client.
+        /// URL to submit validation token to.
         ///
-        /// If you activate the `compat` feature, this field being an empty string in JSON will give
+        /// If omitted, verification happens without client.
-        /// you `None` here.
+        ///
+        /// If you activate the `compat` feature, this field being an empty string in JSON will result
+        /// in `None` here during deserialization.
         #[serde(skip_serializing_if = "Option::is_none")]
         #[cfg_attr(
             feature = "compat",

crates/ruma-client-api/src/r0/account/request_password_change_token_via_msisdn.rs

@@ -36,10 +36,12 @@ ruma_api! {
         /// The session identifier given by the identity server.
         pub sid: SessionIdBox,
 
-        /// URL to submit validation token to. If omitted, verification happens without client.
+        /// URL to submit validation token to.
         ///
-        /// If you activate the `compat` feature, this field being an empty string in JSON will give
+        /// If omitted, verification happens without client.
-        /// you `None` here.
+        ///
+        /// If you activate the `compat` feature, this field being an empty string in JSON will result
+        /// in `None` here during deserialization.
         #[serde(skip_serializing_if = "Option::is_none")]
         #[cfg_attr(
             feature = "compat",

crates/ruma-client-api/src/r0/account/request_registration_token_via_email.rs

@@ -30,9 +30,10 @@ ruma_api! {
         #[serde(skip_serializing_if = "Option::is_none")]
         pub next_link: Option<&'a str>,
 
-        /// Optional identity server hostname and access token. Deprecated since r0.6.0.
+        /// Optional identity server hostname and access token.
-        #[serde(flatten)]
+        ///
-        #[serde(skip_serializing_if = "Option::is_none")]
+        /// Deprecated since r0.6.0.
+        #[serde(flatten, skip_serializing_if = "Option::is_none")]
         pub identity_server_info: Option<IdentityServerInfo<'a>>,
     }
 
@@ -40,10 +41,12 @@ ruma_api! {
         /// The session identifier given by the identity server.
         pub sid: SessionIdBox,
 
-        /// URL to submit validation token to. If omitted, verification happens without client.
+        /// URL to submit validation token to.
         ///
-        /// If you activate the `compat` feature, this field being an empty string in JSON will give
+        /// If omitted, verification happens without client.
-        /// you `None` here.
+        ///
+        /// If you activate the `compat` feature, this field being an empty string in JSON will result
+        /// in `None` here during deserialization.
         #[serde(skip_serializing_if = "Option::is_none")]
         #[cfg_attr(
             feature = "compat",

crates/ruma-client-api/src/r0/account/request_registration_token_via_msisdn.rs

@@ -33,9 +33,10 @@ ruma_api! {
         #[serde(skip_serializing_if = "Option::is_none")]
         pub next_link: Option<&'a str>,
 
-        /// Optional identity server hostname and access token. Deprecated since r0.6.0.
+        /// Optional identity server hostname and access token.
-        #[serde(flatten)]
+        ///
-        #[serde(skip_serializing_if = "Option::is_none")]
+        /// Deprecated since r0.6.0.
+        #[serde(flatten, skip_serializing_if = "Option::is_none")]
         pub identity_server_info: Option<IdentityServerInfo<'a>>,
     }
 
@@ -43,10 +44,12 @@ ruma_api! {
         /// The session identifier given by the identity server.
         pub sid: SessionIdBox,
 
-        /// URL to submit validation token to. If omitted, verification happens without client.
+        /// URL to submit validation token to.
         ///
-        /// If you activate the `compat` feature, this field being an empty string in JSON will give
+        /// If omitted, verification happens without client.
-        /// you `None` here.
+        ///
+        /// If you activate the `compat` feature, this field being an empty string in JSON will result
+        /// in `None` here during deserialization.
         #[serde(skip_serializing_if = "Option::is_none")]
         #[cfg_attr(
             feature = "compat",

crates/ruma-client-api/src/r0/backup/add_backup_key_session.rs

@@ -17,7 +17,9 @@ ruma_api! {
     }
 
     request: {
-        /// The backup version. Must be the current backup.
+        /// The backup version.
+        ///
+        /// Must be the current backup.
         #[ruma_api(query)]
         pub version: &'a str,
 
@@ -35,8 +37,10 @@ ruma_api! {
     }
 
     response: {
-        /// An opaque string representing stored keys in the backup. Clients can compare it with
+        /// An opaque string representing stored keys in the backup.
-        /// the etag value they received in the request of their last key storage request.
+        ///
+        /// Clients can compare it with the etag value they received in the request of their last
+        /// key storage request.
         pub etag: String,
 
         /// The number of keys stored in the backup.

crates/ruma-client-api/src/r0/backup/add_backup_key_sessions.rs

@@ -19,7 +19,9 @@ ruma_api! {
     }
 
     request: {
-        /// The backup version. Must be the current backup.
+        /// The backup version.
+        ///
+        /// Must be the current backup.
         #[ruma_api(query)]
         pub version: &'a str,
 
@@ -32,8 +34,10 @@ ruma_api! {
     }
 
     response: {
-        /// An opaque string representing stored keys in the backup. Clients can compare it with
+        /// An opaque string representing stored keys in the backup.
-        /// the etag value they received in the request of their last key storage request.
+        ///
+        /// Clients can compare it with the etag value they received in the request of their last
+        /// key storage request.
         pub etag: String,
 
         /// The number of keys stored in the backup.

crates/ruma-client-api/src/r0/backup/add_backup_keys.rs

@@ -19,7 +19,9 @@ ruma_api! {
     }
 
     request: {
-        /// The backup version. Must be the current backup.
+        /// The backup version.
+        ///
+        /// Must be the current backup.
         #[ruma_api(query)]
         pub version: &'a str,
 
@@ -28,8 +30,10 @@ ruma_api! {
     }
 
     response: {
-        /// An opaque string representing stored keys in the backup. Clients can compare it with
+        /// An opaque string representing stored keys in the backup.
-        /// the etag value they received in the request of their last key storage request.
+        ///
+        /// Clients can compare it with  the etag value they received in the request of their last
+        /// key storage request.
         pub etag: String,
 
         /// The number of keys stored in the backup.

crates/ruma-client-api/src/r0/backup/create_backup.rs

@@ -21,7 +21,7 @@ ruma_api! {
     }
 
     response: {
-        /// The backup version. This is an opaque string.
+        /// The backup version.
         pub version: String,
     }
 

crates/ruma-client-api/src/r0/backup/delete_backup_key_session.rs

@@ -15,7 +15,9 @@ ruma_api! {
     }
 
     request: {
-        /// The backup version. Must be the current backup.
+        /// The backup version.
+        ///
+        /// Must be the current backup.
         #[ruma_api(query)]
         pub version: &'a str,
 
@@ -29,8 +31,10 @@ ruma_api! {
     }
 
     response: {
-        /// An opaque string representing stored keys in the backup. Clients can compare it with
+        /// An opaque string representing stored keys in the backup.
-        /// the etag value they received in the request of their last key storage request.
+        ///
+        /// Clients can compare it with  the etag value they received in the request of their last
+        /// key storage request.
         pub etag: String,
 
         /// The number of keys stored in the backup.

crates/ruma-client-api/src/r0/backup/delete_backup_key_sessions.rs

@@ -15,7 +15,9 @@ ruma_api! {
     }
 
     request: {
-        /// The backup version. Must be the current backup.
+        /// The backup version.
+        ///
+        /// Must be the current backup.
         #[ruma_api(query)]
         pub version: &'a str,
 
@@ -25,8 +27,10 @@ ruma_api! {
     }
 
     response: {
-        /// An opaque string representing stored keys in the backup. Clients can compare it with
+        /// An opaque string representing stored keys in the backup.
-        /// the etag value they received in the request of their last key storage request.
+        ///
+        /// Clients can compare it with the etag value they received in the request of their last
+        /// key storage request.
         pub etag: String,
 
         /// The number of keys stored in the backup.

crates/ruma-client-api/src/r0/backup/delete_backup_keys.rs

@@ -14,14 +14,18 @@ ruma_api! {
     }
 
     request: {
-        /// The backup version. Must be the current backup.
+        /// The backup version.
+        ///
+        /// Must be the current backup.
         #[ruma_api(query)]
         pub version: &'a str,
     }
 
     response: {
-        /// An opaque string representing stored keys in the backup. Clients can compare it with
+        /// An opaque string representing stored keys in the backup.
-        /// the etag value they received in the request of their last key storage request.
+        ///
+        /// Clients can compare it with the etag value they received in the request of their last
+        /// key storage request.
         pub etag: String,
 
         /// The number of keys stored in the backup.

crates/ruma-client-api/src/r0/backup/get_backup.rs

@@ -29,11 +29,13 @@ ruma_api! {
         /// The number of keys stored in the backup.
         pub count: UInt,
 
-        /// An opaque string representing stored keys in the backup. Clients can compare it with
+        /// An opaque string representing stored keys in the backup.
-        /// the etag value they received in the request of their last key storage request.
+        ///
+        /// Clients can compare it with the etag value they received in the request of their last
+        /// key storage request.
         pub etag: String,
 
-        /// The backup version. This is an opaque string.
+        /// The backup version.
         pub version: String,
     }
 

crates/ruma-client-api/src/r0/backup/get_backup_key_session.rs

@@ -16,7 +16,9 @@ ruma_api! {
     }
 
     request: {
-        /// The backup version. Must be the current backup.
+        /// The backup version.
+        ///
+        /// Must be the current backup.
         #[ruma_api(query)]
         pub version: &'a str,
 

crates/ruma-client-api/src/r0/backup/get_backup_key_sessions.rs

@@ -18,7 +18,9 @@ ruma_api! {
     }
 
     request: {
-        /// The backup version. Must be the current backup.
+        /// The backup version
+        ///
+        /// Must be the current backup.
         #[ruma_api(query)]
         pub version: &'a str,
 

crates/ruma-client-api/src/r0/backup/get_backup_keys.rs

@@ -18,7 +18,9 @@ ruma_api! {
     }
 
     request: {
-        /// The backup version. Must be the current backup.
+        /// The backup version.
+        ///
+        /// Must be the current backup.
         #[ruma_api(query)]
         pub version: &'a str,
     }

crates/ruma-client-api/src/r0/backup/get_latest_backup.rs

@@ -26,11 +26,13 @@ ruma_api! {
         /// The number of keys stored in the backup.
         pub count: UInt,
 
-        /// An opaque string represetning stored keys in the backup. Clients can compare it with
+        /// An opaque string representing stored keys in the backup.
-        /// the etag value they received in the request of their last key storage request.
+        ///
+        /// Clients can compare it with the etag value they received in the request of their last
+        /// key storage request.
         pub etag: String,
 
-        /// The backup version. This is an opaque string.
+        /// The backup version.
         pub version: String,
     }
 

crates/ruma-client-api/src/r0/device/update_device.rs

@@ -18,8 +18,9 @@ ruma_api! {
         #[ruma_api(path)]
         pub device_id: &'a DeviceId,
 
-        /// The new display name for this device. If this is `None`, the display name won't be
+        /// The new display name for this device.
-        /// changed.
+        ///
+        /// If this is `None`, the display name won't be changed.
         #[serde(skip_serializing_if = "Option::is_none")]
         pub display_name: Option<String>,
     }

crates/ruma-client-api/src/r0/directory.rs

@@ -47,8 +47,8 @@ pub struct PublicRoomsChunk {
 
     /// The URL for the room's avatar, if one is set.
     ///
-    /// If you activate the `compat` feature, this field being an empty string in JSON will give
+    /// If you activate the `compat` feature, this field being an empty string in JSON will result
-    /// you `None` here.
+    /// in `None` here during deserialization.
     #[serde(skip_serializing_if = "Option::is_none")]
     #[cfg_attr(
         feature = "compat",

crates/ruma-client-api/src/r0/filter/lazy_load.rs

@@ -13,8 +13,10 @@ pub enum LazyLoadOptions {
 
     /// Enables lazy-loading of events.
     Enabled {
-        /// If `true`, sends all membership events for all events, even if they have
+        /// If `true`, sends all membership events for all events, even if they have already been
-        /// already been sent to the client. Defaults to `false`.
+        /// sent to the client.
+        ///
+        /// Defaults to `false`.
         include_redundant_members: bool,
     },
 }

crates/ruma-client-api/src/r0/keys/get_keys.rs

@@ -22,8 +22,9 @@ ruma_api! {
 
     #[derive(Default)]
     request: {
-        /// The time (in milliseconds) to wait when downloading keys from remote
+        /// The time (in milliseconds) to wait when downloading keys from remote servers.
-        /// servers. 10 seconds is the recommended default.
+        ///
+        /// 10 seconds is the recommended default.
         #[serde(
             with = "ruma_serde::duration::opt_ms",
             default,
@@ -31,24 +32,25 @@ ruma_api! {
         )]
         pub timeout: Option<Duration>,
 
-        /// The keys to be downloaded. An empty list indicates all devices for
+        /// The keys to be downloaded.
-        /// the corresponding user.
+        ///
+        /// An empty list indicates all devices for the corresponding user.
         pub device_keys: BTreeMap<UserId, Vec<DeviceIdBox>>,
 
-        /// If the client is fetching keys as a result of a device update
+        /// If the client is fetching keys as a result of a device update received in a sync
-        /// received in a sync request, this should be the 'since' token of that
+        /// request, this should be the 'since' token of that sync request, or any later sync token.
-        /// sync request, or any later sync token. This allows the server to
+        ///
-        /// ensure its response contains the keys advertised by the notification
+        /// This allows the server to ensure its response contains the keys advertised by the
-        /// in that sync.
+        /// notification in that sync.
         #[serde(skip_serializing_if = "Option::is_none")]
         pub token: Option<&'a str>,
     }
 
     #[derive(Default)]
     response: {
-        /// If any remote homeservers could not be reached, they are recorded
+        /// If any remote homeservers could not be reached, they are recorded here.
-        /// here. The names of the properties are the names of the unreachable
+        ///
-        /// servers.
+        /// The names of the properties are the names of the unreachable servers.
         #[serde(default, skip_serializing_if = "BTreeMap::is_empty")]
         pub failures: BTreeMap<String, JsonValue>,
 

crates/ruma-client-api/src/r0/keys/upload_keys.rs

@@ -19,7 +19,9 @@ ruma_api! {
 
     #[derive(Default)]
     request: {
-        /// Identity keys for the device. May be absent if no new identity keys are required.
+        /// Identity keys for the device.
+        ///
+        /// May be absent if no new identity keys are required.
         #[serde(skip_serializing_if = "Option::is_none")]
         pub device_keys: Option<DeviceKeys>,
 

crates/ruma-client-api/src/r0/keys/upload_signing_keys.rs

@@ -27,13 +27,17 @@ ruma_api! {
         #[serde(skip_serializing_if = "Option::is_none")]
         pub master_key: Option<CrossSigningKey>,
 
-        /// The user's self-signing key. Must be signed with the accompanied master, or by the
+        /// The user's self-signing key.
-        /// user's most recently uploaded master key if no master key is included in the request.
+        ///
+        /// Must be signed with the accompanied master, or by the user's most recently uploaded
+        /// master key if no master key is included in the request.
         #[serde(skip_serializing_if = "Option::is_none")]
         pub self_signing_key: Option<CrossSigningKey>,
 
-        /// The user's user-signing key. Must be signed with the accompanied master, or by the
+        /// The user's user-signing key.
-        /// user's most recently uploaded master key if no master key is included in the request.
+        ///
+        /// Must be signed with the accompanied master, or by the user's most recently uploaded
+        /// master key if no master key is included in the request.
         #[serde(skip_serializing_if = "Option::is_none")]
         pub user_signing_key: Option<CrossSigningKey>,
     }

crates/ruma-client-api/src/r0/media/create_content.rs

@@ -46,8 +46,7 @@ ruma_api! {
         /// This uses the unstable prefix in
         /// [MSC2448](https://github.com/matrix-org/matrix-doc/pull/2448).
         #[cfg(feature = "unstable-pre-spec")]
-        #[serde(rename = "xyz.amorgan.blurhash")]
+        #[serde(rename = "xyz.amorgan.blurhash", skip_serializing_if = "Option::is_none")]
-        #[serde(skip_serializing_if = "Option::is_none")]
         pub blurhash: Option<String>,
     }
 

crates/ruma-client-api/src/r0/media/get_content_thumbnail.rs

@@ -29,13 +29,15 @@ ruma_api! {
         #[serde(skip_serializing_if = "Option::is_none")]
         pub method: Option<Method>,
 
-        /// The *desired* width of the thumbnail. The actual thumbnail may not match the size
+        /// The *desired* width of the thumbnail.
-        /// specified.
+        ///
+        /// The actual thumbnail may not match the size specified.
         #[ruma_api(query)]
         pub width: UInt,
 
-        /// The *desired* height of the thumbnail. The actual thumbnail may not match the size
+        /// The *desired* height of the thumbnail.
-        /// specified.
+        ///
+        /// The actual thumbnail may not match the size specified.
         #[ruma_api(query)]
         pub height: UInt,
 

crates/ruma-client-api/src/r0/membership/get_member_events.rs

@@ -20,21 +20,26 @@ ruma_api! {
         #[ruma_api(path)]
         pub room_id: &'a RoomId,
 
-        /// The point in time (pagination token) to return members for in the room. This token can
+        /// The point in time (pagination token) to return members for in the room.
-        /// be obtained from a prev_batch token returned for each room by the sync API.
+        ///
+        /// This token can be obtained from a prev_batch token returned for each room by the sync
+        /// API.
         #[serde(skip_serializing_if = "Option::is_none")]
         #[ruma_api(query)]
         pub at: Option<&'a str>,
 
-        /// The kind of memberships to filter for. Defaults to no filtering if unspecified. When
+        /// The kind of memberships to filter for.
-        /// specified alongside not_membership, the two parameters create an 'or' condition: either
+        ///
-        /// the membership is the same as membership or is not the same as not_membership.
+        /// Defaults to no filtering if unspecified. When specified alongside not_membership, the
+        /// two parameters create an 'or' condition: either the membership is the same as membership
+        /// or is not the same as not_membership.
         #[serde(skip_serializing_if = "Option::is_none")]
         #[ruma_api(query)]
         pub membership: Option<MembershipEventFilter>,
 
-        /// The kind of memberships to *exclude* from the results. Defaults to no filtering if
+        /// The kind of memberships to *exclude* from the results.
-        /// unspecified.
+        ///
+        /// Defaults to no filtering if unspecified.
         #[serde(skip_serializing_if = "Option::is_none")]
         #[ruma_api(query)]
         pub not_membership: Option<MembershipEventFilter>,

crates/ruma-client-api/src/r0/membership/join_room_by_id_or_alias.rs

@@ -20,8 +20,9 @@ ruma_api! {
         #[ruma_api(path)]
         pub room_id_or_alias: &'a RoomIdOrAliasId,
 
-        /// The servers to attempt to join the room through. One of the servers
+        /// The servers to attempt to join the room through.
-        /// must be participating in the room.
+        ///
+        /// One of the servers  must be participating in the room.
         #[ruma_api(query)]
         #[serde(default, skip_serializing_if = "<[_]>::is_empty")]
         pub server_name: &'a [ServerNameBox],

crates/ruma-client-api/src/r0/membership/joined_members.rs

@@ -55,8 +55,8 @@ pub struct RoomMember {
 
     /// The mxc avatar url of the user.
     ///
-    /// If you activate the `compat` feature, this field being an empty string in JSON will give
+    /// If you activate the `compat` feature, this field being an empty string in JSON will result
-    /// you `None` here.
+    /// in `None` here during deserialization.
     #[serde(skip_serializing_if = "Option::is_none")]
     #[cfg_attr(
         feature = "compat",

crates/ruma-client-api/src/r0/profile/get_avatar_url.rs

@@ -23,8 +23,8 @@ ruma_api! {
     response: {
         /// The user's avatar URL, if set.
         ///
-        /// If you activate the `compat` feature, this field being an empty string in JSON will give
+        /// If you activate the `compat` feature, this field being an empty string in JSON will result
-        /// you `None` here.
+        /// in `None` here during deserialization.
         #[serde(skip_serializing_if = "Option::is_none")]
         #[cfg_attr(
             feature = "compat",
@@ -37,8 +37,7 @@ ruma_api! {
         /// This uses the unstable prefix in
         /// [MSC2448](https://github.com/matrix-org/matrix-doc/pull/2448).
         #[cfg(feature = "unstable-pre-spec")]
-        #[serde(rename = "xyz.amorgan.blurhash")]
+        #[serde(rename = "xyz.amorgan.blurhash", skip_serializing_if = "Option::is_none")]
-        #[serde(skip_serializing_if = "Option::is_none")]
         pub blurhash: Option<String>,
     }
 

crates/ruma-client-api/src/r0/profile/get_profile.rs

@@ -23,8 +23,8 @@ ruma_api! {
     response: {
         /// The user's avatar URL, if set.
         ///
-        /// If you activate the `compat` feature, this field being an empty string in JSON will give
+        /// If you activate the `compat` feature, this field being an empty string in JSON will result
-        /// you `None` here.
+        /// in `None` here during deserialization.
         #[serde(skip_serializing_if = "Option::is_none")]
         #[cfg_attr(
             feature = "compat",
@@ -41,8 +41,7 @@ ruma_api! {
         /// This uses the unstable prefix in
         /// [MSC2448](https://github.com/matrix-org/matrix-doc/pull/2448).
         #[cfg(feature = "unstable-pre-spec")]
-        #[serde(rename = "xyz.amorgan.blurhash")]
+        #[serde(rename = "xyz.amorgan.blurhash", skip_serializing_if = "Option::is_none")]
-        #[serde(skip_serializing_if = "Option::is_none")]
         pub blurhash: Option<String>,
     }
 

crates/ruma-client-api/src/r0/profile/set_avatar_url.rs

@@ -22,8 +22,8 @@ ruma_api! {
         ///
         /// `None` is used to unset the avatar.
         ///
-        /// If you activate the `compat` feature, this field being an empty string in JSON will give
+        /// If you activate the `compat` feature, this field being an empty string in JSON will result
-        /// you `None` here.
+        /// in `None` here during deserialization.
         #[cfg_attr(
             feature = "compat",
             serde(
@@ -43,8 +43,7 @@ ruma_api! {
         /// This uses the unstable prefix in
         /// [MSC2448](https://github.com/matrix-org/matrix-doc/pull/2448).
         #[cfg(feature = "unstable-pre-spec")]
-        #[serde(rename = "xyz.amorgan.blurhash")]
+        #[serde(rename = "xyz.amorgan.blurhash", skip_serializing_if = "Option::is_none")]
-        #[serde(skip_serializing_if = "Option::is_none")]
         pub blurhash: Option<&'a str>,
     }
 

crates/ruma-client-api/src/r0/push.rs

@@ -21,8 +21,8 @@ pub mod set_pushrule;
 pub mod set_pushrule_actions;
 pub mod set_pushrule_enabled;
 
-/// Like `SimplePushRule`, but may represent any kind of push rule
+/// Like `SimplePushRule`, but may represent any kind of push rule thanks to `pattern` and
-/// thanks to `pattern` and `conditions` being optional.
+/// `conditions` being optional.
 ///
 /// To create an instance of this type, use one of its `From` implementations.
 #[derive(Clone, Debug, Serialize, Deserialize)]
@@ -41,13 +41,15 @@ pub struct PushRule {
     pub rule_id: String,
 
     /// The conditions that must hold true for an event in order for a rule to be applied to an
-    /// event. A rule with no conditions always matches.
+    /// event.
     ///
-    /// Only applicable to underride and override rules.
+    /// A rule with no conditions always matches. Only applicable to underride and override rules.
     #[serde(skip_serializing_if = "Option::is_none")]
     pub conditions: Option<Vec<PushCondition>>,
 
-    /// The glob-style pattern to match against. Only applicable to content rules.
+    /// The glob-style pattern to match against.
+    ///
+    /// Only applicable to content rules.
     #[serde(skip_serializing_if = "Option::is_none")]
     pub pattern: Option<String>,
 }

crates/ruma-client-api/src/r0/push/get_notifications.rs

@@ -30,16 +30,20 @@ ruma_api! {
         #[serde(skip_serializing_if = "Option::is_none")]
         pub limit: Option<UInt>,
 
-        /// Allows basic filtering of events returned. Supply "highlight" to return only events
+        /// Allows basic filtering of events returned.
-        /// where the notification had the 'highlight' tweak set.
+        ///
+        /// Supply "highlight" to return only events where the notification had the 'highlight'
+        /// tweak set.
         #[ruma_api(query)]
         #[serde(skip_serializing_if = "Option::is_none")]
         pub only: Option<&'a str>,
     }
 
     response: {
-        /// The token to supply in the from param of the next /notifications request in order
+        /// The token to supply in the from param of the next /notifications request in order to
-        /// to request more events. If this is absent, there are no more results.
+        /// request more events.
+        ///
+        /// If this is absent, there are no more results.
         #[serde(skip_serializing_if = "Option::is_none")]
         pub next_token: Option<String>,
 

crates/ruma-client-api/src/r0/push/set_pushrule.rs

@@ -42,12 +42,16 @@ ruma_api! {
         pub actions: &'a [Action],
 
         /// The conditions that must hold true for an event in order for a rule to be applied to an
-        /// event. A rule with no conditions always matches. Only applicable to underride and
+        /// event.
-        /// override rules, empty Vec otherwise.
+        ///
+        /// A rule with no conditions always matches. Only applicable to underride and override
+        /// rules, empty Vec otherwise.
         #[serde(default, skip_serializing_if = "<[_]>::is_empty")]
         pub conditions: &'a [PushCondition],
 
-        /// The glob-style pattern to match against. Only applicable to content rules.
+        /// The glob-style pattern to match against.
+        ///
+        /// Only applicable to content rules.
         #[serde(skip_serializing_if = "Option::is_none")]
         pub pattern: Option<&'a str>,
     }

crates/ruma-client-api/src/r0/room/create_room.rs

@@ -71,7 +71,9 @@ ruma_api! {
         #[serde(skip_serializing_if = "Option::is_none")]
         pub room_alias_name: Option<&'a str>,
 
-        /// Room version to set for the room. Defaults to homeserver's default if not specified.
+        /// Room version to set for the room.
+        ///
+        /// Defaults to homeserver's default if not specified.
         #[serde(skip_serializing_if = "Option::is_none")]
         pub room_version: Option<&'a RoomVersionId>,
 
@@ -80,10 +82,10 @@ ruma_api! {
         #[serde(skip_serializing_if = "Option::is_none")]
         pub topic: Option<&'a str>,
 
-        /// A public visibility indicates that the room will be shown in the published room
+        /// A public visibility indicates that the room will be shown in the published room list.
-        /// list. A private visibility will hide the room from the published room list.
         ///
-        /// Defaults to `Private`.
+        /// A private visibility will hide the room from the published room list. Defaults to
+        /// `Private`.
         #[serde(default, skip_serializing_if = "ruma_serde::is_default")]
         pub visibility: Visibility,
     }

crates/ruma-client-api/src/r0/room/report_content.rs

@@ -26,7 +26,9 @@ ruma_api! {
         /// Integer between -100 and 0 rating offensivness.
         pub score: Int,
 
-        /// Reason to report content. May be blank.
+        /// Reason to report content.
+        ///
+        /// May be blank.
         pub reason: &'a str,
     }
 

crates/ruma-client-api/src/r0/search/search_events.rs

@@ -77,7 +77,9 @@ pub struct Criteria<'a> {
     /// The string to search events for.
     pub search_term: &'a str,
 
-    /// The keys to search for. Defaults to all keys.
+    /// The keys to search for.
+    ///
+    /// Defaults to all keys.
     #[serde(skip_serializing_if = "Option::is_none")]
     pub keys: Option<&'a [SearchKeys]>,
 
@@ -357,7 +359,9 @@ pub struct ResultRoomEvents {
     pub groups: BTreeMap<GroupingKey, BTreeMap<RoomIdOrUserId, ResultGroup>>,
 
     /// Token that can be used to get the next batch of results, by passing as the `next_batch`
-    /// parameter to the next call. If this field is absent, there are no more results.
+    /// parameter to the next call.
+    ///
+    /// If this field is absent, there are no more results.
     #[serde(skip_serializing_if = "Option::is_none")]
     pub next_batch: Option<String>,
 
@@ -365,8 +369,9 @@ pub struct ResultRoomEvents {
     #[serde(default, skip_serializing_if = "Vec::is_empty")]
     pub results: Vec<SearchResult>,
 
-    /// The current state for every room in the results. This is included if the request had the
+    /// The current state for every room in the results.
-    /// `include_state` key set with a value of `true`.
+    ///
+    /// This is included if the request had the `include_state` key set with a value of `true`.
     #[serde(default, skip_serializing_if = "BTreeMap::is_empty")]
     pub state: BTreeMap<RoomId, Vec<Raw<AnyStateEvent>>>,
 
@@ -398,8 +403,9 @@ impl ResultRoomEvents {
 #[cfg_attr(not(feature = "unstable-exhaustive-types"), non_exhaustive)]
 pub struct ResultGroup {
     /// Token that can be used to get the next batch of results in the group, by passing as the
-    /// `next_batch` parameter to the next call. If this field is absent, there are no more
+    /// `next_batch` parameter to the next call.
-    /// results in this group.
+    ///
+    /// If this field is absent, there are no more results in this group.
     #[serde(skip_serializing_if = "Option::is_none")]
     pub next_batch: Option<String>,
 
@@ -432,7 +438,9 @@ pub struct SearchResult {
     #[serde(skip_serializing_if = "EventContextResult::is_empty")]
     pub context: EventContextResult,
 
-    /// A number that describes how closely this result matches the search. Higher is closer.
+    /// A number that describes how closely this result matches the search.
+    ///
+    /// Higher is closer.
     #[serde(skip_serializing_if = "Option::is_none")]
     pub rank: Option<UInt>,
 
@@ -459,8 +467,8 @@ impl SearchResult {
 pub struct UserProfile {
     /// The user's avatar URL, if set.
     ///
-    /// If you activate the `compat` feature, this field being an empty string in JSON will give
+    /// If you activate the `compat` feature, this field being an empty string in JSON will result
-    /// you `None` here.
+    /// in `None` here during deserialization.
     #[serde(skip_serializing_if = "Option::is_none")]
     #[cfg_attr(
         feature = "compat",

crates/ruma-client-api/src/r0/session/login.rs

@@ -32,8 +32,9 @@ ruma_api! {
         #[serde(skip_serializing_if = "Option::is_none")]
         pub device_id: Option<&'a DeviceId>,
 
-        /// A display name to assign to the newly-created device. Ignored if device_id corresponds
+        /// A display name to assign to the newly-created device.
-        /// to a known device.
+        ///
+        /// Ignored if `device_id` corresponds to a known device.
         #[serde(skip_serializing_if = "Option::is_none")]
         pub initial_device_display_name: Option<&'a str>,
     }

crates/ruma-client-api/src/r0/state/get_state_events.rs

@@ -23,8 +23,10 @@ ruma_api! {
 
     response: {
         /// If the user is a member of the room this will be the current state of the room as a
-        /// list of events. If the user has left the room then this will be the state of the
+        /// list of events.
-        /// room when they left as a list of events.
+        ///
+        /// If the user has left the room then this will be the state of the room when they left as
+        /// a list of events.
         #[ruma_api(body)]
         pub room_state: Vec<Raw<AnyStateEvent>>,
     }

crates/ruma-client-api/src/r0/sync/sync_events.rs

@@ -247,8 +247,7 @@ pub struct JoinedRoom {
     #[serde(default, skip_serializing_if = "RoomAccountData::is_empty")]
     pub account_data: RoomAccountData,
 
-    /// The ephemeral events in the room that aren't recorded in the timeline or state of the
+    /// The ephemeral events in the room that aren't recorded in the timeline or state of the room.
-    /// room. e.g. typing.
     #[serde(default, skip_serializing_if = "Ephemeral::is_empty")]
     pub ephemeral: Ephemeral,
 }
@@ -433,8 +432,9 @@ impl Ephemeral {
 #[derive(Clone, Debug, Default, Deserialize, Serialize)]
 #[cfg_attr(not(feature = "unstable-exhaustive-types"), non_exhaustive)]
 pub struct RoomSummary {
-    /// Users which can be used to generate a room name if the room does not have
+    /// Users which can be used to generate a room name if the room does not have one.
-    /// one. Required if room name or canonical aliases are not set or empty.
+    ///
+    /// Required if room name or canonical aliases are not set or empty.
     #[serde(rename = "m.heroes", default, skip_serializing_if = "Vec::is_empty")]
     pub heroes: Vec<String>,
 

crates/ruma-client-api/src/r0/user_directory/search_users.rs

@@ -80,8 +80,8 @@ pub struct User {
 
     /// The avatar url, as an MXC, if one exists.
     ///
-    /// If you activate the `compat` feature, this field being an empty string in JSON will give
+    /// If you activate the `compat` feature, this field being an empty string in JSON will result
-    /// you `None` here.
+    /// in `None` here during deserialization.
     #[serde(skip_serializing_if = "Option::is_none")]
     #[cfg_attr(
         feature = "compat",

crates/ruma-common/src/directory.rs

@@ -51,8 +51,8 @@ pub struct PublicRoomsChunk {
 
     /// The URL for the room's avatar, if one is set.
     ///
-    /// If you activate the `compat` feature, this field being an empty string in JSON will give
+    /// If you activate the `compat` feature, this field being an empty string in JSON will result
-    /// you `None` here.
+    /// in `None` here during deserialization.
     #[serde(skip_serializing_if = "Option::is_none")]
     #[cfg_attr(
         feature = "compat",

crates/ruma-common/src/encryption.rs

@@ -11,10 +11,14 @@ use serde::{Deserialize, Serialize};
 #[derive(Clone, Debug, Deserialize, Serialize)]
 #[cfg_attr(not(feature = "unstable-exhaustive-types"), non_exhaustive)]
 pub struct DeviceKeys {
-    /// The ID of the user the device belongs to. Must match the user ID used when logging in.
+    /// The ID of the user the device belongs to.
+    ///
+    /// Must match the user ID used when logging in.
     pub user_id: UserId,
 
-    /// The ID of the device these keys belong to. Must match the device ID used when logging in.
+    /// The ID of the device these keys belong to.
+    ///
+    /// Must match the device ID used when logging in.
     pub device_id: DeviceIdBox,
 
     /// The encryption algorithms supported by this device.
@@ -113,17 +117,20 @@ pub struct CrossSigningKey {
     /// What the key is used for.
     pub usage: Vec<KeyUsage>,
 
-    /// The public key. The object must have exactly one property.
+    /// The public key.
+    ///
+    /// The object must have exactly one property.
     pub keys: BTreeMap<String, String>,
 
-    /// Signatures of the key. Only optional for master key.
+    /// Signatures of the key.
+    ///
+    /// Only optional for master key.
     #[serde(default, skip_serializing_if = "BTreeMap::is_empty")]
     pub signatures: CrossSigningKeySignatures,
 }
 
 impl CrossSigningKey {
-    /// Creates a new `CrossSigningKey` with the given user ID, usage, keys and
+    /// Creates a new `CrossSigningKey` with the given user ID, usage, keys and signatures.
-    /// signatures.
     pub fn new(
         user_id: UserId,
         usage: Vec<KeyUsage>,

crates/ruma-common/src/push.rs

@@ -392,7 +392,9 @@ impl Equivalent<PatternedPushRule> for str {
 #[derive(Clone, Debug, Default, Serialize, Deserialize)]
 #[cfg_attr(not(feature = "unstable-exhaustive-types"), non_exhaustive)]
 pub struct PusherData {
-    /// Required if the pusher's kind is http. The URL to use to send notifications to.
+    /// The URL to use to send notifications to.
+    ///
+    /// Required if the pusher's kind is http.
     #[serde(skip_serializing_if = "Option::is_none")]
     pub url: Option<String>,
 

crates/ruma-common/src/push/predefined.rs

@@ -209,10 +209,11 @@ impl ConditionalPushRule {
         }
     }
 
-    /// Matches any encrypted event sent in a room with exactly two members. Unlike other push
+    /// Matches any encrypted event sent in a room with exactly two members.
-    /// rules, this rule cannot be matched against the content of the event by nature of it being
+    ///
-    /// encrypted. This causes the rule to be an "all or nothing" match where it either matches all
+    /// Unlike other push rules, this rule cannot be matched against the content of the event by
-    /// events that are encrypted (in 1:1 rooms) or none.
+    /// nature of it being encrypted. This causes the rule to be an "all or nothing" match where it
+    /// either matches all events that are encrypted (in 1:1 rooms) or none.
     pub fn encrypted_room_one_to_one() -> Self {
         Self {
             rule_id: ".m.rules.encrypted_room_one_to_one".into(),
@@ -259,10 +260,11 @@ impl ConditionalPushRule {
         }
     }
 
-    /// Matches all encrypted events. Unlike other push rules, this rule cannot be matched against
+    /// Matches all encrypted events.
-    /// the content of the event by nature of it being encrypted. This causes the rule to be an
+    ///
-    /// "all or nothing" match where it either matches all events that are encrypted (in group
+    /// Unlike other push rules, this rule cannot be matched against the content of the event by
-    /// rooms) or none.
+    /// nature of it being encrypted. This causes the rule to be an "all or nothing" match where it
+    /// either matches all events that are encrypted (in group rooms) or none.
     pub fn encrypted() -> Self {
         Self {
             rule_id: ".m.rules.encrypted".into(),

crates/ruma-common/src/thirdparty.rs

@@ -25,8 +25,8 @@ pub struct Protocol {
 
     /// A content URI representing an icon for the third party protocol.
     ///
-    /// If you activate the `compat` feature, this field being absent in JSON will give you an
+    /// If you activate the `compat` feature, this field being absent in JSON will result in an
-    /// empty string here.
+    /// empty string here during deserialization.
     #[cfg_attr(feature = "compat", serde(default))]
     pub icon: String,
 

crates/ruma-events/src/call/answer.rs

@@ -13,7 +13,9 @@ use super::SessionDescription;
 #[cfg_attr(not(feature = "unstable-exhaustive-types"), non_exhaustive)]
 #[ruma_event(type = "m.call.answer", kind = Message)]
 pub struct CallAnswerEventContent {
-    /// The VoIP session description object. The session description type must be *answer*.
+    /// The VoIP session description object.
+    ///
+    /// The session description type must be *answer*.
     pub answer: SessionDescription,
 
     /// The ID of the call this event relates to.

crates/ruma-events/src/call/invite.rs

@@ -16,12 +16,15 @@ pub struct CallInviteEventContent {
     /// A unique identifier for the call.
     pub call_id: String,
 
-    /// The time in milliseconds that the invite is valid for. Once the invite age exceeds this
+    /// The time in milliseconds that the invite is valid for.
-    /// value, clients should discard it. They should also no longer show the call as awaiting an
+    ///
-    /// answer in the UI.
+    /// Once the invite age exceeds this value, clients should discard it. They should also no
+    /// longer show the call as awaiting an answer in the UI.
     pub lifetime: UInt,
 
-    /// The session description object. The session description type must be *offer*.
+    /// The session description object.
+    ///
+    /// The session description type must be *offer*.
     pub offer: SessionDescription,
 
     /// The version of the VoIP specification this messages adheres to.

crates/ruma-events/src/key/verification/cancel.rs

@@ -78,8 +78,9 @@ pub enum CancelCode {
     #[ruma_enum(rename = "m.user")]
     User,
 
-    /// The verification process timed out. Verification processes can define their own timeout
+    /// The verification process timed out.
-    /// parameters.
+    ///
+    /// Verification processes can define their own timeout parameters.
     #[ruma_enum(rename = "m.timeout")]
     Timeout,
 

crates/ruma-events/src/policy/rule.rs

@@ -11,8 +11,10 @@ pub mod user;
 #[derive(Clone, Debug, Deserialize, Serialize)]
 #[cfg_attr(not(feature = "unstable-exhaustive-types"), non_exhaustive)]
 pub struct PolicyRuleEventContent {
-    /// The entity affected by this rule. Glob characters * and ? can be used to match zero or more
+    /// The entity affected by this rule.
-    /// and one or more characters respectively.
+    ///
+    /// Glob characters `*` and `?` can be used to match zero or more and one or more characters
+    /// respectively.
     pub entity: String,
 
     /// The suggested action to take.

crates/ruma-events/src/presence.rs

@@ -30,8 +30,8 @@ pub struct PresenceEvent {
 pub struct PresenceEventContent {
     /// The current avatar URL for this user.
     ///
-    /// If you activate the `compat` feature, this field being an empty string in JSON will give
+    /// If you activate the `compat` feature, this field being an empty string in JSON will result
-    /// you `None` here.
+    /// in `None` here during deserialization.
     #[serde(skip_serializing_if = "Option::is_none")]
     #[cfg_attr(
         feature = "compat",

crates/ruma-events/src/room.rs

@@ -52,11 +52,15 @@ pub struct ImageInfo {
     #[serde(skip_serializing_if = "Option::is_none")]
     pub thumbnail_info: Option<Box<ThumbnailInfo>>,
 
-    /// The URL to the thumbnail of the image. Only present if the thumbnail is unencrypted.
+    /// The URL to the thumbnail of the image.
+    ///
+    /// Only present if the thumbnail is unencrypted.
     #[serde(skip_serializing_if = "Option::is_none")]
     pub thumbnail_url: Option<MxcUri>,
 
-    /// Information on the encrypted thumbnail image. Only present if the thumbnail is encrypted.
+    /// Information on the encrypted thumbnail image.
+    ///
+    /// Only present if the thumbnail is encrypted.
     #[serde(skip_serializing_if = "Option::is_none")]
     pub thumbnail_file: Option<Box<EncryptedFile>>,
 
@@ -65,8 +69,7 @@ pub struct ImageInfo {
     /// This uses the unstable prefix in
     /// [MSC2448](https://github.com/matrix-org/matrix-doc/pull/2448).
     #[cfg(feature = "unstable-pre-spec")]
-    #[serde(rename = "xyz.amorgan.blurhash")]
+    #[serde(rename = "xyz.amorgan.blurhash", skip_serializing_if = "Option::is_none")]
-    #[serde(skip_serializing_if = "Option::is_none")]
     pub blurhash: Option<String>,
 }
 
@@ -126,7 +129,9 @@ pub struct EncryptedFile {
     /// Clients should support the SHA-256 hash, which uses the key sha256.
     pub hashes: BTreeMap<String, String>,
 
-    /// Version of the encrypted attachments protocol. Must be `v2`.
+    /// Version of the encrypted attachments protocol.
+    ///
+    /// Must be `v2`.
     pub v: String,
 }
 
@@ -151,7 +156,9 @@ pub struct EncryptedFileInit {
     /// Clients should support the SHA-256 hash, which uses the key sha256.
     pub hashes: BTreeMap<String, String>,
 
-    /// Version of the encrypted attachments protocol. Must be `v2`.
+    /// Version of the encrypted attachments protocol.
+    ///
+    /// Must be `v2`.
     pub v: String,
 }
 
@@ -169,13 +176,19 @@ impl From<EncryptedFileInit> for EncryptedFile {
 #[derive(Clone, Debug, Deserialize, Serialize)]
 #[cfg_attr(not(feature = "unstable-exhaustive-types"), non_exhaustive)]
 pub struct JsonWebKey {
-    /// Key type. Must be `oct`.
+    /// Key type.
+    ///
+    /// Must be `oct`.
     pub kty: String,
 
-    /// Key operations. Must at least contain `encrypt` and `decrypt`.
+    /// Key operations.
+    ///
+    /// Must at least contain `encrypt` and `decrypt`.
     pub key_ops: Vec<String>,
 
-    /// Required. Algorithm. Must be `A256CTR`.
+    /// Algorithm.
+    ///
+    /// Must be `A256CTR`.
     pub alg: String,
 
     /// The key, encoded as url-safe unpadded base64.
@@ -195,13 +208,19 @@ pub struct JsonWebKey {
 #[derive(Debug)]
 #[allow(clippy::exhaustive_structs)]
 pub struct JsonWebKeyInit {
-    /// Key type. Must be `oct`.
+    /// Key type.
+    ///
+    /// Must be `oct`.
     pub kty: String,
 
-    /// Key operations. Must at least contain `encrypt` and `decrypt`.
+    /// Key operations.
+    ///
+    /// Must at least contain `encrypt` and `decrypt`.
     pub key_ops: Vec<String>,
 
-    /// Required. Algorithm. Must be `A256CTR`.
+    /// Algorithm.
+    ///
+    /// Must be `A256CTR`.
     pub alg: String,
 
     /// The key, encoded as url-safe unpadded base64.

crates/ruma-events/src/room/avatar.rs

@@ -85,8 +85,7 @@ pub struct ImageInfo {
     /// This uses the unstable prefix in
     /// [MSC2448](https://github.com/matrix-org/matrix-doc/pull/2448).
     #[cfg(feature = "unstable-pre-spec")]
-    #[serde(rename = "xyz.amorgan.blurhash")]
+    #[serde(rename = "xyz.amorgan.blurhash", skip_serializing_if = "Option::is_none")]
-    #[serde(skip_serializing_if = "Option::is_none")]
     pub blurhash: Option<String>,
 }
 

crates/ruma-events/src/room/create.rs

@@ -14,7 +14,9 @@ use serde::{Deserialize, Serialize};
 #[cfg_attr(not(feature = "unstable-exhaustive-types"), non_exhaustive)]
 #[ruma_event(type = "m.room.create", kind = State)]
 pub struct RoomCreateEventContent {
-    /// The `user_id` of the room creator. This is set by the homeserver.
+    /// The `user_id` of the room creator.
+    ///
+    /// This is set by the homeserver.
     #[ruma_event(skip_redaction)]
     pub creator: UserId,
 
@@ -26,7 +28,9 @@ pub struct RoomCreateEventContent {
     )]
     pub federate: bool,
 
-    /// The version of the room. Defaults to "1" if the key does not exist.
+    /// The version of the room.
+    ///
+    /// Defaults to `RoomVersionId::Version1`.
     #[serde(default = "default_room_version_id")]
     pub room_version: RoomVersionId,
 

crates/ruma-events/src/room/history_visibility.rs

@@ -6,8 +6,8 @@ use serde::{Deserialize, Serialize};
 
 /// The content of an `m.room.history_visibility` event.
 ///
-/// This event controls whether a member of a room can see the events that happened in a room
+/// This event controls whether a member of a room can see the events that happened in a room from
-/// from before they joined.
+/// before they joined.
 #[derive(Clone, Debug, Deserialize, Serialize, EventContent)]
 #[cfg_attr(not(feature = "unstable-exhaustive-types"), non_exhaustive)]
 #[ruma_event(type = "m.room.history_visibility", kind = State)]
@@ -33,21 +33,26 @@ impl RoomHistoryVisibilityEventContent {
 #[non_exhaustive]
 pub enum HistoryVisibility {
     /// Previous events are accessible to newly joined members from the point they were invited
-    /// onwards. Events stop being accessible when the member's state changes to something other
+    /// onwards.
-    /// than *invite* or *join*.
+    ///
+    /// Events stop being accessible when the member's state changes to something other than
+    /// *invite* or *join*.
     Invited,
 
     /// Previous events are accessible to newly joined members from the point they joined the room
-    /// onwards. Events stop being accessible when the member's state changes to something other
+    /// onwards.
-    /// than *join*.
+    /// Events stop being accessible when the member's state changes to something other than
+    /// *join*.
     Joined,
 
-    /// Previous events are always accessible to newly joined members. All events in the room are
+    /// Previous events are always accessible to newly joined members.
-    /// accessible, even those sent when the member was not a part of the room.
+    ///
+    /// All events in the room are accessible, even those sent when the member was not a part of
+    /// the room.
     Shared,
 
-    /// All events while this is the `HistoryVisibility` value may be shared by any
+    /// All events while this is the `HistoryVisibility` value may be shared by any participating
-    /// participating homeserver with anyone, regardless of whether they have ever joined the room.
+    /// homeserver with anyone, regardless of whether they have ever joined the room.
     WorldReadable,
 
     #[doc(hidden)]

crates/ruma-events/src/room/member.rs

@@ -40,10 +40,10 @@ use crate::{StrippedStateEvent, SyncStateEvent};
 #[cfg_attr(not(feature = "unstable-exhaustive-types"), non_exhaustive)]
 #[ruma_event(type = "m.room.member", kind = State)]
 pub struct RoomMemberEventContent {
-    /// The avatar URL for this user, if any. This is added by the homeserver.
+    /// The avatar URL for this user, if any.
     ///
-    /// If you activate the `compat` feature, this field being an empty string in JSON will give
+    /// This is added by the homeserver. If you activate the `compat` feature, this field being an
-    /// you `None` here.
+    /// empty string in JSON will result in `None` here during deserialization.
     #[serde(skip_serializing_if = "Option::is_none")]
     #[cfg_attr(
         feature = "compat",
@@ -51,7 +51,9 @@ pub struct RoomMemberEventContent {
     )]
     pub avatar_url: Option<MxcUri>,
 
-    /// The display name for this user, if any. This is added by the homeserver.
+    /// The display name for this user, if any.
+    ///
+    /// This is added by the homeserver.
     #[serde(skip_serializing_if = "Option::is_none")]
     pub displayname: Option<String>,
 
@@ -74,8 +76,7 @@ pub struct RoomMemberEventContent {
     /// This uses the unstable prefix in
     /// [MSC2448](https://github.com/matrix-org/matrix-doc/pull/2448).
     #[cfg(feature = "unstable-pre-spec")]
-    #[serde(rename = "xyz.amorgan.blurhash")]
+    #[serde(rename = "xyz.amorgan.blurhash", skip_serializing_if = "Option::is_none")]
-    #[serde(skip_serializing_if = "Option::is_none")]
     pub blurhash: Option<String>,
 
     /// User-supplied text for why their membership has changed.
@@ -302,7 +303,9 @@ fn membership_change(
 }
 
 impl RoomMemberEvent {
-    /// Helper function for membership change. Check [the specification][spec] for details.
+    /// Helper function for membership change.
+    ///
+    /// Check [the specification][spec] for details.
     ///
     /// [spec]: https://matrix.org/docs/spec/client_server/r0.6.1#m-room-member
     pub fn membership_change(&self) -> MembershipChange {
@@ -311,7 +314,9 @@ impl RoomMemberEvent {
 }
 
 impl SyncStateEvent<RoomMemberEventContent> {
-    /// Helper function for membership change. Check [the specification][spec] for details.
+    /// Helper function for membership change.
+    ///
+    /// Check [the specification][spec] for details.
     ///
     /// [spec]: https://matrix.org/docs/spec/client_server/r0.6.1#m-room-member
     pub fn membership_change(&self) -> MembershipChange {
@@ -320,7 +325,9 @@ impl SyncStateEvent<RoomMemberEventContent> {
 }
 
 impl StrippedStateEvent<RoomMemberEventContent> {
-    /// Helper function for membership change. Check [the specification][spec] for details.
+    /// Helper function for membership change.
+    ///
+    /// Check [the specification][spec] for details.
     ///
     /// [spec]: https://matrix.org/docs/spec/client_server/r0.6.1#m-room-member
     pub fn membership_change(&self) -> MembershipChange {

crates/ruma-events/src/room/message.rs

@@ -867,13 +867,11 @@ pub struct VideoInfo {
     pub duration: Option<UInt>,
 
     /// The height of the video in pixels.
-    #[serde(rename = "h")]
+    #[serde(rename = "h", skip_serializing_if = "Option::is_none")]
-    #[serde(skip_serializing_if = "Option::is_none")]
     pub height: Option<UInt>,
 
     /// The width of the video in pixels.
-    #[serde(rename = "w")]
+    #[serde(rename = "w", skip_serializing_if = "Option::is_none")]
-    #[serde(skip_serializing_if = "Option::is_none")]
     pub width: Option<UInt>,
 
     /// The mimetype of the video, e.g. "video/mp4".
@@ -905,8 +903,7 @@ pub struct VideoInfo {
     /// This uses the unstable prefix in
     /// [MSC2448](https://github.com/matrix-org/matrix-doc/pull/2448).
     #[cfg(feature = "unstable-pre-spec")]
-    #[serde(rename = "xyz.amorgan.blurhash")]
+    #[serde(rename = "xyz.amorgan.blurhash", skip_serializing_if = "Option::is_none")]
-    #[serde(skip_serializing_if = "Option::is_none")]
     pub blurhash: Option<String>,
 }
 

crates/ruma-events/src/room/third_party_invite.rs

@@ -16,22 +16,22 @@ use serde::{Deserialize, Serialize};
 pub struct RoomThirdPartyInviteEventContent {
     /// A user-readable string which represents the user who has been invited.
     ///
-    /// If you activate the `compat` feature, this field being absent in JSON will give you an
+    /// If you activate the `compat` feature, this field being absent in JSON will result in an
-    /// empty string here.
+    /// empty string here during deserialization.
     #[cfg_attr(feature = "compat", serde(default))]
     pub display_name: String,
 
     /// A URL which can be fetched to validate whether the key has been revoked.
     ///
-    /// If you activate the `compat` feature, this field being absent in JSON will give you an
+    /// If you activate the `compat` feature, this field being absent in JSON will result in an
-    /// empty string here.
+    /// empty string here during deserialization.
     #[cfg_attr(feature = "compat", serde(default))]
     pub key_validity_url: String,
 
     /// A Base64-encoded Ed25519 key with which the token must be signed.
     ///
-    /// If you activate the `compat` feature, this field being absent in JSON will give you an
+    /// If you activate the `compat` feature, this field being absent in JSON will result in an
-    /// empty string here.
+    /// empty string here during deserialization.
     #[cfg_attr(feature = "compat", serde(default))]
     pub public_key: String,
 

crates/ruma-events/src/room/tombstone.rs

@@ -14,8 +14,8 @@ use serde::{Deserialize, Serialize};
 pub struct RoomTombstoneEventContent {
     /// A server-defined message.
     ///
-    /// If you activate the `compat` feature, this field being absent in JSON will give you an
+    /// If you activate the `compat` feature, this field being absent in JSON will result in an
-    /// empty string here.
+    /// empty string here during deserialization.
     #[cfg_attr(feature = "compat", serde(default))]
     pub body: String,
 

crates/ruma-events/src/sticker.rs

@@ -13,15 +13,16 @@ use crate::room::ImageInfo;
 #[cfg_attr(not(feature = "unstable-exhaustive-types"), non_exhaustive)]
 #[ruma_event(type = "m.sticker", kind = Message)]
 pub struct StickerEventContent {
-    /// A textual representation or associated description of the sticker image. This could
+    /// A textual representation or associated description of the sticker image.
-    /// be the alt text of the original image, or a message to accompany and further
+    ///
+    /// This could be the alt text of the original image, or a message to accompany and further
     /// describe the sticker.
     pub body: String,
 
     /// Metadata about the image referred to in `url` including a thumbnail representation.
     pub info: ImageInfo,
 
-    /// The URL to the sticker image. This must be a valid `mxc://` URI.
+    /// The URL to the sticker image.
     pub url: MxcUri,
 }
 

crates/ruma-events/src/tag.rs

@@ -75,8 +75,9 @@ impl Error for InvalidUserTagName {}
 #[derive(Clone, Debug, PartialEq, Eq, PartialOrd, Ord)]
 #[cfg_attr(not(feature = "unstable-exhaustive-types"), non_exhaustive)]
 pub enum TagName {
-    /// `m.favourite`: The user's favorite rooms. These should be shown with higher precedence
+    /// `m.favourite`: The user's favorite rooms.
-    /// than other rooms.
+    ///
+    /// These should be shown with higher precedence than other rooms.
     Favorite,
 
     /// `m.lowpriority`: These should be shown with lower precedence than others.

crates/ruma-federation-api/src/device/get_devices/v1.rs

@@ -17,7 +17,9 @@ ruma_api! {
     }
 
     request: {
-        /// The user ID to retrieve devices for. Must be a user local to the receiving homeserver.
+        /// The user ID to retrieve devices for.
+        ///
+        /// Must be a user local to the receiving homeserver.
         #[ruma_api(path)]
         pub user_id: &'a UserId,
     }
@@ -26,12 +28,13 @@ ruma_api! {
         /// The user ID devices were requested for.
         pub user_id: UserId,
 
-        /// A unique ID for a given user_id which describes the version of the returned device
+        /// A unique ID for a given user_id which describes the version of the returned device list.
-        /// list. This is matched with the `stream_id` field in `m.device_list_update` EDUs in
+        ///
-        /// order to incrementally update the returned device_list.
+        /// This is matched with the `stream_id` field in `m.device_list_update` EDUs in order to
+        /// incrementally update the returned device_list.
         pub stream_id: UInt,
 
-        /// The user's devices. May be empty.
+        /// The user's devices.
         pub devices: Vec<UserDevice>,
     }
 }

crates/ruma-federation-api/src/discovery.rs

@@ -59,12 +59,14 @@ pub struct ServerSigningKeys {
     /// Public keys that the homeserver used to use and when it stopped using them.
     pub old_verify_keys: BTreeMap<ServerSigningKeyId, OldVerifyKey>,
 
-    /// Digital signatures of this object signed using the verify_keys. Map of
+    /// Digital signatures of this object signed using the verify_keys.
-    /// server name to keys by key ID
+    ///
+    /// Map of server name to keys by key ID
     pub signatures: BTreeMap<ServerNameBox, BTreeMap<ServerSigningKeyId, String>>,
 
-    /// Timestamp when the keys should be refreshed. This field MUST be ignored in room
+    /// Timestamp when the keys should be refreshed.
-    /// versions 1, 2, 3, and 4.
+    ///
+    /// This field MUST be ignored in room versions 1, 2, 3, and 4.
     pub valid_until_ts: MilliSecondsSinceUnixEpoch,
 }
 

crates/ruma-federation-api/src/discovery/get_server_version/v1.rs

@@ -46,7 +46,9 @@ pub struct Server {
     #[serde(skip_serializing_if = "Option::is_none")]
     pub name: Option<String>,
 
-    /// Version of this implementation. The version format depends on the implementation.
+    /// Version of this implementation.
+    ///
+    /// The version format depends on the implementation.
     #[serde(skip_serializing_if = "Option::is_none")]
     pub version: Option<String>,
 }

crates/ruma-federation-api/src/event/get_missing_events/v1.rs

@@ -21,15 +21,21 @@ ruma_api! {
         #[ruma_api(path)]
         pub room_id: &'a RoomId,
 
-        /// The maximum number of events to retrieve. Defaults to 10.
+        /// The maximum number of events to retrieve.
+        ///
+        /// Defaults to 10.
         #[serde(default = "default_limit", skip_serializing_if = "is_default_limit")]
         pub limit: UInt,
 
-        /// The minimum depth of events to retrieve. Defaults to 0.
+        /// The minimum depth of events to retrieve.
+        ///
+        /// Defaults to 0.
         #[serde(default, skip_serializing_if = "ruma_serde::is_default")]
         pub min_depth: UInt,
 
-        /// The latest event IDs that the sender already has. These are skipped when retrieving the previous events of `latest_events`.
+        /// The latest event IDs that the sender already has.
+        ///
+        /// These are skipped when retrieving the previous events of `latest_events`.
         pub earliest_events: &'a [EventId],
 
         /// The event IDs to retrieve the previous events for.

crates/ruma-federation-api/src/keys/get_keys/v1.rs

@@ -19,8 +19,9 @@ ruma_api! {
     }
 
     request: {
-        /// The keys to be downloaded. Gives all keys for a given user if the list of device ids is
+        /// The keys to be downloaded.
-        /// empty.
+        ///
+        /// Gives all keys for a given user if the list of device ids is empty.
         pub device_keys: BTreeMap<UserId, Vec<DeviceIdBox>>,
     }
 

crates/ruma-federation-api/src/membership/get_leave_event/v1.rs

@@ -26,12 +26,15 @@ ruma_api! {
     }
 
     response: {
-        /// The version of the room where the server is trying to leave. If not provided, the room
+        /// The version of the room where the server is trying to leave.
-        /// version is assumed to be either "1" or "2".
+        ///
+        /// If not provided, the room version is assumed to be either "1" or "2".
         pub room_version: Option<RoomVersionId>,
 
-        /// An unsigned template event. Note that events have a different format depending on the
+        /// An unsigned template event.
-        /// room version - check the room version specification for precise event formats.
+        ///
+        /// Note that events have a different format depending on the room version - check the room
+        /// version specification for precise event formats.
         pub event: Box<RawJsonValue>,
     }
 }

crates/ruma-federation-api/src/query/get_profile_information/v1.rs

@@ -33,8 +33,8 @@ ruma_api! {
 
         /// Avatar URL for the user's avatar.
         ///
-        /// If you activate the `compat` feature, this field being an empty string in JSON will give
+        /// If you activate the `compat` feature, this field being an empty string in JSON will result
-        /// you `None` here.
+        /// in `None` here during deserialization.
         #[serde(skip_serializing_if = "Option::is_none")]
         #[cfg_attr(
             feature = "compat",
@@ -47,8 +47,7 @@ ruma_api! {
         /// This uses the unstable prefix in
         /// [MSC2448](https://github.com/matrix-org/matrix-doc/pull/2448).
         #[cfg(feature = "unstable-pre-spec")]
-        #[serde(rename = "xyz.amorgan.blurhash")]
+        #[serde(rename = "xyz.amorgan.blurhash", skip_serializing_if = "Option::is_none")]
-        #[serde(skip_serializing_if = "Option::is_none")]
         pub blurhash: Option<String>,
     }
 }

crates/ruma-federation-api/src/thirdparty/bind_callback/v1.rs

@@ -59,7 +59,9 @@ impl<'a> Request<'a> {
 #[derive(Debug, Clone, Deserialize, Serialize)]
 #[cfg_attr(not(feature = "unstable-exhaustive-types"), non_exhaustive)]
 pub struct ThirdPartyInvite {
-    /// The type of third party invite issues. Currently only "email" is used.
+    /// The type of third party invite issues.
+    ///
+    /// Currently only `Medium::Email` is used.
     pub medium: Medium,
 
     /// The third party identifier that received the invite.

crates/ruma-federation-api/src/thirdparty/exchange_invite/v1.rs

@@ -19,7 +19,9 @@ ruma_api! {
         #[ruma_api(path)]
         pub room_id: &'a RoomId,
 
-        /// The event type. Must be `m.room.member`.
+        /// The event type.
+        ///
+        /// Must be `EventType::RoomMember`.
         #[serde(rename = "type")]
         pub kind: EventType,
 

crates/ruma-federation-api/src/transactions/edu.rs

@@ -107,7 +107,9 @@ pub struct PresenceUpdate {
     /// The number of milliseconds that have elapsed since the user last did something.
     pub last_active_ago: UInt,
 
-    /// Whether or not the user is currently active. Defaults to false.
+    /// Whether or not the user is currently active.
+    ///
+    /// Defaults to false.
     #[serde(default)]
     pub currently_active: bool,
 }
@@ -206,15 +208,17 @@ pub struct DeviceListUpdateContent {
     /// The ID of the device whose details are changing.
     pub device_id: DeviceIdBox,
 
-    /// The public human-readable name of this device. Will be absent if the device has no name.
+    /// The public human-readable name of this device.
+    ///
+    /// Will be absent if the device has no name.
     #[serde(skip_serializing_if = "Option::is_none")]
     pub device_display_name: Option<String>,
 
     /// An ID sent by the server for this update, unique for a given user_id.
     pub stream_id: UInt,
 
-    /// The stream_ids of any prior m.device_list_update EDUs sent for this user
+    /// The stream_ids of any prior m.device_list_update EDUs sent for this user which have not
-    /// which have not been referred to already in an EDU's prev_id field.
+    /// been referred to already in an EDU's prev_id field.
     #[serde(default, skip_serializing_if = "Vec::is_empty")]
     pub prev_id: Vec<UInt>,
 

crates/ruma-identifiers/src/event_id.rs

@@ -51,11 +51,10 @@ impl fmt::Debug for EventId {
 
 impl EventId {
     /// Attempts to generate an `EventId` for the given origin server with a localpart consisting
-    /// of 18 random ASCII characters. This should only be used for events in the original format
+    /// of 18 random ASCII characters.
-    /// as used by Matrix room versions 1 and 2.
     ///
-    /// Does not currently ever fail, but may fail in the future if the homeserver cannot be parsed
+    /// This should only be used for events in the original format  as used by Matrix room versions
-    /// parsed as a valid host.
+    /// 1 and 2.
     #[cfg(feature = "rand")]
     pub fn new(server_name: &ServerName) -> Self {
         use crate::generate_localpart;
@@ -65,9 +64,11 @@ impl EventId {
         Self { full_id, colon_idx: NonZeroU8::new(19) }
     }
 
-    /// Returns the event's unique ID. For the original event format as used by Matrix room
+    /// Returns the event's unique ID.
-    /// versions 1 and 2, this is the "localpart" that precedes the homeserver. For later formats,
+    ///
-    /// this is the entire ID without the leading $ sigil.
+    /// For the original event format as used by Matrix room versions 1 and 2, this is the
+    /// "localpart" that precedes the homeserver. For later formats, this is the entire ID without
+    /// the leading `$` sigil.
     pub fn localpart(&self) -> &str {
         let idx = match self.colon_idx {
             Some(idx) => idx.get() as usize,

crates/ruma-identity-service-api/src/association/email/create_email_validation_session/v2.rs

@@ -32,7 +32,9 @@ ruma_api! {
     }
 
     response: {
-        /// The session ID. Session IDs are opaque strings generated by the identity server.
+        /// The session ID.
+        ///
+        /// Session IDs are opaque strings generated by the identity server.
         pub sid: SessionIdBox,
     }
 }

crates/ruma-identity-service-api/src/association/msisdn/create_msisdn_validation_session/v2.rs

@@ -37,7 +37,9 @@ ruma_api! {
     }
 
     response: {
-        /// The session ID. Session IDs are opaque strings generated by the identity server.
+        /// The session ID.
+        ///
+        /// Session IDs are opaque strings generated by the identity server.
         pub sid: SessionIdBox,
     }
 }

crates/ruma-identity-service-api/src/association/unbind_3pid/v2.rs

@@ -20,15 +20,16 @@ ruma_api! {
         ///
         /// If this is not provided, the request must be signed by the homeserver which controls
         /// the `mxid`.
-        #[serde(flatten)]
+        #[serde(flatten, skip_serializing_if = "Option::is_none")]
-        #[serde(skip_serializing_if = "Option::is_none")]
         pub threepid_ownership_proof: Option<&'a ThreePidOwnershipProof>,
 
         /// The Matrix user ID to remove from the 3PIDs.
         pub mxid: &'a UserId,
 
-        /// The 3PID to remove. Must match the 3PID used to generate the session if using `sid` and
+        /// The 3PID to remove.
-        /// `client_secret` to authenticate this request.
+        ///
+        /// Must match the 3PID used to generate the session if using `sid` and `client_secret` to
+        /// authenticate this request.
         pub threepid:  &'a ThirdPartyId,
     }
 

crates/ruma-identity-service-api/src/authentication/register/v2.rs

@@ -17,15 +17,18 @@ ruma_api! {
     }
 
     request: {
-        /// An access token the consumer may use to verify the identity of the
+        /// An access token the consumer may use to verify the identity of the person who generated
-        /// person who generated the token. This is given to the federation API
+        /// the token.
-        /// GET /openid/userinfo to verify the user's identity.
+        ///
+        /// This is given to the federation API `GET /openid/userinfo` to verify the user's
+        /// identity.
         pub access_token: &'a str,
 
         /// The string `Bearer`.
         pub token_type: TokenType,
 
-        /// The homeserver domain the consumer should use when attempting to verify the user's identity.
+        /// The homeserver domain the consumer should use when attempting to verify the user's
+        /// identity.
         pub matrix_server_name: &'a ServerName,
 
         /// The number of seconds before this token expires and a new one must be generated.
@@ -34,7 +37,8 @@ ruma_api! {
     }
 
     response: {
-        /// An opaque string representing the token to authenticate future requests to the identity server with.
+        /// An opaque string representing the token to authenticate future requests to the identity
+        /// server with.
         pub token: String,
     }
 }

crates/ruma-identity-service-api/src/invitation/store_invitation/v2.rs

@@ -64,15 +64,18 @@ ruma_api! {
     }
 
     response: {
-        /// The generated token. Must be a string consisting of the characters `[0-9a-zA-Z.=_-]`.
+        /// The generated token.
         ///
-        /// Its length must not exceed 255 characters and it must not be empty.
+        /// Must be a string consisting of the characters `[0-9a-zA-Z.=_-]`. Its length must not
+        /// exceed 255 characters and it must not be empty.
         pub token: String,
 
         /// A list of [server's long-term public key, generated ephemeral public key].
         pub public_keys: PublicKeys,
 
-        /// The generated (redacted) display_name. An example is `f...@b...`.
+        /// The generated (redacted) display_name.
+        ///
+        /// An example is `f...@b...`.
         pub display_name: String,
     }
 }

crates/ruma-identity-service-api/src/lookup/get_hash_parameters/v2.rs

@@ -23,7 +23,9 @@ ruma_api! {
         /// Servers SHOULD rotate this string often.
         pub lookup_pepper: String,
 
-        /// The algorithms the server supports. Must contain at least `sha256`.
+        /// The algorithms the server supports.
+        ///
+        /// Must contain at least `sha256`.
         pub algorithms: Vec<IdentifierHashingAlgorithm>,
     }
 }

crates/ruma-identity-service-api/src/lookup/lookup_3pid/v2.rs

@@ -26,15 +26,18 @@ ruma_api! {
         /// make use of it.
         pub pepper: &'a str,
 
-        /// The addresses to look up. The format of the entries here depend on the `algorithm`
+        /// The addresses to look up.
-        /// used. Note that queries which have been incorrectly hashed or formatted will lead to no
+        ///
-        /// matches.
+        /// The format of the entries here depend on the `algorithm` used. Note that queries which
+        /// have been incorrectly hashed or formatted will lead to no matches.
         pub addresses: &'a [String],
     }
 
     response: {
-        /// Any applicable mappings of `addresses` to Matrix User IDs. Addresses which do not have
+        /// Any applicable mappings of `addresses` to Matrix User IDs.
-        /// associations will not be included, which can make this property be an empty object.
+        ///
+        /// Addresses which do not have associations will not be included, which can make this
+        /// property be an empty object.
         pub mappings: BTreeMap<String, UserId>,
     }
 }

crates/ruma-push-gateway-api/src/send_event_notification/v1.rs

@@ -204,14 +204,16 @@ pub struct Device {
     #[serde(skip_serializing_if = "Option::is_none")]
     pub pushkey_ts: Option<SecondsSinceUnixEpoch>,
 
-    /// A dictionary of additional pusher-specific data. For 'http' pushers,
+    /// A dictionary of additional pusher-specific data.
-    /// this is the data dictionary passed in at pusher creation minus the `url`
+    ///
-    /// key.
+    /// For 'http' pushers, this is the data dictionary passed in at pusher creation minus the
+    /// `url` key.
     #[serde(skip_serializing_if = "Option::is_none")]
     pub data: Option<PusherData>,
 
-    /// A dictionary of customisations made to the way this notification is to
+    /// A dictionary of customisations made to the way this notification is to be presented.
-    /// be presented. These are added by push rules.
+    ///
+    /// These are added by push rules.
     #[serde(with = "tweak_serde", skip_serializing_if = "Vec::is_empty")]
     pub tweaks: Vec<Tweak>,
 }

crates/ruma-serde-macros/src/lib.rs

@@ -27,8 +27,10 @@ mod serialize_as_ref_str;
 mod util;
 
 /// Derive the `Outgoing` trait, possibly generating an 'Incoming' version of the struct this
-/// derive macro is used on. Specifically, if no lifetime variables are used on any of the fields
+/// derive macro is used on.
-/// of the struct, this simple implementation will be generated:
+///
+/// Specifically, if no lifetime variables are used on any of the fields of the struct, this simple
+/// implementation will be generated:
 ///
 /// ```ignore
 /// # // TODO: "ignore" this doctest until it is more extensively documented. (See #541)

crates/ruma-signatures/src/functions.rs

@@ -767,8 +767,10 @@ pub fn redact(
     Ok(event)
 }
 
-/// Extracts the server names to check signatures for given event. It will return the sender's
+/// Extracts the server names to check signatures for given event.
-/// server (unless it's a third party invite) and the event id server (on v1 and v2 room versions)
+///
+/// It will return the sender's server (unless it's a third party invite) and the event id server
+/// (on v1 and v2 room versions)
 fn servers_to_check_signatures(
     object: &CanonicalJsonObject,
     version: &RoomVersionId,

crates/ruma-state-res/src/lib.rs

@@ -33,8 +33,10 @@ pub type StateMap<T> = HashMap<(EventType, String), T>;
 /// A mapping of `EventId` to `T`, usually a `ServerPdu`.
 type EventMap<T> = HashMap<EventId, T>;
 
-/// Resolve sets of state events as they come in. Internally `StateResolution` builds a graph and an
+/// Resolve sets of state events as they come in.
-/// auth chain to allow for state conflict resolution.
+///
+/// Internally `StateResolution` builds a graph and an auth chain to allow for state conflict
+/// resolution.
 ///
 /// ## Arguments
 ///

xtask/src/cargo.rs

@@ -79,8 +79,9 @@ impl Package {
         Ok(())
     }
 
-    /// Get the changes for the version. If `update` is `true`, update the changelog for the release
+    /// Get the changes for the version.
-    /// of the given version.
+    ///
+    /// If `update` is `true`, update the changelog for the release of the given version.
     pub fn changes(&self, update: bool) -> Result<String> {
         let mut changelog_path = self.manifest_path.clone();
         changelog_path.set_file_name("CHANGELOG.md");

xtask/src/util.rs

@@ -2,7 +2,9 @@ use std::io::{stdin, stdout, BufRead, Write};
 
 use crate::Result;
 
-/// Ask the user the given yes or no question and wait for their input. Returns `true` for yes.
+/// Ask the user the given yes or no question and wait for their input.
+///
+/// Returns `true` for yes.
 pub fn ask_yes_no(question: &str) -> Result<bool> {
     let mut input = String::new();
     let stdin = stdin();