docs(model): fully document channel::message

Denies missing docs on it and any of it's submodules

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<String>,
 }
 
+/// 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)]);
+    }
 }

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);

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<ParseTypes>,
+    /// List of [`Id<UserMarker>`] to mention.
     #[serde(default, skip_serializing_if = "Vec::is_empty")]
     pub users: Vec<Id<UserMarker>>,
+    /// List of [`Id<RoleMarker>`] to mention.
     #[serde(default, skip_serializing_if = "Vec::is_empty")]
     pub roles: Vec<Id<RoleMarker>>,
+    /// 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};

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<ImageHash>,
+    /// Description of the application.
     pub description: String,
+    /// Icon of the application.
     pub icon: Option<ImageHash>,
+    /// ID of the application.
     pub id: Id<ApplicationMarker>,
+    /// Name of the application.
     pub name: String,
 }
 

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
+    );
+}

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.

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.

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<MessageActivity>,
+    /// Sent with Rich Presence-related chat embeds.
     #[serde(skip_serializing_if = "Option::is_none")]
     pub application: Option<MessageApplication>,
     /// Associated application's ID.
@@ -58,7 +69,9 @@ pub struct Message {
     ///
     /// [Message Content Intent]: crate::gateway::Intents::MESSAGE_CONTENT
     pub attachments: Vec<Attachment>,
+    /// Author of the message.
     pub author: User,
+    /// ID of the [`Channel`] the message was sent in.
     pub channel_id: Id<ChannelMarker>,
     /// 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<Timestamp>,
     /// List of embeds.
     ///
@@ -101,23 +115,44 @@ pub struct Message {
     ///
     /// [Message Content Intent]: crate::gateway::Intents::MESSAGE_CONTENT
     pub embeds: Vec<Embed>,
+    /// Enabled [`MessageFlags`].
     #[serde(skip_serializing_if = "Option::is_none")]
     pub flags: Option<MessageFlags>,
+    /// 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<GuildMarker>>,
+    /// Id of the message.
     pub id: Id<MessageMarker>,
+    /// Interaction the message was sent as a response to.
     #[serde(skip_serializing_if = "Option::is_none")]
     pub interaction: Option<MessageInteraction>,
+    /// 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<PartialMember>,
+    /// [`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<ChannelMention>,
+    /// Whether the message mentions `@everyone`.
     pub mention_everyone: bool,
+    /// [`Role`]s mentioned in the message.
+    ///
+    /// [`Role`]: crate::guild::Role
     pub mention_roles: Vec<Id<RoleMarker>>,
+    /// users mentioned in the message.
     pub mentions: Vec<Mention>,
+    /// 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<MessageReaction>,
     /// Reference data sent with crossposted messages and replies.
@@ -133,9 +168,12 @@ pub struct Message {
     pub sticker_items: Vec<MessageSticker>,
     /// 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<Channel>,
+    /// 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<Id<WebhookMarker>>,
 }