From 56987e212bb695f92b83137b7cfd5bbb7ad87b8c Mon Sep 17 00:00:00 2001 From: Still Hsu <341464@gmail.com> Date: Sun, 22 Apr 2018 03:17:52 +0800 Subject: [PATCH] Add XML docs --- docs/_overwrites/Common/IEmote.Inclusion.md | 2 +- docs/_overwrites/Common/IEmote.Overwrites.md | 10 +++-- .../Attributes/CommandAttribute.cs | 6 +++ .../Attributes/GroupAttribute.cs | 15 +++++-- .../Attributes/NameAttribute.cs | 6 ++- .../Attributes/OverrideTypeReaderAttribute.cs | 14 ++++--- .../ParameterPreconditionAttribute.cs | 7 ++++ .../Attributes/PreconditionAttribute.cs | 8 ++-- .../RequireBotPermissionAttribute.cs | 36 ++++++++++------- .../Preconditions/RequireContextAttribute.cs | 24 +++++++---- .../Preconditions/RequireNsfwAttribute.cs | 3 +- .../Preconditions/RequireOwnerAttribute.cs | 1 + .../RequireUserPermissionAttribute.cs | 37 +++++++++-------- .../Attributes/PriorityAttribute.cs | 2 +- .../Builders/CommandBuilder.cs | 5 +-- .../Builders/ModuleBuilder.cs | 1 - src/Discord.Net.Commands/CommandMatch.cs | 1 - src/Discord.Net.Commands/CommandService.cs | 1 - .../Results/ParseResult.cs | 2 +- .../Results/PreconditionResult.cs | 24 +++++++++++ .../Results/RuntimeResult.cs | 5 +++ src/Discord.Net.Core/CDN.cs | 2 +- src/Discord.Net.Core/Logging/LogSeverity.cs | 30 +++++++------- src/Discord.Net.Core/Utils/Cacheable.cs | 39 +++++++++++++----- src/Discord.Net.Core/Utils/Comparers.cs | 2 +- src/Discord.Net.Core/Utils/MentionUtils.cs | 40 ++++++++++++++----- 26 files changed, 219 insertions(+), 104 deletions(-) diff --git a/docs/_overwrites/Common/IEmote.Inclusion.md b/docs/_overwrites/Common/IEmote.Inclusion.md index 9e4824c33..cf93c7eb5 100644 --- a/docs/_overwrites/Common/IEmote.Inclusion.md +++ b/docs/_overwrites/Common/IEmote.Inclusion.md @@ -7,7 +7,7 @@ public async Task SendAndReactAsync(ISocketMessageChannel channel) var message = await channel.SendMessageAsync("I am a message."); // Creates a Unicode-based emoji based on the Unicode string. - // This is effctively the same as new Emoji("πŸ’•"). + // This is effectively the same as new Emoji("πŸ’•"). var heartEmoji = new Emoji("\U0001f495"); // Reacts to the message with the Emoji. await message.AddReactionAsync(heartEmoji); diff --git a/docs/_overwrites/Common/IEmote.Overwrites.md b/docs/_overwrites/Common/IEmote.Overwrites.md index b05ae2b32..034533d1d 100644 --- a/docs/_overwrites/Common/IEmote.Overwrites.md +++ b/docs/_overwrites/Common/IEmote.Overwrites.md @@ -24,7 +24,7 @@ remarks: *content > [!NOTE] > A valid @Discord.Emote format is `<:emoteName:emoteId>`. This can be > obtained by escaping with a `\` in front of the emote using the -> Discord chat client. +> Discord chat client. This class represents a custom emoji. This type of emoji can be created via the @Discord.Emote.Parse* or @Discord.Emote.TryParse* @@ -42,11 +42,15 @@ remarks: *content > [!NOTE] > A valid @Discord.Emoji format is Unicode-based. This means only -> something like `πŸ™ƒ` or `\U0001f643` would work, instead of +> something like `πŸ™ƒ` or `\U0001f643` would work, instead of > `:upside_down:`. +> +> A Unicode-based emoji can be obtained by escaping with a `\` in +> front of the emote using the Discord chat client or by looking up on +> [Emojipedia](https://emojipedia.org). This class represents a standard Unicode-based emoji. This type of emoji -can be created by passing the unicode into its constructor. +can be created by passing the Unicode into the constructor. --- uid: Discord.IEmote diff --git a/src/Discord.Net.Commands/Attributes/CommandAttribute.cs b/src/Discord.Net.Commands/Attributes/CommandAttribute.cs index 91a862f41..cce82101b 100644 --- a/src/Discord.Net.Commands/Attributes/CommandAttribute.cs +++ b/src/Discord.Net.Commands/Attributes/CommandAttribute.cs @@ -15,10 +15,16 @@ namespace Discord.Commands /// public RunMode RunMode { get; set; } = RunMode.Default; + /// public CommandAttribute() { Text = null; } + + /// + /// Initializes a new attribute with the specified name. + /// + /// The name of the command. public CommandAttribute(string text) { Text = text; diff --git a/src/Discord.Net.Commands/Attributes/GroupAttribute.cs b/src/Discord.Net.Commands/Attributes/GroupAttribute.cs index 41bf3e261..e1e38cff7 100644 --- a/src/Discord.Net.Commands/Attributes/GroupAttribute.cs +++ b/src/Discord.Net.Commands/Attributes/GroupAttribute.cs @@ -2,19 +2,26 @@ using System; namespace Discord.Commands { - /// Marks the module as a command group. + /// + /// Marks the module as a command group. + /// [AttributeUsage(AttributeTargets.Class, AllowMultiple = false, Inherited = true)] public class GroupAttribute : Attribute { - /// Gets the prefix set for the module. + /// + /// Gets the prefix set for the module. + /// public string Prefix { get; } + /// public GroupAttribute() { Prefix = null; } - /// Creates a with the provided prefix. - /// The prefix of the module group. + /// + /// Initializes a new with the provided prefix. + /// + /// The prefix of the module group. public GroupAttribute(string prefix) { Prefix = prefix; diff --git a/src/Discord.Net.Commands/Attributes/NameAttribute.cs b/src/Discord.Net.Commands/Attributes/NameAttribute.cs index b3330f1dd..a6e1f2e5a 100644 --- a/src/Discord.Net.Commands/Attributes/NameAttribute.cs +++ b/src/Discord.Net.Commands/Attributes/NameAttribute.cs @@ -14,8 +14,10 @@ namespace Discord.Commands /// public string Text { get; } - /// Marks the public name of a command, module, or parameter with the provided name. - /// The public name of the object. + /// + /// Marks the public name of a command, module, or parameter with the provided name. + /// + /// The public name of the object. public NameAttribute(string text) { Text = text; diff --git a/src/Discord.Net.Commands/Attributes/OverrideTypeReaderAttribute.cs b/src/Discord.Net.Commands/Attributes/OverrideTypeReaderAttribute.cs index 67323bfb9..a70a70f31 100644 --- a/src/Discord.Net.Commands/Attributes/OverrideTypeReaderAttribute.cs +++ b/src/Discord.Net.Commands/Attributes/OverrideTypeReaderAttribute.cs @@ -4,20 +4,24 @@ using System.Reflection; namespace Discord.Commands { - /// Marks the to be read by the specified . + /// + /// Marks the to be read by the specified . + /// [AttributeUsage(AttributeTargets.Parameter, AllowMultiple = false, Inherited = true)] public class OverrideTypeReaderAttribute : Attribute { - private static readonly TypeInfo _typeReaderTypeInfo = typeof(TypeReader).GetTypeInfo(); + private static readonly TypeInfo TypeReaderTypeInfo = typeof(TypeReader).GetTypeInfo(); - /// Gets the specified of the parameter. + /// + /// Gets the specified of the parameter. + /// public Type TypeReader { get; } - /// Marks the parameter to be read with the specified . + /// /// The to be used with the parameter. public OverrideTypeReaderAttribute(Type overridenTypeReader) { - if (!_typeReaderTypeInfo.IsAssignableFrom(overridenTypeReader.GetTypeInfo())) + if (!TypeReaderTypeInfo.IsAssignableFrom(overridenTypeReader.GetTypeInfo())) throw new ArgumentException($"{nameof(overridenTypeReader)} must inherit from {nameof(TypeReader)}."); TypeReader = overridenTypeReader; diff --git a/src/Discord.Net.Commands/Attributes/ParameterPreconditionAttribute.cs b/src/Discord.Net.Commands/Attributes/ParameterPreconditionAttribute.cs index 4c1fe30d7..efdb2c5b2 100644 --- a/src/Discord.Net.Commands/Attributes/ParameterPreconditionAttribute.cs +++ b/src/Discord.Net.Commands/Attributes/ParameterPreconditionAttribute.cs @@ -9,6 +9,13 @@ namespace Discord.Commands [AttributeUsage(AttributeTargets.Parameter, AllowMultiple = true, Inherited = true)] public abstract class ParameterPreconditionAttribute : Attribute { + /// + /// Checks whether the condition is met before execution of the command. + /// + /// The context of the command. + /// The parameter of the command being checked against. + /// The raw value of the type. + /// The service collection used for dependency injection. public abstract Task CheckPermissionsAsync(ICommandContext context, ParameterInfo parameter, object value, IServiceProvider services); } } diff --git a/src/Discord.Net.Commands/Attributes/PreconditionAttribute.cs b/src/Discord.Net.Commands/Attributes/PreconditionAttribute.cs index 7959b748b..50a63c582 100644 --- a/src/Discord.Net.Commands/Attributes/PreconditionAttribute.cs +++ b/src/Discord.Net.Commands/Attributes/PreconditionAttribute.cs @@ -11,11 +11,9 @@ namespace Discord.Commands /// Specify a group that this precondition belongs to. /// /// - /// - /// of the same group require only one of the preconditions to pass in - /// order to be successful (A || B). Specifying = or not - /// at all will require *all* preconditions to pass, just like normal (A && B). - /// + /// of the same group require only one of the preconditions to pass in order to + /// be successful (A || B). Specifying = or not at all will + /// require *all* preconditions to pass, just like normal (A && B). /// public string Group { get; set; } = null; diff --git a/src/Discord.Net.Commands/Attributes/Preconditions/RequireBotPermissionAttribute.cs b/src/Discord.Net.Commands/Attributes/Preconditions/RequireBotPermissionAttribute.cs index 408ddd319..adea63edf 100644 --- a/src/Discord.Net.Commands/Attributes/Preconditions/RequireBotPermissionAttribute.cs +++ b/src/Discord.Net.Commands/Attributes/Preconditions/RequireBotPermissionAttribute.cs @@ -4,43 +4,49 @@ using System.Threading.Tasks; namespace Discord.Commands { /// - /// Requires the bot to have a specific permission in the channel a command is invoked in. + /// Requires the bot to have a specific permission in the channel a command is invoked in. /// [AttributeUsage(AttributeTargets.Class | AttributeTargets.Method, AllowMultiple = true, Inherited = true)] public class RequireBotPermissionAttribute : PreconditionAttribute { + /// + /// Gets the specified of the precondition. + /// public GuildPermission? GuildPermission { get; } + /// + /// Gets the specified of the precondition. + /// public ChannelPermission? ChannelPermission { get; } /// - /// Requires the bot account to have a specific . + /// Requires the bot account to have a specific . /// - /// This precondition will always fail if the command is being invoked in a private channel. - /// The GuildPermission that the bot must have. Multiple permissions can be specified by ORing the permissions together. + /// + /// This precondition will always fail if the command is being invoked in a . + /// + /// + /// The that the bot must have. Multiple permissions can be specified + /// by ORing the permissions together. + /// public RequireBotPermissionAttribute(GuildPermission permission) { GuildPermission = permission; ChannelPermission = null; } /// - /// Requires that the bot account to have a specific . + /// Requires that the bot account to have a specific . /// - /// The ChannelPermission that the bot must have. Multiple permissions can be specified by ORing the permissions together. - /// - /// - /// [Command("permission")] - /// [RequireBotPermission(ChannelPermission.ManageMessages)] - /// public async Task Purge() - /// { - /// } - /// - /// + /// + /// The that the bot must have. Multiple permissions can be + /// specified by ORing the permissions together. + /// public RequireBotPermissionAttribute(ChannelPermission permission) { ChannelPermission = permission; GuildPermission = null; } + /// public override async Task CheckPermissionsAsync(ICommandContext context, CommandInfo command, IServiceProvider services) { IGuildUser guildUser = null; diff --git a/src/Discord.Net.Commands/Attributes/Preconditions/RequireContextAttribute.cs b/src/Discord.Net.Commands/Attributes/Preconditions/RequireContextAttribute.cs index 041da5217..8797f7daf 100644 --- a/src/Discord.Net.Commands/Attributes/Preconditions/RequireContextAttribute.cs +++ b/src/Discord.Net.Commands/Attributes/Preconditions/RequireContextAttribute.cs @@ -3,28 +3,38 @@ using System.Threading.Tasks; namespace Discord.Commands { - /// Defines the type of command context. + /// + /// Defines the type of command context (i.e. where the command is being executed). + /// [Flags] public enum ContextType { - /// Specifies the command to be executed within a guild. + /// + /// Specifies the command to be executed within a guild. + /// Guild = 0x01, - /// Specifies the command to be executed within a DM. + /// + /// Specifies the command to be executed within a DM. + /// DM = 0x02, - /// Specifies the command to be executed within a group. + /// + /// Specifies the command to be executed within a group. + /// Group = 0x04 } /// - /// Requires the command to be invoked in a specified context (e.g. in guild, DM). + /// Requires the command to be invoked in a specified context (e.g. in guild, DM). /// [AttributeUsage(AttributeTargets.Class | AttributeTargets.Method, AllowMultiple = true, Inherited = true)] public class RequireContextAttribute : PreconditionAttribute { - /// Gets the context required to execute the command. + /// + /// Gets the context required to execute the command. + /// public ContextType Contexts { get; } - /// Requires that the command be invoked in the specified context. + /// Requires the command to be invoked in the specified context. /// The type of context the command can be invoked in. Multiple contexts can be specified by ORing the contexts together. /// /// diff --git a/src/Discord.Net.Commands/Attributes/Preconditions/RequireNsfwAttribute.cs b/src/Discord.Net.Commands/Attributes/Preconditions/RequireNsfwAttribute.cs index ec3931dbe..d97db8290 100644 --- a/src/Discord.Net.Commands/Attributes/Preconditions/RequireNsfwAttribute.cs +++ b/src/Discord.Net.Commands/Attributes/Preconditions/RequireNsfwAttribute.cs @@ -4,11 +4,12 @@ using System.Threading.Tasks; namespace Discord.Commands { /// - /// Requires the command to be invoked in a channel marked NSFW. + /// Requires the command to be invoked in a channel marked NSFW. /// [AttributeUsage(AttributeTargets.Class | AttributeTargets.Method, AllowMultiple = true, Inherited = true)] public class RequireNsfwAttribute : PreconditionAttribute { + /// public override Task CheckPermissionsAsync(ICommandContext context, CommandInfo command, IServiceProvider services) { if (context.Channel is ITextChannel text && text.IsNsfw) diff --git a/src/Discord.Net.Commands/Attributes/Preconditions/RequireOwnerAttribute.cs b/src/Discord.Net.Commands/Attributes/Preconditions/RequireOwnerAttribute.cs index 21277d8b1..3ea35a9fd 100644 --- a/src/Discord.Net.Commands/Attributes/Preconditions/RequireOwnerAttribute.cs +++ b/src/Discord.Net.Commands/Attributes/Preconditions/RequireOwnerAttribute.cs @@ -10,6 +10,7 @@ namespace Discord.Commands [AttributeUsage(AttributeTargets.Class | AttributeTargets.Method, AllowMultiple = true, Inherited = true)] public class RequireOwnerAttribute : PreconditionAttribute { + /// public override async Task CheckPermissionsAsync(ICommandContext context, CommandInfo command, IServiceProvider services) { switch (context.Client.TokenType) diff --git a/src/Discord.Net.Commands/Attributes/Preconditions/RequireUserPermissionAttribute.cs b/src/Discord.Net.Commands/Attributes/Preconditions/RequireUserPermissionAttribute.cs index 6343ca190..072f10e0f 100644 --- a/src/Discord.Net.Commands/Attributes/Preconditions/RequireUserPermissionAttribute.cs +++ b/src/Discord.Net.Commands/Attributes/Preconditions/RequireUserPermissionAttribute.cs @@ -9,39 +9,44 @@ namespace Discord.Commands [AttributeUsage(AttributeTargets.Class | AttributeTargets.Method, AllowMultiple = true, Inherited = true)] public class RequireUserPermissionAttribute : PreconditionAttribute { + /// + /// Gets the specified of the precondition. + /// public GuildPermission? GuildPermission { get; } + /// + /// Gets the specified of the precondition. + /// public ChannelPermission? ChannelPermission { get; } /// - /// Requires that the user invoking the command to have a specific . + /// Requires that the user invoking the command to have a specific . /// - /// This precondition will always fail if the command is being invoked in a private channel. - /// The GuildPermission that the user must have. Multiple permissions can be specified by ORing the permissions together. + /// + /// This precondition will always fail if the command is being invoked in a . + /// + /// + /// The that the user must have. Multiple permissions can be + /// specified by ORing the permissions together. + /// public RequireUserPermissionAttribute(GuildPermission permission) { GuildPermission = permission; ChannelPermission = null; } /// - /// Requires that the user invoking the command to have a specific . + /// Requires that the user invoking the command to have a specific . /// - /// The ChannelPermission that the user must have. Multiple permissions can be specified by ORing the permissions together. - /// - /// - /// [Command("permission")] - /// [RequireUserPermission(ChannelPermission.ReadMessageHistory | ChannelPermission.ReadMessages)] - /// public async Task HasPermission() - /// { - /// await ReplyAsync("You can read messages and the message history!"); - /// } - /// - /// + /// + /// The that the user must have. Multiple permissions can be + /// specified by ORing the permissions together. + /// public RequireUserPermissionAttribute(ChannelPermission permission) { ChannelPermission = permission; GuildPermission = null; } - + + /// public override Task CheckPermissionsAsync(ICommandContext context, CommandInfo command, IServiceProvider services) { var guildUser = context.User as IGuildUser; diff --git a/src/Discord.Net.Commands/Attributes/PriorityAttribute.cs b/src/Discord.Net.Commands/Attributes/PriorityAttribute.cs index ba7360ef3..75ffd2585 100644 --- a/src/Discord.Net.Commands/Attributes/PriorityAttribute.cs +++ b/src/Discord.Net.Commands/Attributes/PriorityAttribute.cs @@ -14,7 +14,7 @@ namespace Discord.Commands public int Priority { get; } /// - /// Creates a new with the given priority. + /// Initializes a new attribute with the given priority. /// public PriorityAttribute(int priority) { diff --git a/src/Discord.Net.Commands/Builders/CommandBuilder.cs b/src/Discord.Net.Commands/Builders/CommandBuilder.cs index b6d002c70..70045453f 100644 --- a/src/Discord.Net.Commands/Builders/CommandBuilder.cs +++ b/src/Discord.Net.Commands/Builders/CommandBuilder.cs @@ -1,8 +1,7 @@ -ο»Ώusing System; +using System; using System.Linq; using System.Threading.Tasks; using System.Collections.Generic; -using Microsoft.Extensions.DependencyInjection; namespace Discord.Commands.Builders { @@ -140,4 +139,4 @@ namespace Discord.Commands.Builders return new CommandInfo(this, info, service); } } -} \ No newline at end of file +} diff --git a/src/Discord.Net.Commands/Builders/ModuleBuilder.cs b/src/Discord.Net.Commands/Builders/ModuleBuilder.cs index 1809c2c63..0ada5a9c2 100644 --- a/src/Discord.Net.Commands/Builders/ModuleBuilder.cs +++ b/src/Discord.Net.Commands/Builders/ModuleBuilder.cs @@ -2,7 +2,6 @@ using System; using System.Collections.Generic; using System.Reflection; using System.Threading.Tasks; -using Microsoft.Extensions.DependencyInjection; namespace Discord.Commands.Builders { diff --git a/src/Discord.Net.Commands/CommandMatch.cs b/src/Discord.Net.Commands/CommandMatch.cs index 6411ef084..c15a33228 100644 --- a/src/Discord.Net.Commands/CommandMatch.cs +++ b/src/Discord.Net.Commands/CommandMatch.cs @@ -1,7 +1,6 @@ using System; using System.Collections.Generic; using System.Threading.Tasks; -using Microsoft.Extensions.DependencyInjection; namespace Discord.Commands { diff --git a/src/Discord.Net.Commands/CommandService.cs b/src/Discord.Net.Commands/CommandService.cs index 7ed106132..b4511a90c 100644 --- a/src/Discord.Net.Commands/CommandService.cs +++ b/src/Discord.Net.Commands/CommandService.cs @@ -6,7 +6,6 @@ using System.Linq; using System.Reflection; using System.Threading; using System.Threading.Tasks; -using Microsoft.Extensions.DependencyInjection; using Discord.Commands.Builders; using Discord.Logging; diff --git a/src/Discord.Net.Commands/Results/ParseResult.cs b/src/Discord.Net.Commands/Results/ParseResult.cs index f128ab7a9..96ec667fe 100644 --- a/src/Discord.Net.Commands/Results/ParseResult.cs +++ b/src/Discord.Net.Commands/Results/ParseResult.cs @@ -24,7 +24,7 @@ namespace Discord.Commands Error = error; ErrorReason = errorReason; } - + public static ParseResult FromSuccess(IReadOnlyList argValues, IReadOnlyList paramValues) { for (int i = 0; i < argValues.Count; i++) diff --git a/src/Discord.Net.Commands/Results/PreconditionResult.cs b/src/Discord.Net.Commands/Results/PreconditionResult.cs index beb156b33..dd6adf31f 100644 --- a/src/Discord.Net.Commands/Results/PreconditionResult.cs +++ b/src/Discord.Net.Commands/Results/PreconditionResult.cs @@ -2,6 +2,9 @@ using System.Diagnostics; namespace Discord.Commands { + /// + /// Represents a result type for command preconditions. + /// [DebuggerDisplay(@"{DebuggerDisplay,nq}")] public class PreconditionResult : IResult { @@ -13,19 +16,40 @@ namespace Discord.Commands /// public bool IsSuccess => !Error.HasValue; + /// + /// Initializes a new class with the command type + /// and reason. + /// + /// The type of failure. + /// The reason of failure. protected PreconditionResult(CommandError? error, string errorReason) { Error = error; ErrorReason = errorReason; } + /// + /// Returns a with no errors. + /// public static PreconditionResult FromSuccess() => new PreconditionResult(null, null); + /// + /// Returns a with and the + /// specified reason. + /// + /// The reason of failure. public static PreconditionResult FromError(string reason) => new PreconditionResult(CommandError.UnmetPrecondition, reason); + /// + /// Returns a with the specified type. + /// + /// The result of failure. public static PreconditionResult FromError(IResult result) => new PreconditionResult(result.Error, result.ErrorReason); + /// + /// Returns a string indicating whether the is successful. + /// public override string ToString() => IsSuccess ? "Success" : $"{Error}: {ErrorReason}"; private string DebuggerDisplay => IsSuccess ? "Success" : $"{Error}: {ErrorReason}"; } diff --git a/src/Discord.Net.Commands/Results/RuntimeResult.cs b/src/Discord.Net.Commands/Results/RuntimeResult.cs index fc54e7937..a7febd68e 100644 --- a/src/Discord.Net.Commands/Results/RuntimeResult.cs +++ b/src/Discord.Net.Commands/Results/RuntimeResult.cs @@ -5,6 +5,11 @@ namespace Discord.Commands [DebuggerDisplay(@"{DebuggerDisplay,nq}")] public abstract class RuntimeResult : IResult { + /// + /// Initializes a new class with the type of error and reason. + /// + /// The type of failure, or if none. + /// The reason of failure. protected RuntimeResult(CommandError? error, string reason) { Error = error; diff --git a/src/Discord.Net.Core/CDN.cs b/src/Discord.Net.Core/CDN.cs index 44e1779f3..0c713f135 100644 --- a/src/Discord.Net.Core/CDN.cs +++ b/src/Discord.Net.Core/CDN.cs @@ -3,7 +3,7 @@ using System; namespace Discord { /// - /// A class containing the strings related to various Content Delivery Networks (CDNs). + /// Represents a class containing the strings related to various Content Delivery Networks (CDNs). /// public static class CDN { diff --git a/src/Discord.Net.Core/Logging/LogSeverity.cs b/src/Discord.Net.Core/Logging/LogSeverity.cs index 98677dbde..f9b518c17 100644 --- a/src/Discord.Net.Core/Logging/LogSeverity.cs +++ b/src/Discord.Net.Core/Logging/LogSeverity.cs @@ -1,31 +1,33 @@ namespace Discord { - /// Specifies the severity of the log message. + /// + /// Specifies the severity of the log message. + /// public enum LogSeverity { - /// - /// Logs that contain the most severe level of error. - /// This type of error indicate that immediate attention may be required. + /// + /// Logs that contain the most severe level of error. This type of error indicate that immediate attention + /// may be required. /// Critical = 0, - /// - /// Logs that highlight when the flow of execution is stopped due to a failure. + /// + /// Logs that highlight when the flow of execution is stopped due to a failure. /// Error = 1, - /// - /// Logs that highlight an abnormal activity in the flow of execution. + /// + /// Logs that highlight an abnormal activity in the flow of execution. /// Warning = 2, - /// - /// Logs that track the general flow of the application. + /// + /// Logs that track the general flow of the application. /// Info = 3, - /// - /// Logs that are used for interactive investigation during development. + /// + /// Logs that are used for interactive investigation during development. /// Verbose = 4, - /// - /// Logs that contain the most detailed messages. + /// + /// Logs that contain the most detailed messages. /// Debug = 5 } diff --git a/src/Discord.Net.Core/Utils/Cacheable.cs b/src/Discord.Net.Core/Utils/Cacheable.cs index f09e4d4cf..2eb5a8542 100644 --- a/src/Discord.Net.Core/Utils/Cacheable.cs +++ b/src/Discord.Net.Core/Utils/Cacheable.cs @@ -3,20 +3,29 @@ using System.Threading.Tasks; namespace Discord { - /// Contains an entity that may be cached. - /// The type of entity that is cached. - /// The type of this entity's ID. + /// + /// Represents a that contains an entity that may be cached. + /// + /// The type of entity that is cached. + /// The type of this entity's ID. public struct Cacheable where TEntity : IEntity where TId : IEquatable { - /// Indicates whether this entity is cached. + /// + /// Gets whether this entity is cached. + /// public bool HasValue { get; } - /// Gets the ID of this entity. + /// + /// Gets the ID of this entity. + /// public TId Id { get; } - /// Gets the entity if it could be pulled from cache. + /// + /// Gets the entity if it could be pulled from cache. + /// /// - /// This value is not guaranteed to be set; in cases where the entity cannot be pulled from cache, it is null. + /// This value is not guaranteed to be set; in cases where the entity cannot be pulled from cache, it is + /// null. /// public TEntity Value { get; } private Func> DownloadFunc { get; } @@ -29,19 +38,27 @@ namespace Discord DownloadFunc = downloadFunc; } - /// Downloads this entity to cache. - /// An awaitable Task containing the downloaded entity. + /// + /// Downloads this entity to cache. + /// /// Thrown when used from a user account. /// Thrown when the message is deleted. + /// + /// An awaitable containing the downloaded entity. + /// public async Task DownloadAsync() { return await DownloadFunc().ConfigureAwait(false); } - /// Returns the cached entity if it exists; otherwise downloads it. - /// An awaitable Task containing a cached or downloaded entity. + /// + /// Returns the cached entity if it exists; otherwise downloads it. + /// /// Thrown when used from a user account. /// Thrown when the message is deleted and is not in cache. + /// + /// An awaitable containing a cached or downloaded entity. + /// public async Task GetOrDownloadAsync() => HasValue ? Value : await DownloadAsync().ConfigureAwait(false); } } diff --git a/src/Discord.Net.Core/Utils/Comparers.cs b/src/Discord.Net.Core/Utils/Comparers.cs index d7092d9cc..40500ffe3 100644 --- a/src/Discord.Net.Core/Utils/Comparers.cs +++ b/src/Discord.Net.Core/Utils/Comparers.cs @@ -4,7 +4,7 @@ using System.Collections.Generic; namespace Discord { /// - /// Represents a collection of for various Discord objects. + /// Represents a collection of for various Discord objects. /// public static class DiscordComparers { diff --git a/src/Discord.Net.Core/Utils/MentionUtils.cs b/src/Discord.Net.Core/Utils/MentionUtils.cs index c510c7b3f..36779de6e 100644 --- a/src/Discord.Net.Core/Utils/MentionUtils.cs +++ b/src/Discord.Net.Core/Utils/MentionUtils.cs @@ -4,30 +4,42 @@ using System.Text; namespace Discord { - /// A helper class for mention-related parsing. + /// + /// Represents a helper class for mention-related parsing. + /// public static class MentionUtils { private const char SanitizeChar = '\x200b'; //If the system can't be positive a user doesn't have a nickname, assume useNickname = true (source: Jake) internal static string MentionUser(string id, bool useNickname = true) => useNickname ? $"<@!{id}>" : $"<@{id}>"; - /// Returns a mention string based on the user ID. + /// + /// Returns a mention string based on the user ID. + /// public static string MentionUser(ulong id) => MentionUser(id.ToString(), true); internal static string MentionChannel(string id) => $"<#{id}>"; - /// Returns a mention string based on the channel ID. + /// + /// Returns a mention string based on the channel ID. + /// public static string MentionChannel(ulong id) => MentionChannel(id.ToString()); internal static string MentionRole(string id) => $"<@&{id}>"; - /// Returns a mention string based on the role ID. + /// + /// Returns a mention string based on the role ID. + /// public static string MentionRole(ulong id) => MentionRole(id.ToString()); - /// Parses a provided user mention string. + /// + /// Parses a provided user mention string. + /// public static ulong ParseUser(string text) { if (TryParseUser(text, out ulong id)) return id; throw new ArgumentException("Invalid mention format", nameof(text)); } - /// Tries to parse a provided user mention string. + /// + /// Tries to parse a provided user mention string. + /// public static bool TryParseUser(string text, out ulong userId) { if (text.Length >= 3 && text[0] == '<' && text[1] == '@' && text[text.Length - 1] == '>') @@ -44,14 +56,18 @@ namespace Discord return false; } - /// Parses a provided channel mention string. + /// + /// Parses a provided channel mention string. + /// public static ulong ParseChannel(string text) { if (TryParseChannel(text, out ulong id)) return id; throw new ArgumentException("Invalid mention format", nameof(text)); } - /// Tries to parse a provided channel mention string. + /// + /// Tries to parse a provided channel mention string. + /// public static bool TryParseChannel(string text, out ulong channelId) { if (text.Length >= 3 && text[0] == '<' && text[1] == '#' && text[text.Length - 1] == '>') @@ -65,14 +81,18 @@ namespace Discord return false; } - /// Parses a provided role mention string. + /// + /// Parses a provided role mention string. + /// public static ulong ParseRole(string text) { if (TryParseRole(text, out ulong id)) return id; throw new ArgumentException("Invalid mention format", nameof(text)); } - /// Tries to parse a provided role mention string. + /// + /// Tries to parse a provided role mention string. + /// public static bool TryParseRole(string text, out ulong roleId) { if (text.Length >= 4 && text[0] == '<' && text[1] == '@' && text[2] == '&' && text[text.Length - 1] == '>')