partial, incomplete docs (no builders)

Author: jamesbt365

src/model/application/component.rs

@@ -31,8 +31,14 @@ enum_number! {
     }
 }
 
-// TODO: doc everything new :sob:
-
+/// Represents Discord components, a part of messages that are usually interactable.
+///
+/// # Component Versioning
+///
+/// - When `IS_COMPONENTS_V2` is **not** set, the **only** valid top-level component is
+///   [`ActionRow`].
+/// - When `IS_COMPONENTS_V2` **is** set, other component types may be used at the top level, but
+///   other message limitations are applied.
 #[cfg_attr(feature = "typesize", derive(typesize::derive::TypeSize))]
 #[derive(Clone, Debug, Serialize)]
 #[non_exhaustive]
@@ -51,9 +57,6 @@ pub enum Component {
     // always update the macro below.
 }
 
-// TODO: add something like this to every variant.
-// The component type, it will always be [`ComponentType::Thing`].
-
 // Define the macro to implement Deserialize
 macro_rules! impl_deserialize_component {
     ($enum_name:ident, $($variant:pat => $variant_enum:expr),*) => {
@@ -103,23 +106,38 @@ impl_deserialize_component!(Component,
     ComponentType::Container => Component::Container
 );
 
+/// A component that is a container for up to 3 text display components and an accessory.
+///
+/// [Incomplete Discord docs](https://github.com/Lulalaby/discord-api-docs/pull/30)
 #[cfg_attr(feature = "typesize", derive(typesize::derive::TypeSize))]
 #[derive(Clone, Debug, Deserialize, Serialize)]
 #[non_exhaustive]
 pub struct Section {
-    components: FixedArray<TextDisplay>,
+    /// Always [`ComponentType::Section`]
+    #[serde(rename = "type")]
+    pub kind: ComponentType,
+    components: FixedArray<SectionComponent>,
     accessory: SectionAccessory,
 }
 
+/// A section component's thumbnail.
+///
+/// See [`Section`] for how this fits within a section.
+///
+/// [Incomplete Discord docs](https://github.com/Lulalaby/discord-api-docs/pull/30)
 #[cfg_attr(feature = "typesize", derive(typesize::derive::TypeSize))]
 #[derive(Clone, Debug, Deserialize, Serialize)]
 #[non_exhaustive]
 pub struct Thumbnail {
+    /// Always [`ComponentType::Thumbnail`]
+    #[serde(rename = "type")]
+    pub kind: ComponentType,
     media: UnfurledMediaItem,
     description: Option<FixedString<u16>>,
     spoiler: Option<bool>,
 }
 
+/// An abstraction over a resolved and unresolved unfurled media item.
 #[cfg_attr(feature = "typesize", derive(typesize::derive::TypeSize))]
 #[derive(Clone, Debug, Deserialize, Serialize)]
 #[non_exhaustive]
@@ -129,13 +147,19 @@ pub enum MediaItem {
     Unresolved(UnfurledMediaItem),
 }
 
+/// An unfurled media item, stores the url to the item.
+///
+/// [Incomplete Discord docs](https://github.com/Lulalaby/discord-api-docs/pull/30)
 #[cfg_attr(feature = "typesize", derive(typesize::derive::TypeSize))]
 #[derive(Clone, Debug, Deserialize, Serialize)]
 #[non_exhaustive]
 pub struct UnfurledMediaItem {
     url: FixedString<u16>,
 }
 
+/// A resolved unfurled media item, with extra metadata added by Discord.
+///
+/// [Incomplete Discord docs](https://github.com/Lulalaby/discord-api-docs/pull/30)
 #[cfg_attr(feature = "typesize", derive(typesize::derive::TypeSize))]
 #[derive(Clone, Debug, Deserialize, Serialize)]
 #[non_exhaustive]
@@ -162,6 +186,11 @@ enum_number! {
     }
 }
 
+/// A list of valid components for an accessory of a section.
+///
+/// See [`Section`] for how this works.
+///
+/// [Incomplete Discord docs](https://github.com/Lulalaby/discord-api-docs/pull/30)
 #[cfg_attr(feature = "typesize", derive(typesize::derive::TypeSize))]
 #[derive(Clone, Debug, Serialize)]
 #[non_exhaustive]
@@ -177,29 +206,51 @@ impl_deserialize_component!(SectionAccessory,
     ComponentType::Thumbnail => SectionAccessory::Thumbnail
 );
 
+/// The valid components a section can contain.
+///
+/// See [`Section`] for other details.
+///
+/// [Incomplete Discord docs](https://github.com/Lulalaby/discord-api-docs/pull/30)
 #[cfg_attr(feature = "typesize", derive(typesize::derive::TypeSize))]
-#[derive(Clone, Debug, Deserialize, Serialize)]
+#[derive(Clone, Debug, Serialize)]
 #[non_exhaustive]
 pub enum SectionComponent {
     TextDisplay(TextDisplay),
     Unknown,
-    // TODO: check others because i'm rushing this.
 }
 
+impl_deserialize_component!(SectionComponent,
+    ComponentType::TextDisplay => SectionComponent::TextDisplay
+);
+
+/// A text display component.
+///
+/// [Incomplete Discord docs](https://github.com/Lulalaby/discord-api-docs/pull/30)
 #[cfg_attr(feature = "typesize", derive(typesize::derive::TypeSize))]
 #[derive(Clone, Debug, Deserialize, Serialize)]
 #[non_exhaustive]
 pub struct TextDisplay {
     content: FixedString<u16>,
 }
 
+/// A media gallery component.
+///
+/// [Incomplete Discord docs](https://github.com/Lulalaby/discord-api-docs/pull/30)
 #[cfg_attr(feature = "typesize", derive(typesize::derive::TypeSize))]
 #[derive(Clone, Debug, Deserialize, Serialize)]
 #[non_exhaustive]
 pub struct MediaGallery {
+    /// Always [`ComponentType::MediaGallery`]
+    #[serde(rename = "type")]
+    pub kind: ComponentType,
     items: FixedArray<MediaGalleryItem>,
 }
 
+/// An individual media gallery item.
+///
+/// Belongs to [`MediaGallery`].
+///
+/// [Incomplete Discord docs](https://github.com/Lulalaby/discord-api-docs/pull/30)
 #[cfg_attr(feature = "typesize", derive(typesize::derive::TypeSize))]
 #[derive(Clone, Debug, Deserialize, Serialize)]
 #[non_exhaustive]
@@ -209,15 +260,22 @@ pub struct MediaGalleryItem {
     spoiler: Option<bool>,
 }
 
+/// A separator component
+///
+/// [Incomplete Discord docs](https://github.com/Lulalaby/discord-api-docs/pull/30)
 #[cfg_attr(feature = "typesize", derive(typesize::derive::TypeSize))]
 #[derive(Clone, Debug, Deserialize, Serialize)]
 #[non_exhaustive]
 pub struct Separator {
+    /// Always [`ComponentType::Separator`]
+    #[serde(rename = "type")]
+    pub kind: ComponentType,
     divider: Option<bool>,
     spacing: Option<SeparatorSpacingSize>,
 }
 
 enum_number! {
+    /// The size of a separator component.
     #[derive(Clone, Copy, Debug, Eq, Hash, Ord, PartialEq, PartialOrd, Deserialize, Serialize)]
     #[cfg_attr(feature = "typesize", derive(typesize::derive::TypeSize))]
     #[non_exhaustive]
@@ -228,18 +286,30 @@ enum_number! {
     }
 }
 
+/// A file component, will not render a text preview to the user.
+///
+/// [Incomplete Discord docs](https://github.com/Lulalaby/discord-api-docs/pull/30)
 #[derive(Clone, Debug, Deserialize, Serialize)]
 #[cfg_attr(feature = "typesize", derive(typesize::derive::TypeSize))]
 #[non_exhaustive]
 pub struct FileComponent {
+    /// Always [`ComponentType::File`]
+    #[serde(rename = "type")]
+    pub kind: ComponentType,
     file: UnfurledMediaItem,
     spoiler: Option<bool>,
 }
 
+/// A container component, similar to an embed but without all the functionality.
+///
+/// [Incomplete Discord docs](https://github.com/Lulalaby/discord-api-docs/pull/30)
 #[derive(Clone, Debug, Deserialize, Serialize)]
 #[cfg_attr(feature = "typesize", derive(typesize::derive::TypeSize))]
 #[non_exhaustive]
 pub struct Container {
+    /// Always [`ComponentType::Container`]
+    #[serde(rename = "type")]
+    pub kind: ComponentType,
     accent_color: Option<Colour>,
     spoiler: Option<bool>,
     components: FixedArray<Component>,

src/model/channel/message.rs

@@ -998,9 +998,21 @@ bitflags! {
         /// As of 2023-04-20, bots are currently not able to send voice messages
         /// ([source](https://github.com/discord/discord-api-docs/pull/6082)).
         const IS_VOICE_MESSAGE = 1 << 13;
-        /// TODO: document
-        /// for me: when enabled, content and embeds can't be used.
+        /// Enables support for sending Components V2.
+        ///
+        /// Setting this flag is required to use V2 components.
+        /// Attempting to send V2 components without enabling this flag will result in an error.
+        ///
+        /// # Limitations
+        /// When this flag is enabled, certain restrictions apply:
+        /// - The `content` and `embeds` fields cannot be set.
+        /// - Audio file attachments are not supported.
+        /// - Files will not have a simple text preview.
+        /// - URLs will not generate embeds.
+        ///
+        /// For more details, refer to the Discord documentation: [https://github.com/Lulalaby/discord-api-docs/pull/30]
         const IS_COMPONENTS_V2 = 1 << 15;
+
     }
 }