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

events: Fix docs

Browse Source
This commit is contained in:
Kévin Commaille 2022-03-28 19:17:57 +02:00 committed by Kévin Commaille
parent 47bb788dc2
commit 4ec803c29a
8 changed files with 50 additions and 57 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

16
crates/ruma-common/src/events/emote.rs
View File

@ -31,34 +31,32 @@ pub struct EmoteEventContent {
#[serde(flatten)] #[serde(flatten)]
pub message: MessageContent, pub message: MessageContent,
/// Information about related messages for [rich replies]. /// Information about related messages.
///
/// [rich replies]: https://spec.matrix.org/v1.2/client-server-api/#rich-replies
#[serde(flatten, skip_serializing_if = "Option::is_none")] #[serde(flatten, skip_serializing_if = "Option::is_none")]
pub relates_to: Option<Relation>, pub relates_to: Option<Relation>,
} }
impl EmoteEventContent { impl EmoteEventContent {
/// A convenience constructor to create a plain text message. /// A convenience constructor to create a plain text emote.
pub fn plain(body: impl Into<String>) -> Self { pub fn plain(body: impl Into<String>) -> Self {
Self { message: MessageContent::plain(body), relates_to: None } Self { message: MessageContent::plain(body), relates_to: None }
} }
/// A convenience constructor to create an HTML message. /// A convenience constructor to create an HTML emote.
pub fn html(body: impl Into<String>, html_body: impl Into<String>) -> Self { pub fn html(body: impl Into<String>, html_body: impl Into<String>) -> Self {
Self { message: MessageContent::html(body, html_body), relates_to: None } Self { message: MessageContent::html(body, html_body), relates_to: None }
} }
/// A convenience constructor to create a Markdown message. /// A convenience constructor to create a Markdown emote.
/// ///
/// Returns an HTML message if some Markdown formatting was detected, otherwise returns a plain /// Returns an HTML emote if some Markdown formatting was detected, otherwise returns a plain
/// text message. /// text emote.
#[cfg(feature = "markdown")] #[cfg(feature = "markdown")]
pub fn markdown(body: impl AsRef<str> + Into<String>) -> Self { pub fn markdown(body: impl AsRef<str> + Into<String>) -> Self {
Self { message: MessageContent::markdown(body), relates_to: None } Self { message: MessageContent::markdown(body), relates_to: None }
} }
/// Create a new `MessageEventContent` from the given `EmoteMessageEventContent` and optional /// Create a new `EmoteEventContent` from the given `EmoteMessageEventContent` and optional
/// relation. /// relation.
pub fn from_emote_room_message( pub fn from_emote_room_message(
content: EmoteMessageEventContent, content: EmoteMessageEventContent,

10
crates/ruma-common/src/events/file.rs
View File

@ -42,9 +42,7 @@ pub struct FileEventContent {
#[serde(rename = "m.file")] #[serde(rename = "m.file")]
pub file: FileContent, pub file: FileContent,
/// Information about related messages for [rich replies]. /// Information about related messages.
///
/// [rich replies]: https://spec.matrix.org/v1.2/client-server-api/#rich-replies
#[serde(flatten, skip_serializing_if = "Option::is_none")] #[serde(flatten, skip_serializing_if = "Option::is_none")]
pub relates_to: Option<Relation>, pub relates_to: Option<Relation>,
} }
@ -130,7 +128,7 @@ pub struct FileContent {
/// Information on the encrypted file. /// Information on the encrypted file.
/// ///
/// Required if file is encrypted. /// Required if the file is encrypted.
#[serde(flatten, skip_serializing_if = "Option::is_none")] #[serde(flatten, skip_serializing_if = "Option::is_none")]
pub encryption_info: Option<Box<EncryptedContent>>, pub encryption_info: Option<Box<EncryptedContent>>,
} }
@ -179,7 +177,7 @@ pub struct FileContentInfo {
#[serde(skip_serializing_if = "Option::is_none")] #[serde(skip_serializing_if = "Option::is_none")]
pub name: Option<String>, pub name: Option<String>,
/// The mimetype of the file, e.g. “application/msword”. /// The mimetype of the file, e.g. "application/msword".
#[serde(skip_serializing_if = "Option::is_none")] #[serde(skip_serializing_if = "Option::is_none")]
pub mimetype: Option<String>, pub mimetype: Option<String>,
@ -196,7 +194,7 @@ impl FileContentInfo {
/// Create a new `FileContentInfo` with the given file info and filename. /// Create a new `FileContentInfo` with the given file info and filename.
/// ///
/// Returns `None` if both parameters are `None` /// Returns `None` if both parameters are `None`.
pub fn from_room_message_content( pub fn from_room_message_content(
info: Option<impl Into<FileContentInfo>>, info: Option<impl Into<FileContentInfo>>,
filename: Option<String>, filename: Option<String>,

6
crates/ruma-common/src/events/image.rs
View File

@ -58,9 +58,7 @@ pub struct ImageEventContent {
)] )]
pub caption: Option<MessageContent>, pub caption: Option<MessageContent>,
/// Information about related messages for [rich replies]. /// Information about related messages.
///
/// [rich replies]: https://spec.matrix.org/v1.2/client-server-api/#rich-replies
#[serde(flatten, skip_serializing_if = "Option::is_none")] #[serde(flatten, skip_serializing_if = "Option::is_none")]
pub relates_to: Option<Relation>, pub relates_to: Option<Relation>,
} }
@ -244,7 +242,7 @@ impl ThumbnailFileContent {
Self { url, info, encryption_info: Some(Box::new(encryption_info)) } Self { url, info, encryption_info: Some(Box::new(encryption_info)) }
} }
/// Create a `ThumbnailContent` with the given thumbnail source and info. /// Create a `ThumbnailFileContent` with the given thumbnail source and info.
/// ///
/// Returns `None` if no thumbnail was found. /// Returns `None` if no thumbnail was found.
fn from_room_message_content( fn from_room_message_content(

4
crates/ruma-common/src/events/message.rs
View File

@ -82,9 +82,7 @@ pub struct MessageEventContent {
#[serde(flatten)] #[serde(flatten)]
pub message: MessageContent, pub message: MessageContent,
/// Information about related messages for [rich replies]. /// Information about related messages.
///
/// [rich replies]: https://spec.matrix.org/v1.2/client-server-api/#rich-replies
#[serde(flatten, skip_serializing_if = "Option::is_none")] #[serde(flatten, skip_serializing_if = "Option::is_none")]
pub relates_to: Option<Relation>, pub relates_to: Option<Relation>,
} }

16
crates/ruma-common/src/events/notice.rs
View File

@ -31,34 +31,32 @@ pub struct NoticeEventContent {
#[serde(flatten)] #[serde(flatten)]
pub message: MessageContent, pub message: MessageContent,
/// Information about related messages for [rich replies]. /// Information about related messages.
///
/// [rich replies]: https://spec.matrix.org/v1.2/client-server-api/#rich-replies
#[serde(flatten, skip_serializing_if = "Option::is_none")] #[serde(flatten, skip_serializing_if = "Option::is_none")]
pub relates_to: Option<Relation>, pub relates_to: Option<Relation>,
} }
impl NoticeEventContent { impl NoticeEventContent {
/// A convenience constructor to create a plain text message. /// A convenience constructor to create a plain text notice.
pub fn plain(body: impl Into<String>) -> Self { pub fn plain(body: impl Into<String>) -> Self {
Self { message: MessageContent::plain(body), relates_to: None } Self { message: MessageContent::plain(body), relates_to: None }
} }
/// A convenience constructor to create an HTML message. /// A convenience constructor to create an HTML notice.
pub fn html(body: impl Into<String>, html_body: impl Into<String>) -> Self { pub fn html(body: impl Into<String>, html_body: impl Into<String>) -> Self {
Self { message: MessageContent::html(body, html_body), relates_to: None } Self { message: MessageContent::html(body, html_body), relates_to: None }
} }
/// A convenience constructor to create a Markdown message. /// A convenience constructor to create a Markdown notice.
/// ///
/// Returns an HTML message if some Markdown formatting was detected, otherwise returns a plain /// Returns an HTML notice if some Markdown formatting was detected, otherwise returns a plain
/// text message. /// text notice.
#[cfg(feature = "markdown")] #[cfg(feature = "markdown")]
pub fn markdown(body: impl AsRef<str> + Into<String>) -> Self { pub fn markdown(body: impl AsRef<str> + Into<String>) -> Self {
Self { message: MessageContent::markdown(body), relates_to: None } Self { message: MessageContent::markdown(body), relates_to: None }
} }
/// Create a new `MessageEventContent` from the given `NoticeMessageEventContent` and optional /// Create a new `NoticeEventContent` from the given `NoticeMessageEventContent` and optional
/// relation. /// relation.
pub fn from_notice_room_message( pub fn from_notice_room_message(
content: NoticeMessageEventContent, content: NoticeMessageEventContent,

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

@ -588,7 +588,7 @@ pub struct AudioMessageEventContent {
#[serde(flatten)] #[serde(flatten)]
pub source: MediaSource, pub source: MediaSource,
/// Metadata for the audio clip referred to in `url`. /// Metadata for the audio clip referred to in `source`.
#[serde(skip_serializing_if = "Option::is_none")] #[serde(skip_serializing_if = "Option::is_none")]
pub info: Option<Box<AudioInfo>>, pub info: Option<Box<AudioInfo>>,
@ -622,7 +622,7 @@ pub struct AudioMessageEventContent {
} }
impl AudioMessageEventContent { impl AudioMessageEventContent {
/// Creates a new non-encrypted `RoomAudioMessageEventContent` with the given body, url and /// Creates a new non-encrypted `AudioMessageEventContent` with the given body, url and
/// optional extra info. /// optional extra info.
pub fn plain(body: String, url: Box<MxcUri>, info: Option<Box<AudioInfo>>) -> Self { pub fn plain(body: String, url: Box<MxcUri>, info: Option<Box<AudioInfo>>) -> Self {
Self { Self {
@ -643,7 +643,7 @@ impl AudioMessageEventContent {
} }
} }
/// Creates a new encrypted `RoomAudioMessageEventContent` with the given body and encrypted /// Creates a new encrypted `AudioMessageEventContent` with the given body and encrypted
/// file. /// file.
pub fn encrypted(body: String, file: EncryptedFile) -> Self { pub fn encrypted(body: String, file: EncryptedFile) -> Self {
Self { Self {
@ -693,11 +693,11 @@ impl AudioMessageEventContent {
#[cfg(feature = "unstable-msc3245")] #[cfg(feature = "unstable-msc3245")]
pub fn from_extensible_voice_content( pub fn from_extensible_voice_content(
message: MessageContent, message: MessageContent,
ext_file: FileContent, file: FileContent,
audio: AudioContent, audio: AudioContent,
voice: VoiceContent, voice: VoiceContent,
) -> Self { ) -> Self {
let mut content = Self::from_extensible_content(message, ext_file, audio); let mut content = Self::from_extensible_content(message, file, audio);
content.voice = Some(voice); content.voice = Some(voice);
content content
} }
@ -849,7 +849,7 @@ pub struct FileMessageEventContent {
#[serde(flatten)] #[serde(flatten)]
pub source: MediaSource, pub source: MediaSource,
/// Metadata about the file referred to in `url`. /// Metadata about the file referred to in `source`.
#[serde(skip_serializing_if = "Option::is_none")] #[serde(skip_serializing_if = "Option::is_none")]
pub info: Option<Box<FileInfo>>, pub info: Option<Box<FileInfo>>,
@ -869,7 +869,7 @@ pub struct FileMessageEventContent {
} }
impl FileMessageEventContent { impl FileMessageEventContent {
/// Creates a new non-encrypted `RoomFileMessageEventContent` with the given body, url and /// Creates a new non-encrypted `FileMessageEventContent` with the given body, url and
/// optional extra info. /// optional extra info.
pub fn plain(body: String, url: Box<MxcUri>, info: Option<Box<FileInfo>>) -> Self { pub fn plain(body: String, url: Box<MxcUri>, info: Option<Box<FileInfo>>) -> Self {
Self { Self {
@ -887,7 +887,7 @@ impl FileMessageEventContent {
} }
} }
/// Creates a new encrypted `RoomFileMessageEventContent` with the given body and encrypted /// Creates a new encrypted `FileMessageEventContent` with the given body and encrypted
/// file. /// file.
pub fn encrypted(body: String, file: EncryptedFile) -> Self { pub fn encrypted(body: String, file: EncryptedFile) -> Self {
Self { Self {
@ -902,7 +902,7 @@ impl FileMessageEventContent {
} }
} }
/// Create a new `RoomFileMessageEventContent` with the given message and file info. /// Create a new `FileMessageEventContent` with the given message and file info.
#[cfg(feature = "unstable-msc3551")] #[cfg(feature = "unstable-msc3551")]
pub fn from_extensible_content(message: MessageContent, file: FileContent) -> Self { pub fn from_extensible_content(message: MessageContent, file: FileContent) -> Self {
let body = if let Some(body) = message.find_plain() { let body = if let Some(body) = message.find_plain() {
@ -982,7 +982,7 @@ pub struct ImageMessageEventContent {
#[serde(flatten)] #[serde(flatten)]
pub source: MediaSource, pub source: MediaSource,
/// Metadata about the image referred to in `url`. /// Metadata about the image referred to in `source`.
#[serde(skip_serializing_if = "Option::is_none")] #[serde(skip_serializing_if = "Option::is_none")]
pub info: Option<Box<ImageInfo>>, pub info: Option<Box<ImageInfo>>,
@ -1026,7 +1026,7 @@ pub struct ImageMessageEventContent {
} }
impl ImageMessageEventContent { impl ImageMessageEventContent {
/// Creates a new non-encrypted `RoomImageMessageEventContent` with the given body, url and /// Creates a new non-encrypted `ImageMessageEventContent` with the given body, url and
/// optional extra info. /// optional extra info.
pub fn plain(body: String, url: Box<MxcUri>, info: Option<Box<ImageInfo>>) -> Self { pub fn plain(body: String, url: Box<MxcUri>, info: Option<Box<ImageInfo>>) -> Self {
Self { Self {
@ -1057,7 +1057,7 @@ impl ImageMessageEventContent {
} }
} }
/// Creates a new encrypted `RoomImageMessageEventContent` with the given body and encrypted /// Creates a new encrypted `ImageMessageEventContent` with the given body and encrypted
/// file. /// file.
pub fn encrypted(body: String, file: EncryptedFile) -> Self { pub fn encrypted(body: String, file: EncryptedFile) -> Self {
Self { Self {
@ -1161,7 +1161,7 @@ pub struct LocationMessageEventContent {
} }
impl LocationMessageEventContent { impl LocationMessageEventContent {
/// Creates a new `RoomLocationMessageEventContent` with the given body and geo URI. /// Creates a new `LocationMessageEventContent` with the given body and geo URI.
pub fn new(body: String, geo_uri: String) -> Self { pub fn new(body: String, geo_uri: String) -> Self {
Self { Self {
#[cfg(feature = "unstable-msc3488")] #[cfg(feature = "unstable-msc3488")]
@ -1210,7 +1210,7 @@ impl LocationMessageEventContent {
#[derive(Clone, Debug, Default, Deserialize, Serialize)] #[derive(Clone, Debug, Default, Deserialize, Serialize)]
#[cfg_attr(not(feature = "unstable-exhaustive-types"), non_exhaustive)] #[cfg_attr(not(feature = "unstable-exhaustive-types"), non_exhaustive)]
pub struct LocationInfo { pub struct LocationInfo {
/// The URL to a thumbnail of the location. /// The source of a thumbnail of the location.
#[serde( #[serde(
flatten, flatten,
with = "super::thumbnail_source_serde", with = "super::thumbnail_source_serde",
@ -1328,7 +1328,7 @@ pub struct ServerNoticeMessageEventContent {
} }
impl ServerNoticeMessageEventContent { impl ServerNoticeMessageEventContent {
/// Creates a new `RoomServerNoticeMessageEventContent` with the given body and notice type. /// Creates a new `ServerNoticeMessageEventContent` with the given body and notice type.
pub fn new(body: String, server_notice_type: ServerNoticeType) -> Self { pub fn new(body: String, server_notice_type: ServerNoticeType) -> Self {
Self { body, server_notice_type, admin_contact: None, limit_type: None } Self { body, server_notice_type, admin_contact: None, limit_type: None }
} }
@ -1422,9 +1422,9 @@ impl FormattedBody {
Self { format: MessageFormat::Html, body: body.into() } Self { format: MessageFormat::Html, body: body.into() }
} }
/// Creates a new HTML-formatted message body by parsing the markdown in `body`. /// Creates a new HTML-formatted message body by parsing the Markdown in `body`.
/// ///
/// Returns `None` if no markdown formatting was found. /// Returns `None` if no Markdown formatting was found.
#[cfg(feature = "markdown")] #[cfg(feature = "markdown")]
pub fn markdown(body: impl AsRef<str>) -> Option<Self> { pub fn markdown(body: impl AsRef<str>) -> Option<Self> {
let body = body.as_ref(); let body = body.as_ref();
@ -1473,7 +1473,7 @@ impl TextMessageEventContent {
} }
} }
/// A convenience constructor to create an html message. /// A convenience constructor to create an HTML message.
pub fn html(body: impl Into<String>, html_body: impl Into<String>) -> Self { pub fn html(body: impl Into<String>, html_body: impl Into<String>) -> Self {
let body = body.into(); let body = body.into();
let html_body = html_body.into(); let html_body = html_body.into();
@ -1485,9 +1485,9 @@ impl TextMessageEventContent {
} }
} }
/// A convenience constructor to create a markdown message. /// A convenience constructor to create a Markdown message.
/// ///
/// Returns an html message if some markdown formatting was detected, otherwise returns a plain /// Returns an HTML message if some Markdown formatting was detected, otherwise returns a plain
/// text message. /// text message.
#[cfg(feature = "markdown")] #[cfg(feature = "markdown")]
pub fn markdown(body: impl AsRef<str> + Into<String>) -> Self { pub fn markdown(body: impl AsRef<str> + Into<String>) -> Self {
@ -1531,7 +1531,7 @@ pub struct VideoMessageEventContent {
#[serde(flatten)] #[serde(flatten)]
pub source: MediaSource, pub source: MediaSource,
/// Metadata about the video clip referred to in `url`. /// Metadata about the video clip referred to in `source`.
#[serde(skip_serializing_if = "Option::is_none")] #[serde(skip_serializing_if = "Option::is_none")]
pub info: Option<Box<VideoInfo>>, pub info: Option<Box<VideoInfo>>,
@ -1575,7 +1575,7 @@ pub struct VideoMessageEventContent {
} }
impl VideoMessageEventContent { impl VideoMessageEventContent {
/// Creates a new non-encrypted `RoomVideoMessageEventContent` with the given body, url and /// Creates a new non-encrypted `VideoMessageEventContent` with the given body, url and
/// optional extra info. /// optional extra info.
pub fn plain(body: String, url: Box<MxcUri>, info: Option<Box<VideoInfo>>) -> Self { pub fn plain(body: String, url: Box<MxcUri>, info: Option<Box<VideoInfo>>) -> Self {
Self { Self {
@ -1606,7 +1606,7 @@ impl VideoMessageEventContent {
} }
} }
/// Creates a new encrypted `RoomVideoMessageEventContent` with the given body and encrypted /// Creates a new encrypted `VideoMessageEventContent` with the given body and encrypted
/// file. /// file.
pub fn encrypted(body: String, file: EncryptedFile) -> Self { pub fn encrypted(body: String, file: EncryptedFile) -> Self {
Self { Self {
@ -1780,7 +1780,7 @@ pub struct KeyVerificationRequestEventContent {
} }
impl KeyVerificationRequestEventContent { impl KeyVerificationRequestEventContent {
/// Creates a new `RoomKeyVerificationRequestEventContent` with the given body, method, device /// Creates a new `KeyVerificationRequestEventContent` with the given body, method, device
/// and user ID. /// and user ID.
pub fn new( pub fn new(
body: String, body: String,

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

@ -167,7 +167,7 @@ pub struct FileMessageEventContentDeHelper {
#[serde(flatten)] #[serde(flatten)]
pub source: MediaSource, pub source: MediaSource,
/// Metadata about the file referred to in `url`. /// Metadata about the file referred to in `source`.
pub info: Option<Box<FileInfo>>, pub info: Option<Box<FileInfo>>,
/// Extensible-event text representation of the message. /// Extensible-event text representation of the message.

5
crates/ruma-common/src/events/voice.rs
View File

@ -41,7 +41,7 @@ pub struct VoiceEventContent {
#[serde(rename = "m.audio")] #[serde(rename = "m.audio")]
pub audio: AudioContent, pub audio: AudioContent,
/// The audio content of the message. /// The voice content of the message.
#[serde(rename = "m.voice")] #[serde(rename = "m.voice")]
pub voice: VoiceContent, pub voice: VoiceContent,
@ -99,6 +99,9 @@ impl VoiceEventContent {
} }
/// Voice content. /// Voice content.
///
/// This is currently empty and used as a flag to mark an audio event that should be displayed as a
/// voice message.
#[derive(Clone, Debug, Default, Serialize, Deserialize)] #[derive(Clone, Debug, Default, Serialize, Deserialize)]
#[cfg_attr(not(feature = "unstable-exhaustive-types"), non_exhaustive)] #[cfg_attr(not(feature = "unstable-exhaustive-types"), non_exhaustive)]
pub struct VoiceContent {} pub struct VoiceContent {}