Combine a struct and document all the things

diamondburned · Aug 6, 2024 · 35c61e8 · 35c61e8
1 parent e1b274b
commit 35c61e8
Show file tree

Hide file tree

Showing 2 changed files with 70 additions and 30 deletions.
diff --git a/api/automoderation.go b/api/automoderation.go
@@ -5,6 +5,9 @@ import (
 	"github.com/diamondburned/arikawa/v3/utils/httputil"
 )
 
+// Get a list of all rules currently configured for the guild. Returns a list of auto moderation rule objects for the given guild.
+//
+// This endpoint requires the MANAGE_GUILD permission.
 func (c *Client) ListAutoModerationRules(guildID discord.GuildID) ([]discord.AutoModerationRule, error) {
 	var rules []discord.AutoModerationRule
 	return rules, c.RequestJSON(
@@ -13,6 +16,9 @@ func (c *Client) ListAutoModerationRules(guildID discord.GuildID) ([]discord.Aut
 	)
 }
 
+// Get a single rule. Returns an auto moderation rule object.
+//
+// This endpoint requires the MANAGE_GUILD permission.
 func (c *Client) GetAutoModerationRule(guildID discord.GuildID, ruleID discord.AutoModerationRuleID) (discord.AutoModerationRule, error) {
 	var rule discord.AutoModerationRule
 	return rule, c.RequestJSON(
@@ -21,31 +27,37 @@ func (c *Client) GetAutoModerationRule(guildID discord.GuildID, ruleID discord.A
 	)
 }
 
-type CreateAutomoderationRulePayload struct {
-	Name            string                                `json:"name"`
-	EventType       discord.AutoModerationEventTypes      `json:"event_type"`
-	TriggerType     discord.AutoModerationTriggerTypes    `json:"trigger_type"`
-	TriggerMetadata discord.AutoModerationTriggerMetadata `json:"trigger_metadata,omitempty"`
-	Actions         []discord.AutoModerationAction        `json:"actions"`
-	Enabled         bool                                  `json:"enabled,omitempty"`
-	ExemptRoles     []discord.RoleID                      `json:"exempt_roles,omitempty"`
-	ExemptChannels  []discord.ChannelID                   `json:"exempt_channels,omitempty"`
-}
-
-func (c *Client) CreateAutoModerationRule(guildID discord.GuildID, rule CreateAutomoderationRulePayload) (*discord.AutoModerationRule, error) {
+// Create a new rule. Returns an auto moderation rule on success. Fires an Auto Moderation Rule Create Gateway event.
+//
+// This endpoint requires the MANAGE_GUILD permission.
+//
+// This endpoint supports the X-Audit-Log-Reason header.
+func (c *Client) CreateAutoModerationRule(guildID discord.GuildID, rule discord.AutoModerationRule) (*discord.AutoModerationRule, error) {
 	var ret *discord.AutoModerationRule
 	return ret, c.RequestJSON(&ret, "POST", EndpointGuilds+guildID.String()+"/auto-moderation/rules",
 		httputil.WithJSONBody(rule),
 	)
 }
 
-func (c *Client) ModifyAutoModerationRule(guildID discord.GuildID, ruleID discord.AutoModerationRuleID, rule CreateAutomoderationRulePayload) (*discord.AutoModerationRule, error) {
+// Modify an existing rule. Returns an auto moderation rule on success. Fires an Auto Moderation Rule Update Gateway event.
+//
+// Requires MANAGE_GUILD permissions.
+//
+// All parameters for this endpoint are optional.
+//
+// This endpoint supports the X-Audit-Log-Reason header.
+func (c *Client) ModifyAutoModerationRule(guildID discord.GuildID, ruleID discord.AutoModerationRuleID, rule discord.AutoModerationRule) (*discord.AutoModerationRule, error) {
 	var ret *discord.AutoModerationRule
 	return ret, c.RequestJSON(&ret, "PATCH", EndpointGuilds+guildID.String()+"/auto-moderation/rules/"+ruleID.String(),
 		httputil.WithJSONBody(rule),
 	)
 }
 
+// Delete a rule. Returns a 204 on success. Fires an Auto Moderation Rule Delete Gateway event.
+//
+// This endpoint requires the MANAGE_GUILD permission.
+//
+// This endpoint supports the X-Audit-Log-Reason header.
 func (c *Client) DeleteAutoModerationRule(guildID discord.GuildID, ruleID discord.AutoModerationRuleID) error {
 	return c.FastRequest("DELETE", EndpointGuilds+guildID.String()+"/auto-moderation/rules/"+ruleID.String())
 }
diff --git a/discord/automoderation.go b/discord/automoderation.go
@@ -26,18 +26,29 @@ const (
 )
 
 type AutoModerationTriggerMetadata struct {
-	KeywordFilter                []string                           `json:"keyword_filter"`
-	RegexPatterns                []string                           `json:"regex_patterns"`
-	Presets                      []AutoModerationKeywordPresetTypes `json:"presets"`
-	AllowList                    []string                           `json:"allow_list"`
-	MentionTotalLimit            int                                `json:"mention_total_limit"`
-	MentionRaidProtectionEnabled bool                               `json:"mention_raid_protection_enabled"`
+	// substrings which will be searched for in content (Maximum of 1000)
+	KeywordFilter []string `json:"keyword_filter"`
+	// regular expression patterns which will be matched against content (Maximum of 10)
+	RegexPatterns []string `json:"regex_patterns"`
+	// the internally pre-defined wordsets which will be searched for in content
+	Presets []AutoModerationKeywordPresetTypes `json:"presets"`
+	// substrings which should not trigger the rule (Maximum of 100 or 1000)
+	AllowList []string `json:"allow_list"`
+	// total number of unique role and user mentions allowed per message (Maximum of 50)
+	MentionTotalLimit int `json:"mention_total_limit"`
+	// whether to automatically detect mention raids
+	MentionRaidProtectionEnabled bool `json:"mention_raid_protection_enabled"`
 }
 
 type AutoModerationActionMetadata struct {
-	ChannelID       ChannelID `json:"channel_id"`
-	DurationSeconds int       `json:"duration_seconds"`
-	CustomMessage   string    `json:"custom_message,omitempty"`
+	// channel to which user content should be logged
+	ChannelID ChannelID `json:"channel_id"`
+	// timeout duration in seconds
+	// maximum of 2419200 seconds (4 weeks)
+	DurationSeconds int `json:"duration_seconds"`
+	// additional explanation that will be shown to members whenever their message is blocked
+	// maximum of 150 characters
+	CustomMessage string `json:"custom_message,omitempty"`
 }
 
 type AutoModerationActionTypes uint32
@@ -50,16 +61,33 @@ const (
 )
 
 type AutoModerationAction struct {
-	Type     AutoModerationActionTypes    `json:"type"`
+	// the type of action
+	Type AutoModerationActionTypes `json:"type"`
+	// additional metadata needed during execution for this specific action type
 	Metadata AutoModerationActionMetadata `json:"metadata,omitempty"`
 }
 
 type AutoModerationRule struct {
-	ID              AutoModerationRuleID     `json:"id"`
-	GuildID         GuildID                  `json:"guild_id"`
-	Name            string                   `json:"name"`
-	CreatorID       UserID                   `json:"creator_id"`
-	EventType       AutoModerationEventTypes `json:"event_type"`
-	TriggerType     AutoModerationTriggerTypes
-	TriggerMetadata AutoModerationTriggerMetadata `json:"trigger_metadata"`
+	// the id of this rule
+	ID AutoModerationRuleID `json:"id"`
+	// the id of the guild which this rule belongs to
+	GuildID GuildID `json:"guild_id"`
+	// the rule name
+	Name string `json:"name"`
+	// the user which first created this rule
+	CreatorID UserID `json:"creator_id,omitempty"`
+	// the rule event type
+	EventType AutoModerationEventTypes `json:"event_type"`
+	// the rule trigger type
+	TriggerType AutoModerationTriggerTypes
+	// the rule trigger metadata
+	TriggerMetadata AutoModerationTriggerMetadata `json:"trigger_metadata,omitempty"`
+	// the actions which will execute when the rule is triggered
+	Actions []AutoModerationAction `json:"actions"`
+	// whether the rule is enabled
+	Enabled bool `json:"enabled,omitempty"`
+	// the role ids that should not be affected by the rule (Maximum of 20)
+	ExemptRoles []RoleID `json:"exempt_roles,omitempty"`
+	// the channel ids that should not be affected by the rule (Maximum of 50)
+	ExemptChannels []ChannelID `json:"exempt_channels,omitempty"`
 }