Clean up and rewrap documentation comments

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

@@ -20,7 +20,7 @@ ruma_api! {
 
     response: {
         /// An array containing the current pushers for the user.
-        pub pushers: Vec<Pusher>
+        pub pushers: Vec<Pusher>,
     }
 
     error: crate::Error
@@ -47,13 +47,17 @@ impl Response {
 #[derive(Clone, Debug, Serialize, Deserialize)]
 #[cfg_attr(not(feature = "unstable-exhaustive-types"), non_exhaustive)]
 pub struct Pusher {
-    /// This is a unique identifier for this pusher. Max length, 512 bytes.
+    /// A unique identifier for this pusher.
+    ///
+    /// The maximum allowed length is 512 bytes.
     pub pushkey: String,
 
     /// The kind of the pusher.
     pub kind: PusherKind,
 
-    /// This is a reverse-DNS style identifier for the application. Max length, 64 chars.
+    /// A reverse-DNS style identifier for the application.
+    ///
+    /// The maximum allowed lenght is 64 bytes.
     pub app_id: String,
 
     /// A string that will allow the user to identify what application owns this pusher.
@@ -62,7 +66,7 @@ pub struct Pusher {
     /// A string that will allow the user to identify what device owns this pusher.
     pub device_display_name: String,
 
-    /// This string determines which set of device specific rules this pusher executes.
+    /// Determines which set of device specific rules this pusher executes.
     #[serde(skip_serializing_if = "Option::is_none")]
     pub profile_tag: Option<String>,
 
@@ -80,13 +84,17 @@ pub struct Pusher {
 #[derive(Debug)]
 #[allow(clippy::exhaustive_structs)]
 pub struct PusherInit {
-    /// This is a unique identifier for this pusher. Max length, 512 bytes.
+    /// A unique identifier for this pusher.
+    ///
+    /// The maximum allowed length is 512 bytes.
     pub pushkey: String,
 
-    /// The kind of the pusher. `None` deletes the pusher.
+    /// The kind of the pusher.
     pub kind: PusherKind,
 
-    /// This is a reverse-DNS style identifier for the application. Max length, 64 chars.
+    /// A reverse-DNS style identifier for the application.
+    ///
+    /// The maximum allowed length is 64 bytes.
     pub app_id: String,
 
     /// A string that will allow the user to identify what application owns this pusher.
@@ -95,10 +103,10 @@ pub struct PusherInit {
     /// A string that will allow the user to identify what device owns this pusher.
     pub device_display_name: String,
 
-    /// This string determines which set of device specific rules this pusher executes.
+    /// Determines which set of device-specific rules this pusher executes.
     pub profile_tag: Option<String>,
 
-    /// The preferred language for receiving notifications (e.g. 'en' or 'en-US')
+    /// The preferred language for receiving notifications (e.g. 'en' or 'en-US').
     pub lang: String,
 
     /// Information for the pusher implementation itself.

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

@@ -54,13 +54,19 @@ impl Response {
 #[derive(Clone, Debug, Serialize, Deserialize)]
 #[cfg_attr(not(feature = "unstable-exhaustive-types"), non_exhaustive)]
 pub struct Pusher {
-    /// This is a unique identifier for this pusher. Max length, 512 bytes.
+    /// A unique identifier for this pusher.
+    ///
+    /// The maximum allowed length is 512 bytes.
     pub pushkey: String,
 
-    /// The kind of the pusher. `None` deletes the pusher.
+    /// The kind of the pusher.
+    ///
+    /// `None` deletes the pusher.
     pub kind: Option<PusherKind>,
 
-    /// This is a reverse-DNS style identifier for the application. Max length, 64 chars.
+    /// A reverse-DNS style identifier for the application.
+    ///
+    /// The maximum allowed length is 64 bytes.
     pub app_id: String,
 
     /// A string that will allow the user to identify what application owns this pusher.
@@ -69,7 +75,7 @@ pub struct Pusher {
     /// A string that will allow the user to identify what device owns this pusher.
     pub device_display_name: String,
 
-    /// This string determines which set of device specific rules this pusher executes.
+    /// Determines which set of device specific rules this pusher executes.
     #[serde(skip_serializing_if = "Option::is_none")]
     pub profile_tag: Option<String>,
 
@@ -87,13 +93,19 @@ pub struct Pusher {
 #[derive(Debug)]
 #[allow(clippy::exhaustive_structs)]
 pub struct PusherInit {
-    /// This is a unique identifier for this pusher. Max length, 512 bytes.
+    /// A unique identifier for this pusher.
+    ///
+    /// The maximum allowed length is 512 bytes.
     pub pushkey: String,
 
-    /// The kind of the pusher. `None` deletes the pusher.
+    /// The kind of the pusher.
+    ///
+    /// `None` deletes the pusher.
     pub kind: Option<PusherKind>,
 
-    /// This is a reverse-DNS style identifier for the application. Max length, 64 chars.
+    /// A reverse-DNS style identifier for the application.
+    ///
+    /// The maximum allowed length is 64 bytes.
     pub app_id: String,
 
     /// A string that will allow the user to identify what application owns this pusher.
@@ -102,7 +114,7 @@ pub struct PusherInit {
     /// A string that will allow the user to identify what device owns this pusher.
     pub device_display_name: String,
 
-    /// This string determines which set of device specific rules this pusher executes.
+    /// Determines which set of device specific rules this pusher executes.
     pub profile_tag: Option<String>,
 
     /// The preferred language for receiving notifications (e.g. 'en' or 'en-US')

crates/ruma-client-api/src/r0/read_marker/set_read_marker.rs

@@ -19,13 +19,15 @@ ruma_api! {
         pub room_id: &'a RoomId,
 
         /// The event ID the read marker should be located at.
+        ///
         /// The event MUST belong to the room.
         #[serde(rename = "m.fully_read")]
         pub fully_read: &'a EventId,
 
         /// The event ID to set the read receipt location at.
-        /// This is equivalent to calling the create_read_receipt endpoint and is
+        ///
-        /// provided here to save that extra call.
+        /// This is equivalent to calling the create_read_receipt endpoint and is provided here to
+        /// save that extra call.
         #[serde(rename = "m.read", skip_serializing_if = "Option::is_none")]
         pub read_receipt: Option<&'a EventId>,
     }

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

@@ -19,7 +19,7 @@ pub use room_member_count_is::{ComparisonOperator, RoomMemberCountIs};
 #[cfg_attr(not(feature = "unstable-exhaustive-types"), non_exhaustive)]
 #[serde(tag = "kind", rename_all = "snake_case")]
 pub enum PushCondition {
-    /// This is a glob pattern match on a field of the event.
+    /// A glob pattern match on a field of the event.
     EventMatch {
         /// The dot-separated field of the event to match.
         key: String,
@@ -31,18 +31,18 @@ pub enum PushCondition {
         pattern: String,
     },
 
-    /// This matches unencrypted messages where `content.body` contains the owner's display name in
+    /// Matches unencrypted messages where `content.body` contains the owner's display name in that
-    /// that room.
+    /// room.
     ContainsDisplayName,
 
-    /// This matches the current number of members in the room.
+    /// Matches the current number of members in the room.
     RoomMemberCount {
         /// The condition on the current number of members in the room.
         is: RoomMemberCountIs,
     },
 
-    /// This takes into account the current power levels in the room, ensuring the sender of the
+    /// Takes into account the current power levels in the room, ensuring the sender of the event
-    /// event has high enough power to trigger the notification.
+    /// has high enough power to trigger the notification.
     SenderNotificationPermission {
         /// The field in the power level event the user needs a minimum power level for.
         ///

crates/ruma-events-macros/src/event.rs

@@ -445,7 +445,7 @@ fn expand_eq_ord_event(input: &DeriveInput, fields: &[Field]) -> Option<TokenStr
         quote! {
             #[automatically_derived]
             impl #impl_gen ::std::cmp::PartialEq for #ident #ty_gen #where_clause {
-                /// This checks if two `EventId`s are equal.
+                /// Checks if two `EventId`s are equal.
                 fn eq(&self, other: &Self) -> ::std::primitive::bool {
                     self.event_id == other.event_id
                 }
@@ -456,7 +456,7 @@ fn expand_eq_ord_event(input: &DeriveInput, fields: &[Field]) -> Option<TokenStr
 
             #[automatically_derived]
             impl #impl_gen ::std::cmp::PartialOrd for #ident #ty_gen #where_clause {
-                /// This compares `EventId`s and orders them lexicographically.
+                /// Compares `EventId`s and orders them lexicographically.
                 fn partial_cmp(&self, other: &Self) -> ::std::option::Option<::std::cmp::Ordering> {
                     self.event_id.partial_cmp(&other.event_id)
                 }
@@ -464,7 +464,7 @@ fn expand_eq_ord_event(input: &DeriveInput, fields: &[Field]) -> Option<TokenStr
 
             #[automatically_derived]
             impl #impl_gen ::std::cmp::Ord for #ident #ty_gen #where_clause {
-                /// This compares `EventId`s and orders them lexicographically.
+                /// Compares `EventId`s and orders them lexicographically.
                 fn cmp(&self, other: &Self) -> ::std::cmp::Ordering {
                     self.event_id.cmp(&other.event_id)
                 }

crates/ruma-events-macros/src/event_content.rs

@@ -31,8 +31,8 @@ enum EventMeta {
     /// redacted.
     SkipRedacted,
 
-    /// This attribute signals that the events redacted form is manually implemented and should
+    /// This attribute signals that the events redacted form is manually implemented and should not
-    /// not be generated.
+    /// be generated.
     CustomRedacted,
 }
 

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

@@ -36,8 +36,8 @@ impl HangupEventContent {
 
 /// A reason for a hangup.
 ///
-/// This should not be provided when the user naturally ends or rejects the call. When there was an
+/// Should not be provided when the user naturally ends or rejects the call. When there was an error
-/// error in the call negotiation, this should be `ice_failed` for when ICE negotiation fails or
+/// in the call negotiation, this should be `ice_failed` for when ICE negotiation fails or
 /// `invite_timeout` for when the other party did not answer in time.
 ///
 /// This type can hold an arbitrary string. To check for formats that are not available as a

crates/ruma-events/src/dummy.rs

@@ -10,7 +10,7 @@ use serde::{
 
 /// The payload for `DummyEvent`.
 ///
-/// This event type is used to indicate new Olm sessions for end-to-end encryption.
+/// This event is used to indicate new Olm sessions for end-to-end encryption.
 ///
 /// Typically it is encrypted as an *m.room.encrypted* event, then sent as a to-device event.
 ///

crates/ruma-events/src/event_kinds.rs

@@ -44,9 +44,8 @@ pub struct SyncEphemeralRoomEvent<C: EphemeralRoomEventContent> {
 
 /// A message event.
 ///
-/// `MessageEvent` implements the comparison traits using only
+/// `MessageEvent` implements the comparison traits using only the `event_id` field, a sorted list
-/// the `event_id` field, a sorted list would be sorted lexicographically based on
+/// would be sorted lexicographically based on the event's `EventId`.
-/// the event's `EventId`.
 #[derive(Clone, Debug, Event)]
 pub struct MessageEvent<C: MessageEventContent> {
     /// Data specific to the event type.
@@ -70,9 +69,8 @@ pub struct MessageEvent<C: MessageEventContent> {
 
 /// A message event without a `room_id`.
 ///
-/// `SyncMessageEvent` implements the comparison traits using only
+/// `SyncMessageEvent` implements the comparison traits using only the `event_id` field, a sorted
-/// the `event_id` field, a sorted list would be sorted lexicographically based on
+/// list would be sorted lexicographically based on the event's `EventId`.
-/// the event's `EventId`.
 #[derive(Clone, Debug, Event)]
 pub struct SyncMessageEvent<C: MessageEventContent> {
     /// Data specific to the event type.
@@ -93,9 +91,8 @@ pub struct SyncMessageEvent<C: MessageEventContent> {
 
 /// A redacted message event.
 ///
-/// `RedactedMessageEvent` implements the comparison traits using only
+/// `RedactedMessageEvent` implements the comparison traits using only the `event_id` field, a
-/// the `event_id` field, a sorted list would be sorted lexicographically based on
+/// sorted list would be sorted lexicographically based on the event's `EventId`.
-/// the event's `EventId`.
 #[derive(Clone, Debug, Event)]
 pub struct RedactedMessageEvent<C: RedactedMessageEventContent> {
     /// Data specific to the event type.
@@ -119,13 +116,11 @@ pub struct RedactedMessageEvent<C: RedactedMessageEventContent> {
 
 /// A redacted message event without a `room_id`.
 ///
-/// `RedactedSyncMessageEvent` implements the comparison traits using only
+/// `RedactedSyncMessageEvent` implements the comparison traits using only the `event_id` field, a
-/// the `event_id` field, a sorted list would be sorted lexicographically based on
+/// sorted list would be sorted lexicographically based on the event's `EventId`.
-/// the event's `EventId`.
 #[derive(Clone, Debug, Event)]
 pub struct RedactedSyncMessageEvent<C: RedactedMessageEventContent> {
     /// Data specific to the event type.
-    // #[serde(default, skip_serializing_if = "is_zst")]
     pub content: C,
 
     /// The globally unique event identifier for the user who sent the event.
@@ -143,9 +138,8 @@ pub struct RedactedSyncMessageEvent<C: RedactedMessageEventContent> {
 
 /// A state event.
 ///
-/// `StateEvent` implements the comparison traits using only
+/// `StateEvent` implements the comparison traits using only the `event_id` field, a sorted list
-/// the `event_id` field, a sorted list would be sorted lexicographically based on
+/// would be sorted lexicographically based on the event's `EventId`.
-/// the event's `EventId`.
 #[derive(Clone, Debug, Event)]
 pub struct StateEvent<C: StateEventContent> {
     /// Data specific to the event type.
@@ -165,8 +159,8 @@ pub struct StateEvent<C: StateEventContent> {
 
     /// A unique key which defines the overwriting semantics for this piece of room state.
     ///
-    /// This is often an empty string, but some events send a `UserId` to show
+    /// This is often an empty string, but some events send a `UserId` to show which user the event
-    /// which user the event affects.
+    /// affects.
     pub state_key: String,
 
     /// Optional previous content for this event.
@@ -178,9 +172,8 @@ pub struct StateEvent<C: StateEventContent> {
 
 /// A state event without a `room_id`.
 ///
-/// `SyncStateEvent` implements the comparison traits using only
+/// `SyncStateEvent` implements the comparison traits using only the `event_id` field, a sorted list
-/// the `event_id` field, a sorted list would be sorted lexicographically based on
+/// would be sorted lexicographically based on the event's `EventId`.
-/// the event's `EventId`.
 #[derive(Clone, Debug, Event)]
 pub struct SyncStateEvent<C: StateEventContent> {
     /// Data specific to the event type.
@@ -197,8 +190,8 @@ pub struct SyncStateEvent<C: StateEventContent> {
 
     /// A unique key which defines the overwriting semantics for this piece of room state.
     ///
-    /// This is often an empty string, but some events send a `UserId` to show
+    /// This is often an empty string, but some events send a `UserId` to show which user the event
-    /// which user the event affects.
+    /// affects.
     pub state_key: String,
 
     /// Optional previous content for this event.
@@ -208,8 +201,7 @@ pub struct SyncStateEvent<C: StateEventContent> {
     pub unsigned: Unsigned,
 }
 
-/// A stripped-down state event, used for previews of rooms the user has been
+/// A stripped-down state event, used for previews of rooms the user has been invited to.
-/// invited to.
 #[derive(Clone, Debug, Event)]
 pub struct StrippedStateEvent<C: StateEventContent> {
     /// Data specific to the event type.
@@ -220,8 +212,8 @@ pub struct StrippedStateEvent<C: StateEventContent> {
 
     /// A unique key which defines the overwriting semantics for this piece of room state.
     ///
-    /// This is often an empty string, but some events send a `UserId` to show
+    /// This is often an empty string, but some events send a `UserId` to show which user the event
-    /// which user the event affects.
+    /// affects.
     pub state_key: String,
 }
 
@@ -233,8 +225,8 @@ pub struct InitialStateEvent<C: StateEventContent> {
 
     /// A unique key which defines the overwriting semantics for this piece of room state.
     ///
-    /// This is often an empty string, but some events send a `UserId` to show
+    /// This is often an empty string, but some events send a `UserId` to show which user the event
-    /// which user the event affects.
+    /// affects.
     ///
     /// Defaults to the empty string.
     #[ruma_event(default)]
@@ -243,9 +235,8 @@ pub struct InitialStateEvent<C: StateEventContent> {
 
 /// A redacted state event.
 ///
-/// `RedactedStateEvent` implements the comparison traits using only
+/// `RedactedStateEvent` implements the comparison traits using only the `event_id` field, a sorted
-/// the `event_id` field, a sorted list would be sorted lexicographically based on
+/// list would be sorted lexicographically based on the event's `EventId`.
-/// the event's `EventId`.
 #[derive(Clone, Debug, Event)]
 pub struct RedactedStateEvent<C: RedactedStateEventContent> {
     /// Data specific to the event type.
@@ -265,8 +256,8 @@ pub struct RedactedStateEvent<C: RedactedStateEventContent> {
 
     /// A unique key which defines the overwriting semantics for this piece of room state.
     ///
-    /// This is often an empty string, but some events send a `UserId` to show
+    /// This is often an empty string, but some events send a `UserId` to show which user the event
-    /// which user the event affects.
+    /// affects.
     pub state_key: String,
 
     /// Additional key-value pairs not signed by the homeserver.
@@ -275,13 +266,11 @@ pub struct RedactedStateEvent<C: RedactedStateEventContent> {
 
 /// A redacted state event without a `room_id`.
 ///
-/// `RedactedSyncStateEvent` implements the comparison traits using only
+/// `RedactedSyncStateEvent` implements the comparison traits using only the `event_id` field, a
-/// the `event_id` field, a sorted list would be sorted lexicographically based on
+/// sorted list would be sorted lexicographically based on the event's `EventId`.
-/// the event's `EventId`.
 #[derive(Clone, Debug, Event)]
 pub struct RedactedSyncStateEvent<C: RedactedStateEventContent> {
     /// Data specific to the event type.
-    // #[serde(default, skip_serializing_if = "is_zst")]
     pub content: C,
 
     /// The globally unique event identifier for the user who sent the event.
@@ -295,8 +284,8 @@ pub struct RedactedSyncStateEvent<C: RedactedStateEventContent> {
 
     /// A unique key which defines the overwriting semantics for this piece of room state.
     ///
-    /// This is often an empty string, but some events send a `UserId` to show
+    /// This is often an empty string, but some events send a `UserId` to show which user the event
-    /// which user the event affects.
+    /// affects.
     pub state_key: String,
 
     /// Additional key-value pairs not signed by the homeserver.
@@ -314,8 +303,8 @@ pub struct RedactedStrippedStateEvent<C: RedactedStateEventContent> {
 
     /// A unique key which defines the overwriting semantics for this piece of room state.
     ///
-    /// This is often an empty string, but some events send a `UserId` to show
+    /// This is often an empty string, but some events send a `UserId` to show which user the event
-    /// which user the event affects.
+    /// affects.
     pub state_key: String,
 }
 

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

@@ -92,8 +92,8 @@ pub enum CancelCode {
 
     /// The device does not know how to handle the requested method.
     ///
-    /// This should be sent for *m.key.verification.start* messages and messages defined by
+    /// Should be sent for *m.key.verification.start* messages and messages defined by individual
-    /// individual verification processes.
+    /// verification processes.
     #[ruma_enum(rename = "m.unknown_method")]
     UnknownMethod,
 

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

@@ -7,8 +7,9 @@ use serde::{Deserialize, Serialize};
 
 use crate::StateEvent;
 
-/// This is the first event in a room and cannot be changed. It acts as the root of all other
+/// This is the first event in a room and cannot be changed.
-/// events.
+///
+/// It acts as the root of all other events.
 pub type CreateEvent = StateEvent<CreateEventContent>;
 
 /// The payload for `CreateEvent`.

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

@@ -501,7 +501,7 @@ impl FileInfo {
 pub struct ImageMessageEventContent {
     /// A textual representation of the image.
     ///
-    /// This could be the alt text of the image, the filename of the image, or some kind of content
+    /// Could be the alt text of the image, the filename of the image, or some kind of content
     /// description for accessibility e.g. "image attachment".
     pub body: String,
 

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

@@ -13,28 +13,29 @@ pub type ServerAclEvent = StateEvent<ServerAclEventContent>;
 #[cfg_attr(not(feature = "unstable-exhaustive-types"), non_exhaustive)]
 #[ruma_event(type = "m.room.server_acl", kind = State)]
 pub struct ServerAclEventContent {
-    /// True to allow server names that are IP address literals. False to deny.
+    /// Whether to allow server names that are IP address literals.
     ///
-    /// This is strongly recommended to be set to false as servers running with IP literal
+    /// This is strongly recommended to be set to false as servers running with IP literal names
-    /// names are strongly discouraged in order to require legitimate homeservers to be
+    /// are strongly discouraged in order to require legitimate homeservers to be backed by a
-    /// backed by a valid registered domain name.
+    /// valid registered domain name.
     #[serde(default = "ruma_serde::default_true", skip_serializing_if = "ruma_serde::is_true")]
     pub allow_ip_literals: bool,
 
-    /// The server names to allow in the room, excluding any port information. Wildcards may
+    /// The server names to allow in the room, excluding any port information.
-    /// be used to cover a wider range of hosts, where `*` matches zero or more characters
-    /// and `?` matches exactly one character.
     ///
-    /// **This defaults to an empty list when not provided, effectively disallowing every
+    /// Wildcards may be used to cover a wider range of hosts, where `*` matches zero or more
-    /// server.**
+    /// characters and `?` matches exactly one character.
+    ///
+    /// **Defaults to an empty list when not provided, effectively disallowing every server.**
     #[serde(default, skip_serializing_if = "Vec::is_empty")]
     pub allow: Vec<String>,
 
-    /// The server names to disallow in the room, excluding any port information. Wildcards may
+    /// The server names to disallow in the room, excluding any port information.
-    /// be used to cover a wider range of hosts, where * matches zero or more characters and ?
-    /// matches exactly one character.
     ///
-    /// This defaults to an empty list when not provided.
+    /// Wildcards may be used to cover a wider range of hosts, where * matches zero or more
+    /// characters and `?` matches exactly one character.
+    ///
+    /// Defaults to an empty list when not provided.
     #[serde(default, skip_serializing_if = "Vec::is_empty")]
     pub deny: Vec<String>,
 }