From 94c8e00e2e45f8d561154bce26ed55e9839acbd0 Mon Sep 17 00:00:00 2001 From: Vilgot Fredenberg Date: Thu, 9 Jun 2022 20:33:37 +0200 Subject: [PATCH] docs(model): fully document `channel::message` Denies missing docs on it and any of it's submodules --- model/src/channel/message/activity.rs | 27 ++++++++++- model/src/channel/message/activity_type.rs | 24 ---------- .../message/allowed_mentions/builder.rs | 1 + .../channel/message/allowed_mentions/mod.rs | 45 +++++++++++------ model/src/channel/message/application.rs | 8 ++++ model/src/channel/message/flags.rs | 22 +++++++++ model/src/channel/message/interaction.rs | 1 + model/src/channel/message/kind.rs | 21 ++++++++ model/src/channel/message/mod.rs | 48 +++++++++++++++++-- model/src/channel/message/reaction.rs | 4 ++ model/src/channel/message/reference.rs | 11 +++++ model/src/channel/message/sticker/message.rs | 7 ++- model/src/oauth/application.rs | 5 ++ 13 files changed, 178 insertions(+), 46 deletions(-) delete mode 100644 model/src/channel/message/activity_type.rs diff --git a/model/src/channel/message/activity.rs b/model/src/channel/message/activity.rs index 6319b665dc5..ecbd57ecff4 100644 --- a/model/src/channel/message/activity.rs +++ b/model/src/channel/message/activity.rs @@ -1,14 +1,31 @@ -use super::MessageActivityType; use serde::{Deserialize, Serialize}; +use serde_repr::{Deserialize_repr, Serialize_repr}; +/// Activity associated with a message. #[derive(Clone, Debug, Deserialize, Eq, Hash, PartialEq, Serialize)] pub struct MessageActivity { + /// [`MessageActivityType`] #[serde(rename = "type")] pub kind: MessageActivityType, + /// ID of the player's party, lobby or group. #[serde(skip_serializing_if = "Option::is_none")] pub party_id: Option, } +/// Activity of this message. +#[derive(Clone, Copy, Debug, Deserialize_repr, Eq, Hash, PartialEq, Serialize_repr)] +#[repr(u8)] +pub enum MessageActivityType { + /// Join the the party. + Join = 1, + /// Spectate on or with the party. + Spectate = 2, + /// Listen to or with the party. + Listen = 3, + /// Request to join the party. + JoinRequest = 5, +} + #[cfg(test)] mod tests { use super::{MessageActivity, MessageActivityType}; @@ -58,4 +75,12 @@ mod tests { ], ); } + + #[test] + fn variants() { + serde_test::assert_tokens(&MessageActivityType::Join, &[Token::U8(1)]); + serde_test::assert_tokens(&MessageActivityType::Spectate, &[Token::U8(2)]); + serde_test::assert_tokens(&MessageActivityType::Listen, &[Token::U8(3)]); + serde_test::assert_tokens(&MessageActivityType::JoinRequest, &[Token::U8(5)]); + } } diff --git a/model/src/channel/message/activity_type.rs b/model/src/channel/message/activity_type.rs deleted file mode 100644 index ba7b5ae0b9f..00000000000 --- a/model/src/channel/message/activity_type.rs +++ /dev/null @@ -1,24 +0,0 @@ -use serde_repr::{Deserialize_repr, Serialize_repr}; - -#[derive(Clone, Copy, Debug, Deserialize_repr, Eq, Hash, PartialEq, Serialize_repr)] -#[repr(u8)] -pub enum MessageActivityType { - Join = 1, - Spectate = 2, - Listen = 3, - JoinRequest = 5, -} - -#[cfg(test)] -mod tests { - use super::MessageActivityType; - use serde_test::Token; - - #[test] - fn variants() { - serde_test::assert_tokens(&MessageActivityType::Join, &[Token::U8(1)]); - serde_test::assert_tokens(&MessageActivityType::Spectate, &[Token::U8(2)]); - serde_test::assert_tokens(&MessageActivityType::Listen, &[Token::U8(3)]); - serde_test::assert_tokens(&MessageActivityType::JoinRequest, &[Token::U8(5)]); - } -} diff --git a/model/src/channel/message/allowed_mentions/builder.rs b/model/src/channel/message/allowed_mentions/builder.rs index 55357db94c3..0688e8034c4 100644 --- a/model/src/channel/message/allowed_mentions/builder.rs +++ b/model/src/channel/message/allowed_mentions/builder.rs @@ -6,6 +6,7 @@ use crate::{ }, }; +/// Create an [`AllowedMentions`] with a builder. #[derive(Clone, Debug, Default, Eq, PartialEq)] #[must_use = "has no effect if not built into an AllowedMentions"] pub struct AllowedMentionsBuilder(AllowedMentions); diff --git a/model/src/channel/message/allowed_mentions/mod.rs b/model/src/channel/message/allowed_mentions/mod.rs index 6c3a5c6a1b0..55c6250cf20 100644 --- a/model/src/channel/message/allowed_mentions/mod.rs +++ b/model/src/channel/message/allowed_mentions/mod.rs @@ -1,3 +1,9 @@ +//! Configure granular control over mentions and avoid phantom pings. + +mod builder; + +pub use self::builder::AllowedMentionsBuilder; + use crate::{ id::{ marker::{RoleMarker, UserMarker}, @@ -7,39 +13,48 @@ use crate::{ }; use serde::{Deserialize, Serialize}; -mod builder; - -pub use self::builder::AllowedMentionsBuilder; - -/// Parse types. -#[derive(Clone, Debug, Deserialize, Eq, Hash, PartialEq, Serialize)] -#[non_exhaustive] -#[serde(rename_all = "lowercase")] -pub enum ParseTypes { - Everyone, - Roles, - Users, -} - -/// Allowed mentions structure. +/// Allows for more granular control over mentions. +/// +/// Validates against the message content to avoid phantom pings, but you must +/// still have e.g. `@everyone` in the message content to ping everyone. #[derive(Clone, Debug, Default, Deserialize, Eq, Hash, PartialEq, Serialize)] pub struct AllowedMentions { + /// List of allowed [`ParseTypes`]. #[serde(default)] pub parse: Vec, + /// List of [`Id`] to mention. #[serde(default, skip_serializing_if = "Vec::is_empty")] pub users: Vec>, + /// List of [`Id`] to mention. #[serde(default, skip_serializing_if = "Vec::is_empty")] pub roles: Vec>, + /// For replies, whether to mention the message author being replied to. + /// + /// Defaults to false. #[serde(default, skip_serializing_if = "is_false")] pub replied_user: bool, } impl AllowedMentions { + /// Create a new builder to create a allowed mentions. pub const fn builder() -> AllowedMentionsBuilder { AllowedMentionsBuilder::new() } } +/// Allowed mention type in message content. +#[derive(Clone, Debug, Deserialize, Eq, Hash, PartialEq, Serialize)] +#[non_exhaustive] +#[serde(rename_all = "lowercase")] +pub enum ParseTypes { + /// `@everyone` and `here` mentions. + Everyone, + /// Role mentions. + Roles, + /// User mentions. + Users, +} + #[cfg(test)] mod tests { use super::{AllowedMentions, ParseTypes}; diff --git a/model/src/channel/message/application.rs b/model/src/channel/message/application.rs index bbf851044c2..c99c6b11f38 100644 --- a/model/src/channel/message/application.rs +++ b/model/src/channel/message/application.rs @@ -4,13 +4,21 @@ use crate::{ }; use serde::{Deserialize, Serialize}; +/// Partial [`Application`] sent with Rich Presence-related chat embeds. +/// +/// [`Application`]: crate::oauth::Application #[derive(Clone, Debug, Deserialize, Eq, Hash, PartialEq, Serialize)] pub struct MessageApplication { + /// Default rich presence invite cover image. #[serde(skip_serializing_if = "Option::is_none")] pub cover_image: Option, + /// Description of the application. pub description: String, + /// Icon of the application. pub icon: Option, + /// ID of the application. pub id: Id, + /// Name of the application. pub name: String, } diff --git a/model/src/channel/message/flags.rs b/model/src/channel/message/flags.rs index 8631fc0816e..9921b7da429 100644 --- a/model/src/channel/message/flags.rs +++ b/model/src/channel/message/flags.rs @@ -5,6 +5,7 @@ use serde::{ }; bitflags! { + /// Flags to either signal or to modify the look of a message. pub struct MessageFlags: u64 { /// Has been published to subscribed channels via Channel Following. const CROSSPOSTED = 1; @@ -47,3 +48,24 @@ impl Serialize for MessageFlags { serializer.serialize_u64(self.bits()) } } + +#[cfg(test)] +mod tests { + use super::MessageFlags; + use serde::{Deserialize, Serialize}; + use static_assertions::assert_impl_all; + use std::{fmt::Debug, hash::Hash}; + + assert_impl_all!( + MessageFlags: Copy, + Clone, + Debug, + Deserialize<'static>, + Eq, + Hash, + PartialEq, + Send, + Serialize, + Sync + ); +} diff --git a/model/src/channel/message/interaction.rs b/model/src/channel/message/interaction.rs index f44beeede0c..4a8a1c71ba3 100644 --- a/model/src/channel/message/interaction.rs +++ b/model/src/channel/message/interaction.rs @@ -6,6 +6,7 @@ use crate::{ }; use serde::{Deserialize, Serialize}; +/// Response to an interaction without an existing message. #[derive(Clone, Debug, Deserialize, Eq, Hash, PartialEq, Serialize)] pub struct MessageInteraction { /// ID of the interaction. diff --git a/model/src/channel/message/kind.rs b/model/src/channel/message/kind.rs index b2c5ad08142..11a1e4dde0d 100644 --- a/model/src/channel/message/kind.rs +++ b/model/src/channel/message/kind.rs @@ -1,25 +1,46 @@ use crate::channel::ConversionError; use serde_repr::{Deserialize_repr, Serialize_repr}; +/// Type of a [`Message`]. +/// +/// [`Message`]: super::Message +#[allow(missing_docs)] #[derive(Clone, Copy, Debug, Deserialize_repr, Eq, Hash, PartialEq, Serialize_repr)] #[repr(u8)] pub enum MessageType { + /// Regular message. Regular = 0, + /// System message denoting a recipient has been added to a group. RecipientAdd = 1, + /// System message denoting a recipient has been removed from a group. RecipientRemove = 2, + /// System message denoting a call state, e.g. missed, started. Call = 3, + /// System message denoting a channel's name has been changed. ChannelNameChange = 4, + /// System message denoting a channel's icon has been changed. ChannelIconChange = 5, + /// System message denoting a message has been pinned. ChannelMessagePinned = 6, + /// System message denoting a member has joined a guild. GuildMemberJoin = 7, + /// System message denoting a user nitro boosted a guild. UserPremiumSub = 8, + /// System message denoting a user nitro boosted a guild to level 1. UserPremiumSubTier1 = 9, + /// System message denoting a user nitro boosted a guild to level 2. UserPremiumSubTier2 = 10, + /// System message denoting a user nitro boosted a guild to level 3. UserPremiumSubTier3 = 11, + /// System message denoting a channel has been followed. ChannelFollowAdd = 12, + /// System message denoting a guild has been disqualified for Server Discovery. GuildDiscoveryDisqualified = 14, + /// System message denoting a guild has been redisqualified for Server Discovery. GuildDiscoveryRequalified = 15, + /// System message denoting an initial warning for Server Discovery disqualification. GuildDiscoveryGracePeriodInitialWarning = 16, + /// System message denoting a final warning for Server Discovery disqualification. GuildDiscoveryGracePeriodFinalWarning = 17, ThreadCreated = 18, /// Message is an inline reply. diff --git a/model/src/channel/message/mod.rs b/model/src/channel/message/mod.rs index 5682ff2ad5f..12232000aec 100644 --- a/model/src/channel/message/mod.rs +++ b/model/src/channel/message/mod.rs @@ -1,8 +1,10 @@ +//! Textual user communication method. +#![deny(missing_docs)] + pub mod allowed_mentions; pub mod sticker; mod activity; -mod activity_type; mod application; mod flags; mod interaction; @@ -12,10 +14,16 @@ mod reaction; mod reference; pub use self::{ - activity::MessageActivity, activity_type::MessageActivityType, - allowed_mentions::AllowedMentions, application::MessageApplication, flags::MessageFlags, - interaction::MessageInteraction, kind::MessageType, mention::Mention, - reaction::MessageReaction, reference::MessageReference, sticker::Sticker, + activity::{MessageActivity, MessageActivityType}, + allowed_mentions::AllowedMentions, + application::MessageApplication, + flags::MessageFlags, + interaction::MessageInteraction, + kind::MessageType, + mention::Mention, + reaction::MessageReaction, + reference::MessageReference, + sticker::Sticker, }; use self::sticker::MessageSticker; @@ -34,10 +42,13 @@ use crate::{ }; use serde::{Deserialize, Serialize}; +/// Text message sent in a [`Channel`] within Discord. #[derive(Clone, Debug, Deserialize, Eq, Hash, PartialEq, Serialize)] pub struct Message { + /// Sent with Rich Presence-related chat embeds. #[serde(skip_serializing_if = "Option::is_none")] pub activity: Option, + /// Sent with Rich Presence-related chat embeds. #[serde(skip_serializing_if = "Option::is_none")] pub application: Option, /// Associated application's ID. @@ -58,7 +69,9 @@ pub struct Message { /// /// [Message Content Intent]: crate::gateway::Intents::MESSAGE_CONTENT pub attachments: Vec, + /// Author of the message. pub author: User, + /// ID of the [`Channel`] the message was sent in. pub channel_id: Id, /// List of provided components, such as buttons. /// @@ -87,6 +100,7 @@ pub struct Message { /// /// [Message Content Intent]: crate::gateway::Intents::MESSAGE_CONTENT pub content: String, + /// When the message was last edited. pub edited_timestamp: Option, /// List of embeds. /// @@ -101,23 +115,44 @@ pub struct Message { /// /// [Message Content Intent]: crate::gateway::Intents::MESSAGE_CONTENT pub embeds: Vec, + /// Enabled [`MessageFlags`]. #[serde(skip_serializing_if = "Option::is_none")] pub flags: Option, + /// ID of the [`Guild`] the message was sent in. + /// + /// [`Guild`]: crate::guild::Guild #[serde(skip_serializing_if = "Option::is_none")] pub guild_id: Option>, + /// Id of the message. pub id: Id, + /// Interaction the message was sent as a response to. #[serde(skip_serializing_if = "Option::is_none")] pub interaction: Option, + /// Type of message. #[serde(rename = "type")] pub kind: MessageType, + /// Member properties of the [`author`]. + /// + /// [`author`]: Message::author #[serde(skip_serializing_if = "Option::is_none")] pub member: Option, + /// [`Channel`]s mentioned in the message. + /// + /// Note: only textual channels visible to everyone mentioned in crossposted + /// messages (via channel following) will be included. #[serde(default, skip_serializing_if = "Vec::is_empty")] pub mention_channels: Vec, + /// Whether the message mentions `@everyone`. pub mention_everyone: bool, + /// [`Role`]s mentioned in the message. + /// + /// [`Role`]: crate::guild::Role pub mention_roles: Vec>, + /// users mentioned in the message. pub mentions: Vec, + /// Whether the message is pinned. pub pinned: bool, + /// List of reactions to the message. #[serde(default, skip_serializing_if = "Vec::is_empty")] pub reactions: Vec, /// Reference data sent with crossposted messages and replies. @@ -133,9 +168,12 @@ pub struct Message { pub sticker_items: Vec, /// Timestamp of when the message was created. pub timestamp: Timestamp, + /// Thread started from this message, including [`Channel::member`]. #[serde(skip_serializing_if = "Option::is_none")] pub thread: Option, + /// Whether the message was a TTS message. pub tts: bool, + /// ID of the webhook that generated the message. #[serde(skip_serializing_if = "Option::is_none")] pub webhook_id: Option>, } diff --git a/model/src/channel/message/reaction.rs b/model/src/channel/message/reaction.rs index 3f992693d82..063baa45638 100644 --- a/model/src/channel/message/reaction.rs +++ b/model/src/channel/message/reaction.rs @@ -1,10 +1,14 @@ use crate::channel::ReactionType; use serde::{Deserialize, Serialize}; +/// Message reaction struct. #[derive(Clone, Debug, Deserialize, Eq, Hash, PartialEq, Serialize)] pub struct MessageReaction { + /// Ammount of reactions this emoji has. pub count: u64, + /// Emoji of this reaction. pub emoji: ReactionType, + /// Whether we have reacted with this emoji. pub me: bool, } diff --git a/model/src/channel/message/reference.rs b/model/src/channel/message/reference.rs index 4889c9e9e1d..3f6c6702a71 100644 --- a/model/src/channel/message/reference.rs +++ b/model/src/channel/message/reference.rs @@ -4,14 +4,25 @@ use crate::id::{ }; use serde::{Deserialize, Serialize}; +/// Message reference struct. #[derive(Clone, Debug, Deserialize, Eq, Hash, PartialEq, Serialize)] pub struct MessageReference { + /// Originating message's channel ID. + /// + /// Note: optional when creating a reply, but always present when receiving + /// an event or response containing this model. #[serde(skip_serializing_if = "Option::is_none")] pub channel_id: Option>, + /// Originating message's guild ID. #[serde(skip_serializing_if = "Option::is_none")] pub guild_id: Option>, + /// Originating message's ID. #[serde(skip_serializing_if = "Option::is_none")] pub message_id: Option>, + /// Whether to error if the referenced message doesn't exist instead of + /// sending a normal message. + /// + /// Defaults to true. #[serde(skip_serializing_if = "Option::is_none")] pub fail_if_not_exists: Option, } diff --git a/model/src/channel/message/sticker/message.rs b/model/src/channel/message/sticker/message.rs index 09ab0ac6326..f2007e4e631 100644 --- a/model/src/channel/message/sticker/message.rs +++ b/model/src/channel/message/sticker/message.rs @@ -2,11 +2,16 @@ use super::StickerFormatType; use crate::id::{marker::StickerMarker, Id}; use serde::{Deserialize, Serialize}; -/// Smallest amount of data required to render a sticker. +/// Smallest amount of data required to render a [`Sticker`]. +/// +/// [`Sticker`]: super::Sticker #[derive(Clone, Debug, Deserialize, Eq, Hash, PartialEq, Serialize)] pub struct MessageSticker { + /// Format type. pub format_type: StickerFormatType, + /// ID of the sticker. pub id: Id, + /// Name of the sticker. pub name: String, } diff --git a/model/src/oauth/application.rs b/model/src/oauth/application.rs index 13abed820c0..f1054d6dc34 100644 --- a/model/src/oauth/application.rs +++ b/model/src/oauth/application.rs @@ -13,19 +13,24 @@ use serde::{Deserialize, Serialize}; pub struct Application { pub bot_public: bool, pub bot_require_code_grant: bool, + /// Default rich presence invite cover image. pub cover_image: Option, /// Application's default custom authorization link, if enabled. #[serde(skip_serializing_if = "Option::is_none")] pub custom_install_url: Option, + /// Description of the application. pub description: String, pub guild_id: Option>, /// Public flags of the application. pub flags: Option, + /// Icon of the application. pub icon: Option, + /// ID of the application. pub id: Id, /// Settings for the application's default in-app authorization, if enabled. #[serde(skip_serializing_if = "Option::is_none")] pub install_params: Option, + /// Name of the application. pub name: String, pub owner: Option, pub primary_sku_id: Option>,