diff --git a/src/Discord.Net.Commands/Attributes/Preconditions/RequireContextAttribute.cs b/src/Discord.Net.Commands/Attributes/Preconditions/RequireContextAttribute.cs index 8797f7daf..641b436ea 100644 --- a/src/Discord.Net.Commands/Attributes/Preconditions/RequireContextAttribute.cs +++ b/src/Discord.Net.Commands/Attributes/Preconditions/RequireContextAttribute.cs @@ -37,11 +37,12 @@ namespace Discord.Commands /// 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. /// - /// - /// [Command("private_only")] + /// + /// [Command("secret")] /// [RequireContext(ContextType.DM | ContextType.Group)] - /// public async Task PrivateOnly() + /// public Task PrivateOnlyAsync() /// { + /// return ReplyAsync("shhh, this command is a secret"); /// } /// /// @@ -50,12 +51,13 @@ namespace Discord.Commands Contexts = contexts; } + /// public override Task CheckPermissionsAsync(ICommandContext context, CommandInfo command, IServiceProvider services) { bool isValid = false; if ((Contexts & ContextType.Guild) != 0) - isValid = isValid || context.Channel is IGuildChannel; + isValid = context.Channel is IGuildChannel; if ((Contexts & ContextType.DM) != 0) isValid = isValid || context.Channel is IDMChannel; if ((Contexts & ContextType.Group) != 0) diff --git a/src/Discord.Net.Commands/CommandServiceConfig.cs b/src/Discord.Net.Commands/CommandServiceConfig.cs index 741c3bc59..6464a4811 100644 --- a/src/Discord.Net.Commands/CommandServiceConfig.cs +++ b/src/Discord.Net.Commands/CommandServiceConfig.cs @@ -44,7 +44,7 @@ namespace Discord.Commands /// If this map is set to null or empty, the default delimiter of " will be used. /// /// - /// + /// /// QuotationMarkAliasMap = new Dictionary<char, char%gt;() /// { /// {'\"', '\"' }, diff --git a/src/Discord.Net.Commands/Results/ExecuteResult.cs b/src/Discord.Net.Commands/Results/ExecuteResult.cs index 7eb252be5..5ee374059 100644 --- a/src/Discord.Net.Commands/Results/ExecuteResult.cs +++ b/src/Discord.Net.Commands/Results/ExecuteResult.cs @@ -8,9 +8,12 @@ namespace Discord.Commands { public Exception Exception { get; } + /// public CommandError? Error { get; } + /// public string ErrorReason { get; } + /// public bool IsSuccess => !Error.HasValue; private ExecuteResult(Exception exception, CommandError? error, string errorReason) diff --git a/src/Discord.Net.Core/Audio/AudioStream.cs b/src/Discord.Net.Core/Audio/AudioStream.cs index d5b36aef2..2287d47fa 100644 --- a/src/Discord.Net.Core/Audio/AudioStream.cs +++ b/src/Discord.Net.Core/Audio/AudioStream.cs @@ -11,6 +11,7 @@ namespace Discord.Audio public override bool CanSeek => false; public override bool CanWrite => false; + /// This stream does not accept headers. public virtual void WriteHeader(ushort seq, uint timestamp, bool missed) => throw new InvalidOperationException("This stream does not accept headers."); public override void Write(byte[] buffer, int offset, int count) diff --git a/src/Discord.Net.Core/Entities/Permissions/Overwrite.cs b/src/Discord.Net.Core/Entities/Permissions/Overwrite.cs index 790e7ea72..f8f3fff44 100644 --- a/src/Discord.Net.Core/Entities/Permissions/Overwrite.cs +++ b/src/Discord.Net.Core/Entities/Permissions/Overwrite.cs @@ -1,5 +1,8 @@ namespace Discord { + /// + /// Represent a permission object. + /// public struct Overwrite { /// @@ -16,7 +19,7 @@ namespace Discord public OverwritePermissions Permissions { get; } /// - /// Creates a new with provided target information and modified permissions. + /// Initializes a new with provided target information and modified permissions. /// public Overwrite(ulong targetId, PermissionTarget targetType, OverwritePermissions permissions) { diff --git a/src/Discord.Net.Core/Entities/Permissions/OverwritePermissions.cs b/src/Discord.Net.Core/Entities/Permissions/OverwritePermissions.cs index ff38f52e3..0af2fba9a 100644 --- a/src/Discord.Net.Core/Entities/Permissions/OverwritePermissions.cs +++ b/src/Discord.Net.Core/Entities/Permissions/OverwritePermissions.cs @@ -4,6 +4,9 @@ using System.Diagnostics; namespace Discord { + /// + /// Represents a container for a series of overwrite permissions. + /// [DebuggerDisplay(@"{DebuggerDisplay,nq}")] public struct OverwritePermissions { @@ -14,11 +17,13 @@ namespace Discord /// /// Gets a that grants all permissions for the given channel. /// + /// Unknown channel type. public static OverwritePermissions AllowAll(IChannel channel) => new OverwritePermissions(ChannelPermissions.All(channel).RawValue, 0); /// /// Gets a that denies all permissions for the given channel. /// + /// Unknown channel type. public static OverwritePermissions DenyAll(IChannel channel) => new OverwritePermissions(0, ChannelPermissions.All(channel).RawValue); @@ -132,7 +137,7 @@ namespace Discord } /// - /// Creates a new with the provided permissions. + /// Initializes a new struct with the provided permissions. /// public OverwritePermissions( PermValue createInstantInvite = PermValue.Inherit, @@ -160,8 +165,8 @@ namespace Discord moveMembers, useVoiceActivation, manageRoles, manageWebhooks) { } /// - /// Creates a new from this one, changing the provided non-null - /// permissions. + /// Initializes a new from the current one, changing the provided + /// non-null permissions. /// public OverwritePermissions Modify( PermValue? createInstantInvite = null, diff --git a/src/Discord.Net.Core/Entities/Roles/Color.cs b/src/Discord.Net.Core/Entities/Roles/Color.cs index b2f29d110..e1de2d1f7 100644 --- a/src/Discord.Net.Core/Entities/Roles/Color.cs +++ b/src/Discord.Net.Core/Entities/Roles/Color.cs @@ -14,45 +14,64 @@ namespace Discord { /// Gets the default user color value. public static readonly Color Default = new Color(0); - /// Gets the teal color value + /// Gets the teal color value. public static readonly Color Teal = new Color(0x1ABC9C); - /// Gets the dark teal color value + /// Gets the dark teal color value. + /// A color class with the hex value of 1ABC9C. public static readonly Color DarkTeal = new Color(0x11806A); - /// Gets the green color value + /// Gets the green color value. + /// A color class with the hex value of 11806A. public static readonly Color Green = new Color(0x2ECC71); - /// Gets the dark green color value + /// Gets the dark green color value. + /// A color class with the hex value of 2ECC71. public static readonly Color DarkGreen = new Color(0x1F8B4C); - /// Gets the blue color value + /// Gets the blue color value. + /// A color class with the hex value of 1F8B4C. public static readonly Color Blue = new Color(0x3498DB); - /// Gets the dark blue color value + /// Gets the dark blue color value. + /// A color class with the hex value of 3498DB. public static readonly Color DarkBlue = new Color(0x206694); - /// Gets the purple color value + /// Gets the purple color value. + /// A color class with the hex value of 206694. public static readonly Color Purple = new Color(0x9B59B6); - /// Gets the dark purple color value + /// Gets the dark purple color value. + /// A color class with the hex value of 9B59B6. public static readonly Color DarkPurple = new Color(0x71368A); - /// Gets the magenta color value + /// Gets the magenta color value. + /// A color class with the hex value of 71368A. public static readonly Color Magenta = new Color(0xE91E63); - /// Gets the dark magenta color value + /// Gets the dark magenta color value. + /// A color class with the hex value of E91E63. public static readonly Color DarkMagenta = new Color(0xAD1457); - /// Gets the gold color value + /// Gets the gold color value. + /// A color class with the hex value of AD1457. public static readonly Color Gold = new Color(0xF1C40F); - /// Gets the light orange color value + /// Gets the light orange color value. + /// A color class with the hex value of F1C40F. public static readonly Color LightOrange = new Color(0xC27C0E); - /// Gets the orange color value + /// Gets the orange color value. + /// A color class with the hex value of C27C0E. public static readonly Color Orange = new Color(0xE67E22); - /// Gets the dark orange color value + /// Gets the dark orange color value. + /// A color class with the hex value of E67E22. public static readonly Color DarkOrange = new Color(0xA84300); - /// Gets the red color value + /// Gets the red color value. + /// A color class with the hex value of A84300. public static readonly Color Red = new Color(0xE74C3C); - /// Gets the dark red color value + /// Gets the dark red color value. + /// A color class with the hex value of E74C3C. public static readonly Color DarkRed = new Color(0x992D22); - /// Gets the light grey color value + /// Gets the light grey color value. + /// A color class with the hex value of 992D22. public static readonly Color LightGrey = new Color(0x979C9F); - /// Gets the lighter grey color value + /// Gets the lighter grey color value. + /// A color class with the hex value of 979C9F. public static readonly Color LighterGrey = new Color(0x95A5A6); - /// Gets the dark grey color value + /// Gets the dark grey color value. + /// A color class with the hex value of 95A5A6. public static readonly Color DarkGrey = new Color(0x607D8B); - /// Gets the darker grey color value + /// Gets the darker grey color value. + /// A color class with the hex value of 607D8B. public static readonly Color DarkerGrey = new Color(0x546E7A); /// Gets the encoded value for this color. @@ -66,13 +85,13 @@ namespace Discord public byte B => (byte)(RawValue); /// - /// Initializes a with the given raw value. + /// Initializes a struct with the given raw value. /// /// /// The following will create a color that has a hex value of /// #607D8B. /// - /// Color darkGrey = new Color(0x607D8B); + /// Color darkGrey = new Color(0x607D8B); /// /// /// The raw value of the color (e.g. 0x607D8B). @@ -87,7 +106,7 @@ namespace Discord /// The following will create a color that has a value of /// #607D8B. /// - /// Color darkGrey = new Color((byte)0b_01100000, (byte)0b_01111101, (byte)0b_10001011); + /// Color darkGrey = new Color((byte)0b_01100000, (byte)0b_01111101, (byte)0b_10001011); /// /// /// The byte that represents the red color. @@ -108,7 +127,7 @@ namespace Discord /// The following will create a color that has a value of /// #607D8B. /// - /// Color darkGrey = new Color(96, 125, 139); + /// Color darkGrey = new Color(96, 125, 139); /// /// /// The value that represents the red color. Must be within 0~255. @@ -135,7 +154,7 @@ namespace Discord /// The following will create a color that has a value of /// #607c8c. /// - /// Color darkGrey = new Color(0.38f, 0.49f, 0.55f); + /// Color darkGrey = new Color(0.38f, 0.49f, 0.55f); /// /// /// The value that represents the red color. Must be within 0~1. diff --git a/src/Discord.Net.Core/Entities/Roles/IRole.cs b/src/Discord.Net.Core/Entities/Roles/IRole.cs index c0f4e9942..8dde78c11 100644 --- a/src/Discord.Net.Core/Entities/Roles/IRole.cs +++ b/src/Discord.Net.Core/Entities/Roles/IRole.cs @@ -11,54 +11,79 @@ namespace Discord /// /// Gets the guild owning this role. /// + /// + /// A guild representing the parent guild of this role. + /// IGuild Guild { get; } /// /// Gets the color given to users of this role. /// + /// + /// A struct representing the color of this role. + /// Color Color { get; } /// /// Determines whether the role can be separated in the user list. /// /// - /// Returns true if users of this role are separated in the user list; otherwise, returns - /// false. + /// true if users of this role are separated in the user list; otherwise false. /// bool IsHoisted { get; } /// /// Determines whether the role is managed by Discord. /// /// - /// Returns true if this role is automatically managed by Discord; otherwise, returns - /// false. + /// true if this role is automatically managed by Discord; otherwise false. /// bool IsManaged { get; } /// /// Determines whether the role is mentionable. /// /// - /// Returns true if this role may be mentioned in messages; otherwise, returns - /// false. + /// true if this role may be mentioned in messages; otherwise false. /// bool IsMentionable { get; } /// /// Gets the name of this role. /// + /// + /// A string containing the name of this role. + /// string Name { get; } /// /// Gets the permissions granted to members of this role. /// + /// + /// A struct that this role possesses. + /// GuildPermissions Permissions { get; } /// /// Gets this role's position relative to other roles in the same guild. /// + /// + /// An representing the position of the role in the role list of the guild. + /// int Position { get; } /// /// Modifies this role. /// - /// The properties to modify the role with. + /// + /// + /// await role.ModifyAsync(x => + /// { + /// x.Name = "Sonic"; + /// x.Color = new Color(0x1A50BC); + /// x.Mentionable = true; + /// }); + /// + /// + /// A delegate containing the properties to modify the role with. /// The options to be used when sending the request. + /// + /// An awaitable . + /// Task ModifyAsync(Action func, RequestOptions options = null); } } diff --git a/src/Discord.Net.Core/Entities/Roles/ReorderRoleProperties.cs b/src/Discord.Net.Core/Entities/Roles/ReorderRoleProperties.cs index 5d7a53c3e..6c6c1ebc9 100644 --- a/src/Discord.Net.Core/Entities/Roles/ReorderRoleProperties.cs +++ b/src/Discord.Net.Core/Entities/Roles/ReorderRoleProperties.cs @@ -6,12 +6,18 @@ namespace Discord public class ReorderRoleProperties { /// - /// Gets the ID of the role to be edited. + /// Gets the identifier of the role to be edited. /// + /// + /// A representing the snowflake identifier of the role to be modified. + /// public ulong Id { get; } /// /// Gets the new zero-based position of the role. /// + /// + /// A representing the new zero-based position of the role. + /// public int Position { get; } /// diff --git a/src/Discord.Net.Core/Entities/Roles/RoleProperties.cs b/src/Discord.Net.Core/Entities/Roles/RoleProperties.cs index ad057a827..df23cf7b1 100644 --- a/src/Discord.Net.Core/Entities/Roles/RoleProperties.cs +++ b/src/Discord.Net.Core/Entities/Roles/RoleProperties.cs @@ -10,7 +10,7 @@ namespace Discord /// Gets or sets the name of the role. /// /// - /// If this role is the EveryoneRole, this value may not be set. + /// This value may not be set if the role is an @everyone role. /// public Optional Name { get; set; } /// @@ -21,28 +21,28 @@ namespace Discord /// Gets or sets the position of the role. This is 0-based! /// /// - /// If this role is the EveryoneRole, this value may not be set. + /// This value may not be set if the role is an @everyone role. /// public Optional Position { get; set; } /// /// Gets or sets the color of the role. /// /// - /// If this role is the EveryoneRole, this value may not be set. + /// This value may not be set if the role is an @everyone role. /// public Optional Color { get; set; } /// /// Gets or sets whether or not this role should be displayed independently in the user list. /// /// - /// If this role is the EveryoneRole, this value may not be set. + /// This value may not be set if the role is an @everyone role. /// public Optional Hoist { get; set; } /// /// Gets or sets whether or not this role can be mentioned. /// /// - /// If this role is the EveryoneRole, this value may not be set. + /// This value may not be set if the role is an @everyone role. /// public Optional Mentionable { get; set; } } diff --git a/src/Discord.Net.Core/Extensions/EmbedBuilderExtensions.cs b/src/Discord.Net.Core/Extensions/EmbedBuilderExtensions.cs index efa168be3..2d72dc985 100644 --- a/src/Discord.Net.Core/Extensions/EmbedBuilderExtensions.cs +++ b/src/Discord.Net.Core/Extensions/EmbedBuilderExtensions.cs @@ -14,10 +14,12 @@ namespace Discord builder.WithColor(new Color(r, g, b)); /// Adds embed color based on the provided RGB value. + /// The argument value is not between 0 to 255. public static EmbedBuilder WithColor(this EmbedBuilder builder, int r, int g, int b) => builder.WithColor(new Color(r, g, b)); /// Adds embed color based on the provided RGB value. + /// The argument value is not between 0 to 1. public static EmbedBuilder WithColor(this EmbedBuilder builder, float r, float g, float b) => builder.WithColor(new Color(r, g, b)); diff --git a/src/Discord.Net.Core/Extensions/UserExtensions.cs b/src/Discord.Net.Core/Extensions/UserExtensions.cs index 7759c8ea3..ff3c24bbf 100644 --- a/src/Discord.Net.Core/Extensions/UserExtensions.cs +++ b/src/Discord.Net.Core/Extensions/UserExtensions.cs @@ -10,6 +10,7 @@ namespace Discord /// /// Sends a message via DM. /// + /// The user to send the DM to. /// The message to be sent. /// Whether the message should be read aloud by Discord or not. /// The to be sent. @@ -29,6 +30,7 @@ namespace Discord /// /// Sends a file to this message channel with an optional caption. /// + /// The user to send the DM to. /// The of the file to be sent. /// The name of the attachment. /// The message to be sent. @@ -58,6 +60,7 @@ namespace Discord /// /// Sends a file via DM with an optional caption. /// + /// The user to send the DM to. /// The file path of the file. /// The message to be sent. /// Whether the message should be read aloud by Discord or not. @@ -89,6 +92,7 @@ namespace Discord /// The number of days to remove messages from this user for - must be between [0, 7] /// /// The reason of the ban to be written in the audit log. + /// The options to be used when sending the request. /// is not between 0 to 7. public static Task BanAsync(this IGuildUser user, int pruneDays = 0, string reason = null, RequestOptions options = null) => user.Guild.AddBanAsync(user, pruneDays, reason, options); diff --git a/src/Discord.Net.Core/IDiscordClient.cs b/src/Discord.Net.Core/IDiscordClient.cs index da9ef3d6d..b302e05a6 100644 --- a/src/Discord.Net.Core/IDiscordClient.cs +++ b/src/Discord.Net.Core/IDiscordClient.cs @@ -62,12 +62,12 @@ namespace Discord /// Gets a generic channel via the snowflake identifier. /// /// - /// - /// var channel = await _client.GetChannelAsync(381889909113225237); - /// if (channel != null && channel is IMessageChannel msgChannel) - /// { - /// await msgChannel.SendMessageAsync($"{msgChannel} is created at {msgChannel.CreatedAt}"); - /// } + /// + /// var channel = await _client.GetChannelAsync(381889909113225237); + /// if (channel != null && channel is IMessageChannel msgChannel) + /// { + /// await msgChannel.SendMessageAsync($"{msgChannel} is created at {msgChannel.CreatedAt}"); + /// } /// /// /// The snowflake identifier of the channel (e.g. `381889909113225237`). @@ -150,10 +150,10 @@ namespace Discord /// Gets a user via the snowflake identifier. /// /// - /// - /// var user = await _client.GetUserAsync(168693960628371456); - /// if (user != null) - /// Console.WriteLine($"{user} is created at {user.CreatedAt}."; + /// + /// var user = await _client.GetUserAsync(168693960628371456); + /// if (user != null) + /// Console.WriteLine($"{user} is created at {user.CreatedAt}."; /// /// /// The snowflake identifier of the user (e.g. `168693960628371456`). @@ -170,9 +170,9 @@ namespace Discord /// /// /// - /// var user = await _client.GetUserAsync("Still", "2876"); - /// if (user != null) - /// Console.WriteLine($"{user} is created at {user.CreatedAt}."; + /// var user = await _client.GetUserAsync("Still", "2876"); + /// if (user != null) + /// Console.WriteLine($"{user} is created at {user.CreatedAt}."; /// /// /// The name of the user (e.g. `Still`). diff --git a/src/Discord.Net.Rest/DiscordRestApiClient.cs b/src/Discord.Net.Rest/DiscordRestApiClient.cs index d9f1eddea..194046863 100644 --- a/src/Discord.Net.Rest/DiscordRestApiClient.cs +++ b/src/Discord.Net.Rest/DiscordRestApiClient.cs @@ -45,6 +45,7 @@ namespace Discord.API internal IRestClient RestClient { get; private set; } internal ulong? CurrentUserId { get; set;} + /// Unknown OAuth token type. public DiscordRestApiClient(RestClientProvider restClientProvider, string userAgent, RetryMode defaultRetryMode = RetryMode.AlwaysRetry, JsonSerializer serializer = null) { @@ -60,7 +61,6 @@ namespace Discord.API } /// Unknown OAuth token type. - /// A delegate callback throws an exception. internal void SetBaseUrl(string baseUrl) { RestClient = _restClientProvider(baseUrl); diff --git a/src/Discord.Net.Rest/DiscordRestClient.cs b/src/Discord.Net.Rest/DiscordRestClient.cs index 3a19dd1a5..2737e1ac1 100644 --- a/src/Discord.Net.Rest/DiscordRestClient.cs +++ b/src/Discord.Net.Rest/DiscordRestClient.cs @@ -5,13 +5,24 @@ using System.Threading.Tasks; namespace Discord.Rest { + /// + /// Provides a client to send REST-based requests to Discord. + /// public class DiscordRestClient : BaseDiscordClient, IDiscordClient { private RestApplication _applicationInfo; + /// + /// Gets the logged-in user. + /// public new RestSelfUser CurrentUser => base.CurrentUser as RestSelfUser; + /// public DiscordRestClient() : this(new DiscordRestConfig()) { } + /// + /// Initializes a new with the provided configuratation. + /// + /// The configuration to be used with the client. public DiscordRestClient(DiscordRestConfig config) : base(config, CreateApiClient(config)) { } private static API.DiscordRestApiClient CreateApiClient(DiscordRestConfig config)