Add/improve xml comments for commands and interactions (#124)

KubaZ2 · web-flow · commit cf137671637f · 2025-06-09T00:15:04.000+02:00
* Add xml comments for application command properties and for application command attributes

* Add xml comments for `SubSlashCommandAttribute`

* Add xml docs for slash command parameter and choice attributes

* Add xml docs for `CommandAttribute` and refactor a bit

* Add xml comments for `CommandParameterAttribute` and revert previous refactor partially

* Revert the previous refactor completely

* Add xml docs for component interactions

* Remove AttributeUsage

* Fix MaxValue xml comment

* Fix an xml comment of SlashCommandProperties

* Improve formality
diff --git a/Documentation/guides/services/application-commands/Localizations/AnimalModule.cs b/Documentation/guides/services/application-commands/Localizations/AnimalModule.cs
@@ -17,6 +17,6 @@ public enum Animal
     Dog,
     Cat,
     Fish,
-    [SlashCommandChoice("Guinea Pig")]
+    [SlashCommandChoice(Name = "Guinea Pig")]
     GuineaPig,
 }
diff --git a/Documentation/guides/services/application-commands/Parameters/Animal.cs b/Documentation/guides/services/application-commands/Parameters/Animal.cs
@@ -7,6 +7,6 @@ public enum Animal
     Dog,
     Cat,
     Fish,
-    [SlashCommandChoice("Guinea Pig")]
+    [SlashCommandChoice(Name = "Guinea Pig")]
     GuineaPig,
 }
diff --git a/NetCord.Services/ApplicationCommands/ApplicationCommandAttribute.cs b/NetCord.Services/ApplicationCommands/ApplicationCommandAttribute.cs
@@ -1,5 +1,6 @@
 ﻿namespace NetCord.Services.ApplicationCommands;
 
+/// <inheritdoc cref="Rest.ApplicationCommandProperties" />
 [AttributeUsage(AttributeTargets.Method, AllowMultiple = true)]
 public abstract class ApplicationCommandAttribute : Attribute
 {
@@ -8,8 +9,10 @@ private protected ApplicationCommandAttribute(string name)
         Name = name;
     }
 
+    /// <inheritdoc cref="Rest.ApplicationCommandProperties.Name" />
     public string Name { get; }
 
