From 90fdd54926324dad92005a3c60681a186c00950d Mon Sep 17 00:00:00 2001 From: Still Hsu <341464@gmail.com> Date: Fri, 31 Aug 2018 09:27:18 +0800 Subject: [PATCH] Add XML docs --- src/Discord.Net.Commands/CommandService.cs | 39 +++++++++++++++++-- .../Extensions/MessageExtensions.cs | 8 +++- src/Discord.Net.Commands/Info/ModuleInfo.cs | 36 +++++++++++++++++ .../Info/ParameterInfo.cs | 27 +++++++++++++ .../Results/ExecuteResult.cs | 3 ++ .../Extensions/MessageExtensions.cs | 2 +- .../DiscordSocketClient.cs | 20 ++++++++++ .../Entities/Users/SocketSelfUser.cs | 2 +- 8 files changed, 131 insertions(+), 6 deletions(-) diff --git a/src/Discord.Net.Commands/CommandService.cs b/src/Discord.Net.Commands/CommandService.cs index 96677c203..91a6e9e09 100644 --- a/src/Discord.Net.Commands/CommandService.cs +++ b/src/Discord.Net.Commands/CommandService.cs @@ -11,6 +11,22 @@ using Discord.Logging; namespace Discord.Commands { + /// + /// Provides a framework for building Discord commands. + /// + /// + /// + /// The service provides a framework for building Discord commands both dynamically via runtime builders or + /// statically via compile-time modules. To create a command module at compile-time, see + /// (most common); otherwise, see . + /// + /// + /// This service also provides several events for monitoring command usages; such as + /// for any command-related log events, and + /// for information about commands that have + /// been successfully executed. + /// + /// public class CommandService { /// @@ -20,8 +36,19 @@ namespace Discord.Commands internal readonly AsyncEvent> _logEvent = new AsyncEvent>(); /// - /// Occurs when a command is successfully executed without any runtime error. + /// Occurs when a command is successfully executed without any error. /// + /// + /// + /// This event is fired when a command has been successfully executed without any of the following errors: + /// + /// * Parsing error + /// * Precondition error + /// * Runtime exception + /// + /// Should the command encounter any of the aforementioned error, this event will not be raised. + /// + /// public event Func CommandExecuted { add { _commandExecutedEvent.Add(value); } remove { _commandExecutedEvent.Remove(value); } } internal readonly AsyncEvent> _commandExecutedEvent = new AsyncEvent>(); @@ -132,8 +159,14 @@ namespace Discord.Commands /// /// Add a command module from a . /// + /// + /// The following example registers the module MyModule to commandService. + /// + /// await commandService.AddModuleAsync<MyModule>(serviceProvider); + /// + /// /// The type of module. - /// The for your dependency injection solution if using one; otherwise, pass null . + /// The for your dependency injection solution if using one; otherwise, pass null. /// This module has already been added. /// /// The fails to be built; an invalid type may have been provided. @@ -145,7 +178,7 @@ namespace Discord.Commands public Task AddModuleAsync(IServiceProvider services) => AddModuleAsync(typeof(T), services); /// - /// Adds a command module from a . + /// Adds a command module from a . /// /// The type of module. /// The for your dependency injection solution if using one; otherwise, pass null . diff --git a/src/Discord.Net.Commands/Extensions/MessageExtensions.cs b/src/Discord.Net.Commands/Extensions/MessageExtensions.cs index e4a9f7de4..f76df1f2a 100644 --- a/src/Discord.Net.Commands/Extensions/MessageExtensions.cs +++ b/src/Discord.Net.Commands/Extensions/MessageExtensions.cs @@ -3,13 +3,19 @@ using System; namespace Discord.Commands { /// - /// Extension methods for that related to commands. + /// Provides extension methods for that relates to commands. /// public static class MessageExtensions { /// /// Gets whether the message starts with the provided character. /// + /// The message to check against. + /// The char prefix. + /// References where the command starts. + /// + /// true if the message begins with the char ; otherwise false. + /// public static bool HasCharPrefix(this IUserMessage msg, char c, ref int argPos) { var text = msg.Content; diff --git a/src/Discord.Net.Commands/Info/ModuleInfo.cs b/src/Discord.Net.Commands/Info/ModuleInfo.cs index dd486e014..bd75c143c 100644 --- a/src/Discord.Net.Commands/Info/ModuleInfo.cs +++ b/src/Discord.Net.Commands/Info/ModuleInfo.cs @@ -11,18 +11,54 @@ namespace Discord.Commands /// public class ModuleInfo { + /// + /// Gets the command service associated with this module. + /// public CommandService Service { get; } + /// + /// Gets the name of this module. + /// public string Name { get; } + /// + /// Gets the summary of this module. + /// public string Summary { get; } + /// + /// Gets the remarks of this module. + /// public string Remarks { get; } + /// + /// Gets the group name (main prefix) of this module. + /// public string Group { get; } + /// + /// Gets a read-only list of aliases associated with this module. + /// public IReadOnlyList Aliases { get; } + /// + /// Gets a read-only list of commands associated with this module. + /// public IReadOnlyList Commands { get; } + /// + /// Gets a read-only list of preconditions that apply to this module. + /// public IReadOnlyList Preconditions { get; } + /// + /// Gets a read-only list of attributes that apply to this module. + /// public IReadOnlyList Attributes { get; } + /// + /// Gets a read-only list of submodules associated with tihs module. + /// public IReadOnlyList Submodules { get; } + /// + /// Gets the parent module of this submodule if applicable. + /// public ModuleInfo Parent { get; } + /// + /// Gets a value that indicates whether this module is a submodule or not. + /// public bool IsSubmodule => Parent != null; internal ModuleInfo(ModuleBuilder builder, CommandService service, IServiceProvider services, ModuleInfo parent = null) diff --git a/src/Discord.Net.Commands/Info/ParameterInfo.cs b/src/Discord.Net.Commands/Info/ParameterInfo.cs index 142d6b0c2..b435b301a 100644 --- a/src/Discord.Net.Commands/Info/ParameterInfo.cs +++ b/src/Discord.Net.Commands/Info/ParameterInfo.cs @@ -15,16 +15,43 @@ namespace Discord.Commands { private readonly TypeReader _reader; + /// + /// Gets the command that associates with this parameter. + /// public CommandInfo Command { get; } + /// + /// Gets the name of this parameter. + /// public string Name { get; } + /// + /// Gets the summary of this parameter. + /// public string Summary { get; } + /// + /// Gets a value that indicates whether this parameter is optional or not. + /// public bool IsOptional { get; } + /// + /// Gets a value that indicates whether this parameter is a remainder parameter or not. + /// public bool IsRemainder { get; } public bool IsMultiple { get; } + /// + /// Gets the type of the parameter. + /// public Type Type { get; } + /// + /// Gets the default value for this optional parameter if applicable. + /// public object DefaultValue { get; } + /// + /// Gets a read-only list of precondition that apply to this parameter. + /// public IReadOnlyList Preconditions { get; } + /// + /// Gets a read-only list of attributes that apply to this parameter. + /// public IReadOnlyList Attributes { get; } internal ParameterInfo(ParameterBuilder builder, CommandInfo command, CommandService service) diff --git a/src/Discord.Net.Commands/Results/ExecuteResult.cs b/src/Discord.Net.Commands/Results/ExecuteResult.cs index 5ee374059..a1a68866f 100644 --- a/src/Discord.Net.Commands/Results/ExecuteResult.cs +++ b/src/Discord.Net.Commands/Results/ExecuteResult.cs @@ -6,6 +6,9 @@ namespace Discord.Commands [DebuggerDisplay(@"{DebuggerDisplay,nq}")] public struct ExecuteResult : IResult { + /// + /// Gets the exception that may have occurred during the command execution. + /// public Exception Exception { get; } /// diff --git a/src/Discord.Net.Core/Extensions/MessageExtensions.cs b/src/Discord.Net.Core/Extensions/MessageExtensions.cs index a809ee4fa..90185cb6d 100644 --- a/src/Discord.Net.Core/Extensions/MessageExtensions.cs +++ b/src/Discord.Net.Core/Extensions/MessageExtensions.cs @@ -1,7 +1,7 @@ namespace Discord { /// - /// Provides extension methods for . + /// Provides extension methods for . /// public static class MessageExtensions { diff --git a/src/Discord.Net.WebSocket/DiscordSocketClient.cs b/src/Discord.Net.WebSocket/DiscordSocketClient.cs index 57d06eace..925ebf381 100644 --- a/src/Discord.Net.WebSocket/DiscordSocketClient.cs +++ b/src/Discord.Net.WebSocket/DiscordSocketClient.cs @@ -361,6 +361,12 @@ namespace Discord.WebSocket } /// + /// + /// The following example sets the status of the current user to Do Not Disturb. + /// + /// await client.SetStatusAsync(UserStatus.DoNotDisturb); + /// + /// public override async Task SetStatusAsync(UserStatus status) { Status = status; @@ -371,6 +377,20 @@ namespace Discord.WebSocket await SendStatusAsync().ConfigureAwait(false); } /// + /// + /// + /// The following example sets the activity of the current user to the specified game name. + /// + /// await client.SetGameAsync("A Strange Game"); + /// + /// + /// + /// The following example sets the activity of the current user to a streaming status. + /// + /// await client.SetGameAsync("Great Stream 10/10", "https://twitch.tv/MyAmazingStream1337", ActivityType.Streaming); + /// + /// + /// public override async Task SetGameAsync(string name, string streamUrl = null, ActivityType type = ActivityType.Playing) { if (!string.IsNullOrEmpty(streamUrl)) diff --git a/src/Discord.Net.WebSocket/Entities/Users/SocketSelfUser.cs b/src/Discord.Net.WebSocket/Entities/Users/SocketSelfUser.cs index efbddd57b..ae705109c 100644 --- a/src/Discord.Net.WebSocket/Entities/Users/SocketSelfUser.cs +++ b/src/Discord.Net.WebSocket/Entities/Users/SocketSelfUser.cs @@ -7,7 +7,7 @@ using Model = Discord.API.User; namespace Discord.WebSocket { /// - /// Represents the logged-in WebSocker-based user. + /// Represents the logged-in WebSocket-based user. /// [DebuggerDisplay(@"{DebuggerDisplay,nq}")] public class SocketSelfUser : SocketUser, ISelfUser