📝 Add docstrings to development

crates/dapi/src/api/automoderation/create_auto_moderation_rule.rs

@@ -10,6 +10,25 @@ pub struct CreateAutoModerationRule {
 impl ApiReq for CreateAutoModerationRule {
     type Resp = serde_json::Value;
 
+    /// Creates an auto-moderation rule after validating the request and permissions.
+    ///
+    /// Validates the provided `reason` and the embedded rule `data`, ensures the current bot user exists
+    /// and has the `MANAGE_GUILD` permission, then calls the controller to create and return the rule.
+    ///
+    /// # Returns
+    /// The created auto-moderation rule as a `serde_json::Value`.
+    ///
+    /// # Examples
+    ///
+    /// ```ignore
+    /// // In an async context with a valid `DiscordContext`
+    /// let req = CreateAutoModerationRule {
+    ///     reason: "Block spam messages".into(),
+    ///     data: /* CreateAutoModRule value */,
+    /// };
+    /// let created = req.execute(&ctx).await?;
+    /// assert!(created.is_object());
+    /// ```
     async fn execute<T: DiscordProvider>(self, this: &DiscordContext<T>) -> Result<Self::Resp, crate::Error> {
         this.check_reason(&self.reason)?;
 
@@ -30,7 +49,19 @@ impl ApiReq for CreateAutoModerationRule {
         Ok(rule)
     }
 
+    /// Converts this request into the corresponding `crate::apilist::API` enum variant.
+    ///
+    /// # Examples
+    ///
+    /// ```
+    /// let req = CreateAutoModerationRule { reason: "spam".into(), data: Default::default() };
+    /// let api = req.to_apilist();
+    /// match api {
+    ///     crate::apilist::API::CreateAutoModerationRule(_) => {},
+    ///     _ => panic!("expected CreateAutoModerationRule variant"),
+    /// }
+    /// ```
     fn to_apilist(self) -> crate::apilist::API {
         crate::apilist::API::CreateAutoModerationRule(self)
     }
-}
+}

crates/dapi/src/api/automoderation/delete_auto_moderation_rule.rs

@@ -10,6 +10,21 @@ pub struct DeleteAutoModerationRule {
 impl ApiReq for DeleteAutoModerationRule {
     type Resp = ();
 
+    /// Deletes an auto moderation rule after validating the provided reason and verifying permissions.
+    ///
+    /// Validates `reason` with the context, ensures the current bot user is available and has the `MANAGE_GUILD` permission, then instructs the controller to delete the rule identified by `self.rule_id`.
+    ///
+    /// # Errors
+    ///
+    /// Returns an error if reason validation fails, the current user is not found, the bot lacks `MANAGE_GUILD` permission, or the controller fails to delete the rule.
+    ///
+    /// # Examples
+    ///
+    /// ```
+    /// // In an async context:
+    /// // let req = DeleteAutoModerationRule { rule_id, reason: "no longer needed".into() };
+    /// // req.execute(&ctx).await?;
+    /// ```
     async fn execute<T: DiscordProvider>(self, this: &DiscordContext<T>) -> Result<Self::Resp, crate::Error> {
         this.check_reason(&self.reason)?;
 
@@ -28,7 +43,22 @@ impl ApiReq for DeleteAutoModerationRule {
         Ok(())
     }
 
+    /// Convert this request into its API list representation.
+    ///
+    /// This consumes the request and wraps it in the `crate::apilist::API::DeleteAutoModerationRule` variant,
+    /// which is used by the API routing layer.
+    ///
+    /// # Examples
+    ///
+    /// ```no_run
+    /// let req = DeleteAutoModerationRule {
+    ///     rule_id: /* a RuleId value */,
+    ///     reason: "violation".to_string(),
+    /// };
+    /// let api = req.to_apilist();
+    /// // `api` is now `crate::apilist::API::DeleteAutoModerationRule(...)`
+    /// ```
     fn to_apilist(self) -> crate::apilist::API {
         crate::apilist::API::DeleteAutoModerationRule(self)
     }
-}
+}

crates/dapi/src/api/automoderation/edit_auto_moderation_rule.rs

@@ -11,6 +11,29 @@ pub struct EditAutoModerationRule {
 impl ApiReq for EditAutoModerationRule {
     type Resp = serde_json::Value;
 
+    /// Edits an auto-moderation rule using the payload and returns the updated rule.
+    ///
+    /// Validates the provided reason and rule data, ensures the current bot user exists and has
+    /// `MANAGE_GUILD` permission, applies the edit via the controller, and returns the resulting rule as JSON.
+    ///
+    /// # Returns
+    ///
+    /// `serde_json::Value` representing the updated auto-moderation rule.
+    ///
+    /// # Examples
+    ///
+    /// ```
+    /// use serenity::all::RuleId;
+    /// use dapi::api::automoderation::edit_auto_moderation_rule::EditAutoModerationRule;
+    ///
+    /// let req = EditAutoModerationRule {
+    ///     rule_id: RuleId::from(1),
+    ///     reason: String::from("Update rule threshold"),
+    ///     data: Default::default(),
+    /// };
+    ///
+    /// assert_eq!(req.reason, "Update rule threshold");
+    /// ```
     async fn execute<T: DiscordProvider>(self, this: &DiscordContext<T>) -> Result<Self::Resp, crate::Error> {
         this.check_reason(&self.reason)?;
 
@@ -31,7 +54,24 @@ impl ApiReq for EditAutoModerationRule {
         Ok(rule)
     }
 
+    /// Create an API list entry representing this edit auto-moderation rule request.
+    ///
+    /// # Examples
+    ///
+    /// ```
+    /// use crate::api::automoderation::edit_auto_moderation_rule::EditAutoModerationRule;
+    /// use crate::apilist::API;
+    ///
+    /// let req = EditAutoModerationRule {
+    ///     rule_id: serenity::all::RuleId(0),
+    ///     reason: String::new(),
+    ///     data: Default::default(),
+    /// };
+    ///
+    /// let api = req.to_apilist();
+    /// matches!(api, API::EditAutoModerationRule(_));
+    /// ```
     fn to_apilist(self) -> crate::apilist::API {
         crate::apilist::API::EditAutoModerationRule(self)
     }
-}
+}

crates/dapi/src/api/channels/create_channel_invite.rs

@@ -11,6 +11,41 @@ pub struct CreateChannelInvite {
 impl ApiReq for CreateChannelInvite {
     type Resp = serde_json::Value;
 
+    /// Creates an invite for the specified channel after validating the provided reason and required permissions.
+    ///
+    /// The request validates the reason string, ensures the current bot user exists, checks that the bot has
+    /// the `CREATE_INSTANT_INVITE` permission on the target channel, and then delegates to the controller to
+    /// create the invite.
+    ///
+    /// # Returns
+    ///
+    /// A `serde_json::Value` containing the created invite object.
+    ///
+    /// # Errors
+    ///
+    /// Returns `Err` if the reason is invalid, the current user is not available, the bot lacks the
+    /// `CREATE_INSTANT_INVITE` permission for the channel, or if the controller call fails.
+    ///
+    /// # Examples
+    ///
+    /// ```rust,ignore
+    /// # async fn run_example() -> Result<(), crate::Error> {
+    /// use your_crate::api::channels::CreateChannelInvite;
+    /// use your_crate::{DiscordContext, DiscordProvider, CreateInvite};
+    ///
+    /// // Construct request (fields shown conceptually)
+    /// let req = CreateChannelInvite {
+    ///     channel_id: /* GenericChannelId */,
+    ///     data: CreateInvite { /* ... */ },
+    ///     reason: "Creating an invite".to_string(),
+    /// };
+    ///
+    /// // Execute using a DiscordContext implementation
+    /// let ctx: DiscordContext<impl DiscordProvider> = /* obtain context */;
+    /// let invite_json = req.execute(&ctx).await?;
+    /// # Ok(())
+    /// # }
+    /// ```
     async fn execute<T: DiscordProvider>(self, this: &DiscordContext<T>) -> Result<Self::Resp, crate::Error> {
         this.check_reason(&self.reason)?;
 
@@ -29,7 +64,15 @@ impl ApiReq for CreateChannelInvite {
         Ok(invite)
     }
 
+    /// Wraps this request in the API enum as the `CreateChannelInvite` variant.
+    ///
+    /// # Examples
+    ///
+    /// ```
+    /// // given `req: CreateChannelInvite`
+    /// let api = req.to_apilist();
+    /// ```
     fn to_apilist(self) -> crate::apilist::API {
         crate::apilist::API::CreateChannelInvite(self)
     }
-}
+}

crates/dapi/src/api/channels/delete_channel.rs

@@ -10,6 +10,27 @@ pub struct DeleteChannel {
 impl ApiReq for DeleteChannel {
     type Resp = serde_json::Value;
 
+    /// Deletes the specified channel after validating the provided reason and the bot's permissions.
+    ///
+    /// The function validates `reason`, ensures the current bot user is available, checks that the bot
+    /// has `manage_threads` for thread channels or `manage_channels` for other channel types, and then
+    /// calls the controller to delete the channel. Returns the deleted channel's JSON representation.
+    ///
+    /// # Returns
+    ///
+    /// The deleted channel payload as a `serde_json::Value`.
+    ///
+    /// # Examples
+    ///
+    /// ```
+    /// # use crate::api::channels::DeleteChannel;
+    /// # use serenity::all::GenericChannelId;
+    /// # async fn example<T: crate::DiscordProvider>(ctx: &crate::DiscordContext<T>) -> Result<(), crate::Error> {
+    /// let req = DeleteChannel { channel_id: GenericChannelId(123), reason: "cleanup".into() };
+    /// let resp = req.execute(ctx).await?;
+    /// println!("{}", resp);
+    /// # Ok(()) }
+    /// ```
     async fn execute<T: DiscordProvider>(self, this: &DiscordContext<T>) -> Result<Self::Resp, crate::Error> {
         this.check_reason(&self.reason)?;
 
@@ -47,7 +68,15 @@ impl ApiReq for DeleteChannel {
         Ok(channel)
     }
 
+    /// Convert this request into the corresponding `apilist::API` variant for dispatch.
+    ///
+    /// # Examples
+    ///
+    /// ```
+    /// let api = crate::api::channels::delete_channel::DeleteChannel::default().to_apilist();
+    /// assert!(matches!(api, crate::apilist::API::DeleteChannel(_)));
+    /// ```
     fn to_apilist(self) -> crate::apilist::API {
         crate::apilist::API::DeleteChannel(self)
     }
-}
+}

crates/dapi/src/api/channels/delete_channel_permission.rs

@@ -11,6 +11,29 @@ pub struct DeleteChannelPermission {
 impl ApiReq for DeleteChannelPermission {
     type Resp = ();
 
+    /// Deletes a permission overwrite for a channel using the provided overwrite target and reason.
+    ///
+    /// Validates the provided reason, ensures the current bot user exists and has the `MANAGE_ROLES` permission,
+    /// and then instructs the controller to remove the permission overwrite for the given channel.
+    ///
+    /// # Returns
+    ///
+    /// `Ok(())` on success, or an error if validation, permission checks, the current user lookup, or controller call fail.
+    ///
+    /// # Examples
+    ///
+    /// ```no_run
+    /// # use crates::api::channels::DeleteChannelPermission;
+    /// # async fn example(ctx: &DiscordContext<impl DiscordProvider>) -> Result<(), crate::Error> {
+    /// let req = DeleteChannelPermission {
+    ///     channel_id,
+    ///     overwrite_id,
+    ///     reason: "remove obsolete overwrite".into(),
+    /// };
+    /// req.execute(ctx).await?;
+    /// # Ok(())
+    /// # }
+    /// ```
     async fn execute<T: DiscordProvider>(self, this: &DiscordContext<T>) -> Result<Self::Resp, crate::Error> {
         this.check_reason(&self.reason)?;
 
@@ -29,7 +52,21 @@ impl ApiReq for DeleteChannelPermission {
         Ok(())
     }
 
+    /// Convert this request into its `apilist::API` enum variant.
+    ///
+    /// # Examples
+    ///
+    /// ```no_run
+    /// use crate::api::channels::delete_channel_permission::DeleteChannelPermission;
+    /// let req = DeleteChannelPermission {
+    ///     channel_id: 0.into(),
+    ///     overwrite_id: 0.into(),
+    ///     reason: "cleanup".into(),
+    /// };
+    /// let api = req.to_apilist();
+    /// matches!(api, crate::apilist::API::DeleteChannelPermission(_));
+    /// ```
     fn to_apilist(self) -> crate::apilist::API {
         crate::apilist::API::DeleteChannelPermission(self)
     }
-}
+}

crates/dapi/src/api/channels/edit_channel_permissions.rs

@@ -15,6 +15,34 @@ pub struct EditChannelPermissions {
 impl ApiReq for EditChannelPermissions {
     type Resp = ();
 
+    /// Edits permission overrides for a channel target after validating the request and the bot's permissions.
+    ///
+    /// Validates the provided reason, ensures the current bot user exists and has the required `MANAGE_ROLES` permission on the channel, verifies that any requested allow/deny permissions are permitted for the bot, and then sends the edit request to the controller.
+    ///
+    /// # Returns
+    ///
+    /// `()` on success, or a `crate::Error` describing why the operation failed.
+    ///
+    /// # Examples
+    ///
+    /// ```
+    /// use serenity::all::{GenericChannelId, TargetId, Permissions};
+    /// use crate::api::channels::EditChannelPermissions;
+    /// use crate::multioption::MultiOption;
+    ///
+    /// # async fn example(context: &crate::context::DiscordContext<impl crate::controller::DiscordProvider>) -> Result<(), crate::Error> {
+    /// let req = EditChannelPermissions {
+    ///     channel_id: GenericChannelId(123),
+    ///     target_id: TargetId::User(456),
+    ///     allow: MultiOption::Some(Permissions::SEND_MESSAGES),
+    ///     deny: MultiOption::None,
+    ///     kind: 0,
+    ///     reason: "Adjusting permissions".into(),
+    /// };
+    ///
+    /// req.execute(context).await?;
+    /// # Ok(()) }
+    /// ```
     async fn execute<T: DiscordProvider>(self, this: &DiscordContext<T>) -> Result<Self::Resp, crate::Error> {
         this.check_reason(&self.reason)?;
 
@@ -58,7 +86,16 @@ impl ApiReq for EditChannelPermissions {
         Ok(())
     }
 
+    /// Convert this request into the API enum variant used by the request dispatcher.
+    ///
+    /// # Examples
+    ///
+    /// ```no_run
+    /// // given an EditChannelPermissions request `req`
+    /// // let req = EditChannelPermissions { /* fields */ };
+    /// let api = req.to_apilist();
+    /// ```
     fn to_apilist(self) -> crate::apilist::API {
         crate::apilist::API::EditChannelPermissions(self)
     }
-}
+}