+    /// <inheritdoc cref="Rest.ApplicationCommandProperties.DefaultGuildUserPermissions" />
     public Permissions DefaultGuildUserPermissions
     {
         get => _defaultGuildUserPermissions.GetValueOrDefault();
@@ -21,6 +24,7 @@ public Permissions DefaultGuildUserPermissions
 
     internal readonly Permissions? _defaultGuildUserPermissions;
 
+    /// <inheritdoc cref="Rest.ApplicationCommandProperties.DMPermission" />
     [Obsolete($"Replaced by '{nameof(Contexts)}'.")]
     public bool DMPermission
     {
@@ -33,15 +37,22 @@ public bool DMPermission
 
     internal readonly bool? _dMPermission;
 
+    /// <inheritdoc cref="Rest.ApplicationCommandProperties.DefaultPermission" />
     [Obsolete($"Replaced by '{nameof(DefaultGuildUserPermissions)}'.")]
     public bool DefaultPermission { get; init; } = true;
 
+    /// <inheritdoc cref="Rest.ApplicationCommandProperties.IntegrationTypes" />
     public ApplicationIntegrationType[]? IntegrationTypes { get; init; }
 
+    /// <inheritdoc cref="Rest.ApplicationCommandProperties.Contexts" />
     public InteractionContextType[]? Contexts { get; init; }
 
+    /// <inheritdoc cref="Rest.ApplicationCommandProperties.Nsfw" />
     public bool Nsfw { get; init; }
 
+    /// <summary>
+    /// The ID of the guild where the application command is registered.
+    /// </summary>
     public ulong GuildId
     {
         get => _guildId.GetValueOrDefault();
diff --git a/NetCord.Services/ApplicationCommands/EntryPointCommandAttribute.cs b/NetCord.Services/ApplicationCommands/EntryPointCommandAttribute.cs
@@ -1,7 +1,9 @@
 ﻿namespace NetCord.Services.ApplicationCommands;
 
+/// <inheritdoc cref="Rest.EntryPointCommandProperties" />
 [AttributeUsage(AttributeTargets.Class | AttributeTargets.Method, AllowMultiple = true)]
 public class EntryPointCommandAttribute(string name, string description) : ApplicationCommandAttribute(name)
 {
+    /// <inheritdoc cref="Rest.EntryPointCommandProperties.Description" />
     public string Description { get; } = description;
 }
diff --git a/NetCord.Services/ApplicationCommands/MessageCommandAttribute.cs b/NetCord.Services/ApplicationCommands/MessageCommandAttribute.cs
@@ -1,5 +1,6 @@
 ﻿namespace NetCord.Services.ApplicationCommands;
 
+/// <inheritdoc cref="Rest.MessageCommandProperties" />
 public class MessageCommandAttribute(string name) : ApplicationCommandAttribute(name)
 {
 }
diff --git a/NetCord.Services/ApplicationCommands/SlashCommandAttribute.cs b/NetCord.Services/ApplicationCommands/SlashCommandAttribute.cs
@@ -1,7 +1,9 @@
 ﻿namespace NetCord.Services.ApplicationCommands;
 
+/// <inheritdoc cref="Rest.SlashCommandProperties" />
 [AttributeUsage(AttributeTargets.Class | AttributeTargets.Method, AllowMultiple = true)]
 public class SlashCommandAttribute(string name, string description) : ApplicationCommandAttribute(name)
 {
+    /// <inheritdoc cref="Rest.SlashCommandProperties.Description" />
     public string Description { get; } = description;
 }
diff --git a/NetCord.Services/ApplicationCommands/SlashCommandChoiceAttribute.cs b/NetCord.Services/ApplicationCommands/SlashCommandChoiceAttribute.cs
@@ -1,7 +1,13 @@
 ﻿namespace NetCord.Services.ApplicationCommands;
 
+/// <summary>
+/// Specifies metadata for a choice of a slash command parameter.
+/// </summary>
 [AttributeUsage(AttributeTargets.Field)]
-public class SlashCommandChoiceAttribute(string name) : Attribute
+public class SlashCommandChoiceAttribute : Attribute
 {
-    public string Name { get; } = name;
+    /// <summary>
+    /// Name of the choice (1-100 characters).
+    /// </summary>
+    public string? Name { get; init; }
 }
diff --git a/NetCord.Services/ApplicationCommands/SlashCommandParameterAttribute.cs b/NetCord.Services/ApplicationCommands/SlashCommandParameterAttribute.cs
@@ -2,13 +2,26 @@
 
 namespace NetCord.Services.ApplicationCommands;
 
+/// <summary>
+/// Specifies metadata for a parameter of a slash command.
+/// Use this attribute to configure how a parameter is presented and validated.
+/// </summary>
 [AttributeUsage(AttributeTargets.Parameter)]
 public class SlashCommandParameterAttribute : Attribute
 {
+    /// <summary>
+    /// Name of the parameter (1-32 characters).
+    /// </summary>
     public string? Name { get; init; }
 
+    /// <summary>
+    /// Description of the parameter (1-100 characters).
+    /// </summary>
     public string? Description { get; init; }
 
+    /// <summary>
+    /// Maximum value permitted for the parameter.
+    /// </summary>
     public double MaxValue
     {
         get => _maxValue.GetValueOrDefault();
@@ -20,6 +33,9 @@ public double MaxValue
 
     internal readonly double? _maxValue;
 
+    /// <summary>
+    /// Minimum value permitted for the parameter.
+    /// </summary>
     public double MinValue
     {
         get => _minValue.GetValueOrDefault();
@@ -31,6 +47,9 @@ public double MinValue
 
     internal readonly double? _minValue;
 
+    /// <summary>
+    /// Maximum length of the parameter value (1-6000).
+    /// </summary>
     public int MaxLength
     {
         get => _maxLength.GetValueOrDefault();
@@ -42,6 +61,9 @@ public int MaxLength
 
     internal readonly int? _maxLength;
 
+    /// <summary>
+    /// Minimum length of the parameter value (0-6000).
+    /// </summary>
     public int MinLength
     {
         get => _minLength.GetValueOrDefault();
@@ -53,14 +75,26 @@ public int MinLength
 
     internal readonly int? _minLength;
 
+    /// <summary>
+    /// If the option is a channel type, the channels shown will be restricted to these types.
+    /// </summary>
     public ChannelType[]? AllowedChannelTypes { get; init; }
 
+    /// <summary>
+    /// Type reader for the parameter, used to convert the input value to the specified type.
+    /// </summary>
     [DynamicallyAccessedMembers(DynamicallyAccessedMemberTypes.PublicParameterlessConstructor)]
     public Type? TypeReaderType { get; init; }
 
+    /// <summary>
+    /// Provider for choices for the parameter, allowing users to select from predefined options.
+    /// </summary>
     [DynamicallyAccessedMembers(DynamicallyAccessedMemberTypes.PublicParameterlessConstructor)]
     public Type? ChoicesProviderType { get; init; }
 
+    /// <summary>
+    /// Provider for autocomplete functionality, allowing dynamic suggestions based on user input.
+    /// </summary>
     [DynamicallyAccessedMembers(DynamicallyAccessedMemberTypes.PublicConstructors)]
     public Type? AutocompleteProviderType { get; init; }
 }
diff --git a/NetCord.Services/ApplicationCommands/SubSlashCommandAttribute.cs b/NetCord.Services/ApplicationCommands/SubSlashCommandAttribute.cs
@@ -1,9 +1,20 @@
 ﻿namespace NetCord.Services.ApplicationCommands;
 
+/// <summary>
+/// Sub slash command allowing to create nested slash commands within a slash command.
+/// </summary>
+/// <param name="name"><inheritdoc cref="Name" path="/summary" /></param>
+/// <param name="description"><inheritdoc cref="Description" path="/summary" /></param>
 [AttributeUsage(AttributeTargets.Class | AttributeTargets.Method, AllowMultiple = true)]
 public class SubSlashCommandAttribute(string name, string description) : Attribute
 {
+    /// <summary>
+    /// Name of the sub slash command (1-32 characters).
+    /// </summary>
     public string Name { get; } = name;
 
+    /// <summary>
+    /// Description of the sub slash command (1-100 characters).
+    /// </summary>
     public string Description { get; } = description;
 }
diff --git a/NetCord.Services/ApplicationCommands/UserCommandAttribute.cs b/NetCord.Services/ApplicationCommands/UserCommandAttribute.cs
@@ -1,5 +1,6 @@
 ﻿namespace NetCord.Services.ApplicationCommands;
 
+/// <inheritdoc cref="Rest.UserCommandProperties" />
 public class UserCommandAttribute(string name) : ApplicationCommandAttribute(name)
 {
 }
diff --git a/NetCord.Services/Commands/CommandAttribute.cs b/NetCord.Services/Commands/CommandAttribute.cs
@@ -1,8 +1,21 @@
 ﻿namespace NetCord.Services.Commands;
 
+/// <summary>
+/// Commands are text-based commands that can be invoked by users in a chat by sending a message, typically starting with a prefix.
+/// </summary>
+/// <param name="aliases"><inheritdoc cref="Aliases" path="/summary" /></param>
 [AttributeUsage(AttributeTargets.Method)]
 public class CommandAttribute(params string[] aliases) : Attribute
 {
+    /// <summary>
+    /// Aliases of the command.
+    /// </summary>
     public string[] Aliases { get; } = aliases;
+
+    /// <summary>
+    /// Priority of the command.
+    /// Commands are matched in order of descending priority, and the first command that matches the input is executed.
+    /// Higher values indicate higher priority.
+    /// </summary>
     public int Priority { get; init; }
 }
diff --git a/NetCord.Services/Commands/CommandParameterAttribute.cs b/NetCord.Services/Commands/CommandParameterAttribute.cs
@@ -2,13 +2,25 @@
 
 namespace NetCord.Services.Commands;
 
+/// <summary>
+/// Specifies metadata for a parameter of a command.
+/// </summary>
 [AttributeUsage(AttributeTargets.Parameter)]
 public class CommandParameterAttribute : Attribute
 {
+    /// <summary>
+    /// Name of the parameter.
+    /// </summary>
     public string? Name { get; init; }
 
+    /// <summary>
+    /// Indicates whether the parameter is parsed as a remainder, meaning that it captures the rest of the input after the command and preceding parameters.
+    /// </summary>
     public bool Remainder { get; init; }
 
+    /// <summary>
+    /// Type reader for the parameter, used to convert the input value to the specified type.
+    /// </summary>
     [DynamicallyAccessedMembers(DynamicallyAccessedMemberTypes.PublicParameterlessConstructor)]
     public Type? TypeReaderType { get; init; }
 }
diff --git a/NetCord.Services/ComponentInteractions/ComponentInteractionAttribute.cs b/NetCord.Services/ComponentInteractions/ComponentInteractionAttribute.cs
@@ -1,7 +1,14 @@
 ﻿namespace NetCord.Services.ComponentInteractions;
 
+/// <summary>
+/// Component interactions are interactions that are triggered by user actions on components, such as buttons, select menus, and modals.
+/// </summary>
+/// <param name="customId"><inheritdoc cref="CustomId" path="/summary" /></param>
 [AttributeUsage(AttributeTargets.Method)]
 public class ComponentInteractionAttribute(string customId) : Attribute
 {
+    /// <summary>
+    /// The custom identifier for the component interaction (0-100 characters).
+    /// </summary>
     public string CustomId { get; } = customId;
 }
diff --git a/NetCord.Services/ComponentInteractions/ComponentInteractionParameterAttribute.cs b/NetCord.Services/ComponentInteractions/ComponentInteractionParameterAttribute.cs
@@ -2,11 +2,20 @@
 
 namespace NetCord.Services.ComponentInteractions;
 
+/// <summary>
+/// Specifies metadata for a parameter of a component interaction.
+/// </summary>
 [AttributeUsage(AttributeTargets.Parameter)]
 public class ComponentInteractionParameterAttribute : Attribute
 {
+    /// <summary>
+    /// Name of the parameter.
+    /// </summary>
     public string? Name { get; init; }
 
+    /// <summary>
+    /// Type reader for the parameter, used to convert the input value to the specified type.
+    /// </summary>
     [DynamicallyAccessedMembers(DynamicallyAccessedMemberTypes.PublicParameterlessConstructor)]
     public Type? TypeReaderType { get; init; }
 }
diff --git a/NetCord.Services/EnumTypeReaders/SlashCommandEnumTypeReader.cs b/NetCord.Services/EnumTypeReaders/SlashCommandEnumTypeReader.cs
@@ -37,7 +37,7 @@ async ValueTask<ApplicationCommandOptionChoiceProperties> CreateChoiceAsync(Fiel
 
             var attribute = field.GetCustomAttribute<SlashCommandChoiceAttribute>();
 
-            var name = attribute is null ? field.Name : attribute.Name;
+            var name = attribute is null ? field.Name : (attribute.Name ?? field.Name);
 
             ApplicationCommandOptionChoiceProperties result = new(name, value);
 
diff --git a/NetCord/Rest/EntryPointCommandProperties.cs b/NetCord/Rest/EntryPointCommandProperties.cs
@@ -3,11 +3,12 @@
 namespace NetCord.Rest;
 
 /// <summary>
-/// 
+/// Entry point command serves as the primary way for users to open an app's Activity from the App Launcher.
+/// You can create only a single Entry Point command per app.
 /// </summary>
-/// <param name="name">Name of the command (1-32 characters).</param>
-/// <param name="description">Description of the command (1-100 characters).</param>
-/// <param name="handler">Determines whether the interaction is handled by the app's interactions handler or by Discord.</param>
+/// <param name="name"><inheritdoc cref="ApplicationCommandProperties.Name" path="/summary" /></param>
+/// <param name="description"><inheritdoc cref="Description" path="/summary" /></param>
+/// <param name="handler"><inheritdoc cref="Handler" path="/summary" /></param>
 public partial class EntryPointCommandProperties(string name, string description, EntryPointCommandHandler handler) : ApplicationCommandProperties(ApplicationCommandType.EntryPoint, name)
 {
     /// <summary>
diff --git a/NetCord/Rest/MessageCommandProperties.cs b/NetCord/Rest/MessageCommandProperties.cs
@@ -1,9 +1,10 @@
 ﻿namespace NetCord.Rest;
 
 /// <summary>
-/// 
+/// Message commands are application commands that appear on the context menu (right click or tap) of messages.
+/// They are a great way to surface quick actions for your app that target messages.
 /// </summary>
-/// <param name="name">Name of the command (1-32 characters).</param>
+/// <param name="name"><inheritdoc cref="ApplicationCommandProperties.Name" path="/summary" /></param>
 public partial class MessageCommandProperties(string name) : ApplicationCommandProperties(ApplicationCommandType.Message, name)
 {
 }
diff --git a/NetCord/Rest/SlashCommandProperties.cs b/NetCord/Rest/SlashCommandProperties.cs
@@ -3,10 +3,11 @@
 namespace NetCord.Rest;
 
 /// <summary>
-/// 
+/// Slash commands are application commands that are invoked by typing a slash (/) in the chat input box.
+/// They allow users to interact with your application.
 /// </summary>
-/// <param name="name">Name of the command (1-32 characters).</param>
-/// <param name="description">Description of the command (1-100 characters).</param>
+/// <param name="name"><inheritdoc cref="ApplicationCommandProperties.Name" path="/summary" /> Must be lowercase.</param>
+/// <param name="description"><inheritdoc cref="Description" path="/summary" /></param>
 public partial class SlashCommandProperties(string name, string description) : ApplicationCommandProperties(ApplicationCommandType.ChatInput, name)
 {
     /// <summary>
diff --git a/NetCord/Rest/UserCommandProperties.cs b/NetCord/Rest/UserCommandProperties.cs
@@ -1,9 +1,10 @@
 ﻿namespace NetCord.Rest;
 
 /// <summary>
-/// 
+/// User commands are application commands that appear on the context menu (right click or tap) of users.
+/// They are a great way to surface quick actions for your app that target users.
 /// </summary>
-/// <param name="name">Name of the command (1-32 characters).</param>
+/// <param name="name"><inheritdoc cref="ApplicationCommandProperties.Name" path="/summary" /></param>
 public partial class UserCommandProperties(string name) : ApplicationCommandProperties(ApplicationCommandType.User, name)
 {
 }
diff --git a/Tests/NetCord.Test/ApplicationCommands/Commands.cs b/Tests/NetCord.Test/ApplicationCommands/Commands.cs
@@ -353,20 +353,20 @@ public Task EntityMenusAsync([SlashCommandParameter(Name = "min_values", MinValu
 
 public enum DeleteMessagesDays
 {
-    [SlashCommandChoice("Don't remove")]
+    [SlashCommandChoice(Name = "Don't remove")]
     DontRemove = 0 * 24 * 60 * 60,
-    [SlashCommandChoice("Last 24 hours")]
+    [SlashCommandChoice(Name = "Last 24 hours")]
     Last24Hours = 1 * 24 * 60 * 60,
-    [SlashCommandChoice("Last 2 days")]
+    [SlashCommandChoice(Name = "Last 2 days")]
     Last2Days = 2 * 24 * 60 * 60,
-    [SlashCommandChoice("Last 3 days")]
+    [SlashCommandChoice(Name = "Last 3 days")]
     Last3Days = 3 * 24 * 60 * 60,
-    [SlashCommandChoice("Last 4 days")]
+    [SlashCommandChoice(Name = "Last 4 days")]
     Last4Days = 4 * 24 * 60 * 60,
-    [SlashCommandChoice("Last 5 days")]
+    [SlashCommandChoice(Name = "Last 5 days")]
     Last5Days = 5 * 24 * 60 * 60,
-    [SlashCommandChoice("Last 6 days")]
+    [SlashCommandChoice(Name = "Last 6 days")]
     Last6Days = 6 * 24 * 60 * 60,
-    [SlashCommandChoice("Last week")]
+    [SlashCommandChoice(Name = "Last week")]
     LastWeek = 7 * 24 * 60 * 60,
 }

Original file line number	Diff line number	Diff line change
`@@ -17,6 +17,6 @@ public enum Animal`
`17`	`17`	`Dog,`
`18`	`18`	`Cat,`
`19`	`19`	`Fish,`
`20`		`- [SlashCommandChoice("Guinea Pig")]`
	`20`	`+ [SlashCommandChoice(Name = "Guinea Pig")]`
`21`	`21`	`GuineaPig,`
`22`	`22`	`}`
Original file line number	Diff line number	Diff line change
`@@ -7,6 +7,6 @@ public enum Animal`
`7`	`7`	`Dog,`
`8`	`8`	`Cat,`
`9`	`9`	`Fish,`
`10`		`- [SlashCommandChoice("Guinea Pig")]`
	`10`	`+ [SlashCommandChoice(Name = "Guinea Pig")]`
`11`	`11`	`GuineaPig,`
`12`	`12`	`}`
Original file line number	Diff line number	Diff line change
`@@ -1,7 +1,9 @@`
`1`	`1`	`namespace NetCord.Services.ApplicationCommands;`
`2`	`2`
	`3`	`+/// <inheritdoc cref="Rest.EntryPointCommandProperties" />`
`3`	`4`	`[AttributeUsage(AttributeTargets.Class \| AttributeTargets.Method, AllowMultiple = true)]`
`4`	`5`	`public class EntryPointCommandAttribute(string name, string description) : ApplicationCommandAttribute(name)`
`5`	`6`	`{`
	`7`	`+ /// <inheritdoc cref="Rest.EntryPointCommandProperties.Description" />`
`6`	`8`	`public string Description { get; } = description;`
`7`	`9`	`}`
Original file line number	Diff line number	Diff line change
`@@ -1,5 +1,6 @@`
`1`	`1`	`namespace NetCord.Services.ApplicationCommands;`
`2`	`2`
	`3`	`+/// <inheritdoc cref="Rest.MessageCommandProperties" />`
`3`	`4`	`public class MessageCommandAttribute(string name) : ApplicationCommandAttribute(name)`
`4`	`5`	`{`
`5`	`6`	`}`
Original file line number	Diff line number	Diff line change
`@@ -1,7 +1,9 @@`
`1`	`1`	`namespace NetCord.Services.ApplicationCommands;`
`2`	`2`
	`3`	`+/// <inheritdoc cref="Rest.SlashCommandProperties" />`
`3`	`4`	`[AttributeUsage(AttributeTargets.Class \| AttributeTargets.Method, AllowMultiple = true)]`
`4`	`5`	`public class SlashCommandAttribute(string name, string description) : ApplicationCommandAttribute(name)`
`5`	`6`	`{`
	`7`	`+ /// <inheritdoc cref="Rest.SlashCommandProperties.Description" />`
`6`	`8`	`public string Description { get; } = description;`
`7`	`9`	`}`
Original file line number	Diff line number	Diff line change
`@@ -1,5 +1,6 @@`
`1`	`1`	`namespace NetCord.Services.ApplicationCommands;`
`2`	`2`
	`3`	`+/// <inheritdoc cref="Rest.UserCommandProperties" />`
`3`	`4`	`public class UserCommandAttribute(string name) : ApplicationCommandAttribute(name)`
`4`	`5`	`{`
`5`	`6`	`}`