From 1a9d4b6cb956d94f55b8d38e92bda4236a0b385a Mon Sep 17 00:00:00 2001 From: Still Hsu <341464@gmail.com> Date: Wed, 5 Sep 2018 02:34:53 +0800 Subject: [PATCH] Add XML docs --- Discord.Net.sln.DotSettings | 2 ++ .../Preconditions/RequireContextAttribute.cs | 2 +- .../Preconditions/RequireNsfwAttribute.cs | 5 +++++ .../Preconditions/RequireOwnerAttribute.cs | 12 ++++++++++-- .../RequireUserPermissionAttribute.cs | 2 +- .../Entities/Channels/IGuildChannel.cs | 16 ++++++++++++++++ src/Discord.Net.Core/RetryMode.cs | 4 ++-- src/Discord.Net.Core/Utils/TokenUtils.cs | 7 +++---- .../Entities/Channels/SocketCategoryChannel.cs | 13 +++++++++++++ .../Entities/Channels/SocketGroupChannel.cs | 2 ++ .../Entities/Channels/SocketGuildChannel.cs | 1 - 11 files changed, 55 insertions(+), 11 deletions(-) diff --git a/Discord.Net.sln.DotSettings b/Discord.Net.sln.DotSettings index b29ba331c..ca75a7f1b 100644 --- a/Discord.Net.sln.DotSettings +++ b/Discord.Net.sln.DotSettings @@ -1,8 +1,10 @@  + True True True True True + True True True True diff --git a/src/Discord.Net.Commands/Attributes/Preconditions/RequireContextAttribute.cs b/src/Discord.Net.Commands/Attributes/Preconditions/RequireContextAttribute.cs index 3b33552a2..810b62014 100644 --- a/src/Discord.Net.Commands/Attributes/Preconditions/RequireContextAttribute.cs +++ b/src/Discord.Net.Commands/Attributes/Preconditions/RequireContextAttribute.cs @@ -66,7 +66,7 @@ namespace Discord.Commands if (isValid) return Task.FromResult(PreconditionResult.FromSuccess()); else - return Task.FromResult(PreconditionResult.FromError($"Invalid context for command; accepted contexts: {Contexts}")); + return Task.FromResult(PreconditionResult.FromError($"Invalid context for command; accepted contexts: {Contexts}.")); } } } diff --git a/src/Discord.Net.Commands/Attributes/Preconditions/RequireNsfwAttribute.cs b/src/Discord.Net.Commands/Attributes/Preconditions/RequireNsfwAttribute.cs index d97db8290..6a6f7eb6d 100644 --- a/src/Discord.Net.Commands/Attributes/Preconditions/RequireNsfwAttribute.cs +++ b/src/Discord.Net.Commands/Attributes/Preconditions/RequireNsfwAttribute.cs @@ -6,6 +6,11 @@ namespace Discord.Commands /// /// Requires the command to be invoked in a channel marked NSFW. /// + /// + /// The precondition will restrict the access of the command or module to be accessed within a guild channel + /// that has been marked as mature or NSFW. If the channel is not of type or the + /// channel is not marked as NSFW, the precondition will fail with an erroneous . + /// [AttributeUsage(AttributeTargets.Class | AttributeTargets.Method, AllowMultiple = true, Inherited = true)] public class RequireNsfwAttribute : PreconditionAttribute { diff --git a/src/Discord.Net.Commands/Attributes/Preconditions/RequireOwnerAttribute.cs b/src/Discord.Net.Commands/Attributes/Preconditions/RequireOwnerAttribute.cs index 3ea35a9fd..0b9571a2a 100644 --- a/src/Discord.Net.Commands/Attributes/Preconditions/RequireOwnerAttribute.cs +++ b/src/Discord.Net.Commands/Attributes/Preconditions/RequireOwnerAttribute.cs @@ -4,9 +4,17 @@ using System.Threading.Tasks; namespace Discord.Commands { /// - /// Requires the command to be invoked by the owner of the bot. + /// Requires the command to be invoked by the owner of the bot. /// - /// This precondition will only work if the bot is a bot account. + /// + /// This precondition will restrict the access of the command or module to the owner of the Discord application. + /// If the precondition fails to be met, an erroneous will be returned with the + /// message "Command can only be run by the owner of the bot." + /// + /// This precondition will only work if the account has a of + /// ;otherwise, this precondition will always fail. + /// + /// [AttributeUsage(AttributeTargets.Class | AttributeTargets.Method, AllowMultiple = true, Inherited = true)] public class RequireOwnerAttribute : PreconditionAttribute { diff --git a/src/Discord.Net.Commands/Attributes/Preconditions/RequireUserPermissionAttribute.cs b/src/Discord.Net.Commands/Attributes/Preconditions/RequireUserPermissionAttribute.cs index e12b0c737..e9b1c0c5d 100644 --- a/src/Discord.Net.Commands/Attributes/Preconditions/RequireUserPermissionAttribute.cs +++ b/src/Discord.Net.Commands/Attributes/Preconditions/RequireUserPermissionAttribute.cs @@ -4,7 +4,7 @@ using System.Threading.Tasks; namespace Discord.Commands { /// - /// Requires the user invoking the command to have a specified permission. + /// Requires the user invoking the command to have a specified permission. /// [AttributeUsage(AttributeTargets.Class | AttributeTargets.Method, AllowMultiple = true, Inherited = true)] public class RequireUserPermissionAttribute : PreconditionAttribute diff --git a/src/Discord.Net.Core/Entities/Channels/IGuildChannel.cs b/src/Discord.Net.Core/Entities/Channels/IGuildChannel.cs index 6bd2d3e7d..c3a2161cc 100644 --- a/src/Discord.Net.Core/Entities/Channels/IGuildChannel.cs +++ b/src/Discord.Net.Core/Entities/Channels/IGuildChannel.cs @@ -47,6 +47,13 @@ namespace Discord /// /// Creates a new invite to this channel. /// + /// + /// The following example creates a new invite to this channel; the invite lasts for 12 hours and can only + /// be used 3 times throughout its lifespan. + /// + /// await guildChannel.CreateInviteAsync(maxAge: 43200, maxUses: 3); + /// + /// /// The time (in seconds) until the invite expires. Set to null to never expire. /// The max amount of times this invite may be used. Set to null to have unlimited uses. /// If true, the user accepting this invite will be kicked from the guild after closing their client. @@ -60,6 +67,15 @@ namespace Discord /// /// Gets a collection of all invites to this channel. /// + /// + /// The following example gets all of the invites that have been created in this channel and selects the + /// most used invite. + /// + /// var invites = await channel.GetInvitesAsync(); + /// if (invites.Count == 0) return; + /// var invite = invites.OrderByDescending(x => x.Uses).FirstOrDefault(); + /// + /// /// The options to be used when sending the request. /// /// A task that represents the asynchronous get operation. The task result contains a read-only collection diff --git a/src/Discord.Net.Core/RetryMode.cs b/src/Discord.Net.Core/RetryMode.cs index 65ae75fc3..1e09f4dd1 100644 --- a/src/Discord.Net.Core/RetryMode.cs +++ b/src/Discord.Net.Core/RetryMode.cs @@ -1,4 +1,4 @@ -using System; +using System; namespace Discord { @@ -12,7 +12,7 @@ namespace Discord RetryTimeouts = 0x1, // /// Retry if a request failed due to a network error. //RetryErrors = 0x2, - /// Retry if a request failed due to a ratelimit. + /// Retry if a request failed due to a rate-limit. RetryRatelimit = 0x4, /// Retry if a request failed due to an HTTP error 502. Retry502 = 0x8, diff --git a/src/Discord.Net.Core/Utils/TokenUtils.cs b/src/Discord.Net.Core/Utils/TokenUtils.cs index 6ff36548c..45d769441 100644 --- a/src/Discord.Net.Core/Utils/TokenUtils.cs +++ b/src/Discord.Net.Core/Utils/TokenUtils.cs @@ -1,11 +1,10 @@ using System; -using System.Collections.Generic; -using System.Linq; -using System.Text; -using System.Threading.Tasks; namespace Discord { + /// + /// Provides a series of helper methods for handling Discord login tokens. + /// public static class TokenUtils { /// diff --git a/src/Discord.Net.WebSocket/Entities/Channels/SocketCategoryChannel.cs b/src/Discord.Net.WebSocket/Entities/Channels/SocketCategoryChannel.cs index 4c224e09a..0ae40820c 100644 --- a/src/Discord.Net.WebSocket/Entities/Channels/SocketCategoryChannel.cs +++ b/src/Discord.Net.WebSocket/Entities/Channels/SocketCategoryChannel.cs @@ -20,6 +20,14 @@ namespace Discord.WebSocket Permissions.ResolveChannel(Guild, x, this, Permissions.ResolveGuild(Guild, x)), ChannelPermission.ViewChannel)).ToImmutableArray(); + /// + /// Gets the child channels of this category. + /// + /// + /// A read-only collection of whose + /// matches the snowflake identifier of this category + /// channel. + /// public IReadOnlyCollection Channels => Guild.Channels.Where(x => x is INestedChannel nestedChannel && nestedChannel.CategoryId == Id).ToImmutableArray(); @@ -35,6 +43,7 @@ namespace Discord.WebSocket } //Users + /// public override SocketGuildUser GetUser(ulong id) { var user = Guild.GetUser(id); @@ -52,8 +61,10 @@ namespace Discord.WebSocket internal new SocketCategoryChannel Clone() => MemberwiseClone() as SocketCategoryChannel; // IGuildChannel + /// IAsyncEnumerable> IGuildChannel.GetUsersAsync(CacheMode mode, RequestOptions options) => ImmutableArray.Create>(Users).ToAsyncEnumerable(); + /// Task IGuildChannel.GetUserAsync(ulong id, CacheMode mode, RequestOptions options) => Task.FromResult(GetUser(id)); /// @@ -66,8 +77,10 @@ namespace Discord.WebSocket => throw new NotSupportedException(); //IChannel + /// IAsyncEnumerable> IChannel.GetUsersAsync(CacheMode mode, RequestOptions options) => ImmutableArray.Create>(Users).ToAsyncEnumerable(); + /// Task IChannel.GetUserAsync(ulong id, CacheMode mode, RequestOptions options) => Task.FromResult(GetUser(id)); } diff --git a/src/Discord.Net.WebSocket/Entities/Channels/SocketGroupChannel.cs b/src/Discord.Net.WebSocket/Entities/Channels/SocketGroupChannel.cs index fd661eb6e..1fc289f41 100644 --- a/src/Discord.Net.WebSocket/Entities/Channels/SocketGroupChannel.cs +++ b/src/Discord.Net.WebSocket/Entities/Channels/SocketGroupChannel.cs @@ -119,8 +119,10 @@ namespace Discord.WebSocket public Task SendFileAsync(Stream stream, string filename, string text, bool isTTS = false, Embed embed = null, RequestOptions options = null) => ChannelHelper.SendFileAsync(this, Discord, stream, filename, text, isTTS, embed, options); + /// public Task DeleteMessageAsync(ulong messageId, RequestOptions options = null) => ChannelHelper.DeleteMessageAsync(this, messageId, Discord, options); + /// public Task DeleteMessageAsync(IMessage message, RequestOptions options = null) => ChannelHelper.DeleteMessageAsync(this, message.Id, Discord, options); diff --git a/src/Discord.Net.WebSocket/Entities/Channels/SocketGuildChannel.cs b/src/Discord.Net.WebSocket/Entities/Channels/SocketGuildChannel.cs index d86e5ff9b..bf1b2260b 100644 --- a/src/Discord.Net.WebSocket/Entities/Channels/SocketGuildChannel.cs +++ b/src/Discord.Net.WebSocket/Entities/Channels/SocketGuildChannel.cs @@ -219,7 +219,6 @@ namespace Discord.WebSocket /// public override string ToString() => Name; private string DebuggerDisplay => $"{Name} ({Id}, Guild)"; - /// internal new SocketGuildChannel Clone() => MemberwiseClone() as SocketGuildChannel; //SocketChannel