chris/ruwuma
1
0
Fork 0
Code Issues Pull Requests Actions 1 Packages Projects Releases Wiki Activity

Clean up and rewrap documentation comments

Browse Source
This commit is contained in:
Jonas Platte 2021-08-27 21:32:02 +02:00
parent f32e0babe9
commit 46c7e3f811
No known key found for this signature in database
GPG Key ID: CC154DE0E30B7C67
13 changed files with 106 additions and 93 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

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

@ -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.

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

@ -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')

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

@ -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>,
}

12
crates/ruma-common/src/push/condition.rs
View File

@ -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
/// that room.
/// Matches unencrypted messages where `content.body` contains the owner's display name in that
/// 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
/// event has high enough power to trigger the notification.
/// Takes into account the current power levels in the room, ensuring the sender of the event
/// has high enough power to trigger the notification.
SenderNotificationPermission {
/// The field in the power level event the user needs a minimum power level for.
///

6
crates/ruma-events-macros/src/event.rs
View File

@ -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)
}

4
crates/ruma-events-macros/src/event_content.rs
View File

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

4
crates/ruma-events/src/call/hangup.rs
View File

@ -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
/// error in the call negotiation, this should be `ice_failed` for when ICE negotiation fails or
/// Should not be provided when the user naturally ends or rejects the call. When there was an error
/// 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

2
crates/ruma-events/src/dummy.rs
View File

@ -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.
///

73
crates/ruma-events/src/event_kinds.rs
View File

@ -44,9 +44,8 @@ pub struct SyncEphemeralRoomEvent<C: EphemeralRoomEventContent> {
/// A message event.
///
/// `MessageEvent` implements the comparison traits using only
/// the `event_id` field, a sorted list would be sorted lexicographically based on
/// the event's `EventId`.
/// `MessageEvent` implements the comparison traits using only the `event_id` field, a sorted list
/// would be sorted lexicographically based on 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
/// the `event_id` field, a sorted list would be sorted lexicographically based on
/// the event's `EventId`.
/// `SyncMessageEvent` implements the comparison traits using only the `event_id` field, a sorted
/// list would be sorted lexicographically based on 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
/// the `event_id` field, a sorted list would be sorted lexicographically based on
/// the event's `EventId`.
/// `RedactedMessageEvent` implements the comparison traits using only the `event_id` field, a
/// sorted list would be sorted lexicographically based on 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
/// the `event_id` field, a sorted list would be sorted lexicographically based on
/// the event's `EventId`.
/// `RedactedSyncMessageEvent` implements the comparison traits using only the `event_id` field, a
/// sorted list would be sorted lexicographically based on 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
/// the `event_id` field, a sorted list would be sorted lexicographically based on
/// the event's `EventId`.
/// `StateEvent` implements the comparison traits using only the `event_id` field, a sorted list
/// would be sorted lexicographically based on 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
/// which user the event affects.
/// This is often an empty string, but some events send a `UserId` to show which user the event
/// 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
/// the `event_id` field, a sorted list would be sorted lexicographically based on
/// the event's `EventId`.
/// `SyncStateEvent` implements the comparison traits using only the `event_id` field, a sorted list
/// would be sorted lexicographically based on 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
/// which user the event affects.
/// This is often an empty string, but some events send a `UserId` to show which user the event
/// 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
/// invited to.
/// A stripped-down state event, used for previews of rooms the user has been 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
/// which user the event affects.
/// This is often an empty string, but some events send a `UserId` to show which user the event
/// 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
/// which user the event affects.
/// This is often an empty string, but some events send a `UserId` to show which user the event
/// 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
/// the `event_id` field, a sorted list would be sorted lexicographically based on
/// the event's `EventId`.
/// `RedactedStateEvent` implements the comparison traits using only the `event_id` field, a sorted
/// list would be sorted lexicographically based on 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
/// which user the event affects.
/// This is often an empty string, but some events send a `UserId` to show which user the event
/// 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
/// the `event_id` field, a sorted list would be sorted lexicographically based on
/// the event's `EventId`.
/// `RedactedSyncStateEvent` implements the comparison traits using only the `event_id` field, a
/// sorted list would be sorted lexicographically based on 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
/// which user the event affects.
/// This is often an empty string, but some events send a `UserId` to show which user the event
/// 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
/// which user the event affects.
/// This is often an empty string, but some events send a `UserId` to show which user the event
/// affects.
pub state_key: String,
}

4
crates/ruma-events/src/key/verification/cancel.rs
View File

@ -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
/// individual verification processes.
/// Should be sent for *m.key.verification.start* messages and messages defined by individual
/// verification processes.
#[ruma_enum(rename = "m.unknown_method")]
UnknownMethod,

5
crates/ruma-events/src/room/create.rs
View File

@ -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
/// events.
/// This is the first event in a room and cannot be changed.
///
/// It acts as the root of all other events.
pub type CreateEvent = StateEvent<CreateEventContent>;
/// The payload for `CreateEvent`.

2
crates/ruma-events/src/room/message.rs
View File

@ -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,

27
crates/ruma-events/src/room/server_acl.rs
View File

@ -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
/// names are strongly discouraged in order to require legitimate homeservers to be
/// backed by a valid registered domain name.
/// This is strongly recommended to be set to false as servers running with IP literal names
/// are strongly discouraged in order to require legitimate homeservers to be backed by a
/// 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
/// be used to cover a wider range of hosts, where `*` matches zero or more characters
/// and `?` matches exactly one character.
/// The server names to allow in the room, excluding any port information.
///
/// **This defaults to an empty list when not provided, effectively disallowing every
/// server.**
/// 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, 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
/// be used to cover a wider range of hosts, where * matches zero or more characters and ?
/// matches exactly one character.
/// The server names to disallow in the room, excluding any port information.
///
/// 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>,
}