From b940ecb95e221659c2af920327d692aaf654bceb Mon Sep 17 00:00:00 2001 From: Still Hsu <341464@gmail.com> Date: Wed, 11 Jul 2018 06:29:11 +0800 Subject: [PATCH] Add XML docs & patch return types + Starting from this commit, all return types for tasks will use style similar to most documentations featured on docs.microsoft.com References: https://docs.microsoft.com/en-us/dotnet/api/microsoft.entityframeworkcore.dbcontext.-ctor?view=efcore-2.1 https://docs.microsoft.com/en-us/dotnet/api/system.io.filestream.readasync?view=netcore-2.1 https://docs.microsoft.com/en-us/dotnet/api/system.io.textwriter.writelineasync?view=netcore-2.1#System_IO_TextWriter_WriteLineAsync_System_Char___ And many more other asynchronous method documentations featured in the latest BCL. --- .../Channels/GuildChannelProperties.cs | 7 +- .../Entities/Channels/IAudioChannel.cs | 14 +- .../Entities/Channels/IChannel.cs | 7 +- .../Entities/Channels/IDMChannel.cs | 6 + .../Entities/Channels/IGroupChannel.cs | 3 + .../Entities/Channels/IGuildChannel.cs | 56 ++-- .../Entities/Channels/IMessageChannel.cs | 78 +++-- .../Entities/Channels/INestedChannel.cs | 5 +- .../Entities/Channels/IPrivateChannel.cs | 2 +- .../Entities/Channels/ITextChannel.cs | 34 +- .../Entities/Channels/IVoiceChannel.cs | 17 +- .../Channels/ReorderChannelProperties.cs | 4 +- .../Channels/TextChannelProperties.cs | 6 +- .../Channels/VoiceChannelProperties.cs | 2 +- src/Discord.Net.Core/Entities/Emotes/Emoji.cs | 5 +- src/Discord.Net.Core/Entities/Emotes/Emote.cs | 15 +- .../Entities/Emotes/EmoteProperties.cs | 2 +- .../Entities/Emotes/GuildEmote.cs | 13 +- .../Entities/Emotes/IEmote.cs | 3 + .../Entities/Guilds/GuildEmbedProperties.cs | 2 +- .../Guilds/GuildIntegrationProperties.cs | 2 +- .../Entities/Guilds/GuildProperties.cs | 2 +- .../Entities/Guilds/IGuild.cs | 313 ++++++++++-------- .../Entities/Permissions/GuildPermissions.cs | 2 +- src/Discord.Net.Core/Entities/Roles/Color.cs | 39 ++- .../Entities/Roles/ReorderRoleProperties.cs | 2 +- .../Entities/Users/IGuildUser.cs | 59 +++- .../Entities/Users/ISelfUser.cs | 10 +- .../Net/RateLimitedException.cs | 2 +- .../Entities/Channels/RestTextChannel.cs | 8 +- .../Entities/Channels/RestVoiceChannel.cs | 1 + .../Entities/Messages/RestSystemMessage.cs | 3 +- .../Entities/Guilds/SocketGuild.cs | 206 +++++++----- 33 files changed, 565 insertions(+), 365 deletions(-) diff --git a/src/Discord.Net.Core/Entities/Channels/GuildChannelProperties.cs b/src/Discord.Net.Core/Entities/Channels/GuildChannelProperties.cs index a0edfc796..4e92a2369 100644 --- a/src/Discord.Net.Core/Entities/Channels/GuildChannelProperties.cs +++ b/src/Discord.Net.Core/Entities/Channels/GuildChannelProperties.cs @@ -10,8 +10,11 @@ namespace Discord /// Gets or sets the channel to this name. /// /// - /// When modifying an , the - /// MUST be alphanumeric with dashes. It must match the following RegEx: [a-z0-9-_]{2,100} + /// This property defines the new name for this channel. + /// + /// When modifying an , the must be alphanumeric with + /// dashes. It must match the RegEx [a-z0-9-_]{2,100}. + /// /// public Optional Name { get; set; } /// diff --git a/src/Discord.Net.Core/Entities/Channels/IAudioChannel.cs b/src/Discord.Net.Core/Entities/Channels/IAudioChannel.cs index e6642d8b0..6d8ef2cd3 100644 --- a/src/Discord.Net.Core/Entities/Channels/IAudioChannel.cs +++ b/src/Discord.Net.Core/Entities/Channels/IAudioChannel.cs @@ -12,9 +12,21 @@ namespace Discord /// /// Connects to this audio channel. /// + /// Determines whether the client should deaf itself upon connection. + /// Determines whether the client should mute itself upon connection. + /// Determines whether the audio client is an external one or not. + /// + /// A task representing the asynchronous connection operation. The task result contains the + /// responsible for the connection. + /// Task ConnectAsync(bool selfDeaf = false, bool selfMute = false, bool external = false); - /// Disconnects from this audio channel. + /// + /// Disconnects from this audio channel. + /// + /// + /// A task representing the asynchronous disconnection operation. + /// Task DisconnectAsync(); } } diff --git a/src/Discord.Net.Core/Entities/Channels/IChannel.cs b/src/Discord.Net.Core/Entities/Channels/IChannel.cs index 04408989b..b66f778fb 100644 --- a/src/Discord.Net.Core/Entities/Channels/IChannel.cs +++ b/src/Discord.Net.Core/Entities/Channels/IChannel.cs @@ -31,11 +31,12 @@ namespace Discord /// /// Gets a user in this channel. /// - /// The snowflake identifier of the user (e.g. 168693960628371456). - /// The that determines whether the object should be fetched from cache. + /// The snowflake identifier of the user (e.g. 168693960628371456). + /// The that determines whether the object should be fetched from cache. /// The options to be used when sending the request. /// - /// An awaitable containing a user object that represents the user. + /// A task that represents the asynchronous get operation. The task result contains a user object that + /// represents the found user; null if none is found. /// Task GetUserAsync(ulong id, CacheMode mode = CacheMode.AllowDownload, RequestOptions options = null); } diff --git a/src/Discord.Net.Core/Entities/Channels/IDMChannel.cs b/src/Discord.Net.Core/Entities/Channels/IDMChannel.cs index 49e58038a..f0ef7f3f3 100644 --- a/src/Discord.Net.Core/Entities/Channels/IDMChannel.cs +++ b/src/Discord.Net.Core/Entities/Channels/IDMChannel.cs @@ -10,12 +10,18 @@ namespace Discord /// /// Gets the recipient of all messages in this channel. /// + /// + /// A user object that represents the other user in this channel. + /// IUser Recipient { get; } /// /// Closes this private channel, removing it from your channel list. /// /// The options to be used when sending the request. + /// + /// A task that represents the asynchronous close operation. + /// Task CloseAsync(RequestOptions options = null); } } diff --git a/src/Discord.Net.Core/Entities/Channels/IGroupChannel.cs b/src/Discord.Net.Core/Entities/Channels/IGroupChannel.cs index 8ee2b622c..77af3450e 100644 --- a/src/Discord.Net.Core/Entities/Channels/IGroupChannel.cs +++ b/src/Discord.Net.Core/Entities/Channels/IGroupChannel.cs @@ -11,6 +11,9 @@ namespace Discord /// Leaves this group. /// /// The options to be used when sending the request. + /// + /// A task that represents the asynchronous leave operation. + /// Task LeaveAsync(RequestOptions options = null); } } diff --git a/src/Discord.Net.Core/Entities/Channels/IGuildChannel.cs b/src/Discord.Net.Core/Entities/Channels/IGuildChannel.cs index 301737aa1..7c4dd8675 100644 --- a/src/Discord.Net.Core/Entities/Channels/IGuildChannel.cs +++ b/src/Discord.Net.Core/Entities/Channels/IGuildChannel.cs @@ -16,7 +16,8 @@ namespace Discord /// Gets the position of this channel. /// /// - /// The position of this channel in the guild's channel list, relative to others of the same type. + /// An representing the position of this channel in the guild's channel list relative to + /// others of the same type. /// int Position { get; } @@ -24,14 +25,15 @@ namespace Discord /// Gets the guild associated with this channel. /// /// - /// A guild that this channel belongs to. + /// A guild object that this channel belongs to. /// IGuild Guild { get; } /// /// Gets the guild ID associated with this channel. /// /// - /// A guild snowflake identifier for the guild that this channel belongs to. + /// An representing the guild snowflake identifier for the guild that this channel + /// belongs to. /// ulong GuildId { get; } /// @@ -45,25 +47,14 @@ namespace Discord /// /// Creates a new invite to this channel. /// - /// - /// 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, a user accepting this invite will be kicked from the guild after closing their client. - /// - /// - /// If true, don't try to reuse a similar invite (useful for creating many unique one time use - /// invites). - /// - /// - /// The options to be used when sending the request. - /// + /// 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. + /// If true, don't try to reuse a similar invite (useful for creating many unique one time use invites). + /// The options to be used when sending the request. /// - /// An awaitable containing an invite metadata object containing information for the - /// created invite. + /// A task that represents the asynchronous invite creation operation. The task result contains an invite + /// metadata object containing information for the created invite. /// Task CreateInviteAsync(int? maxAge = 86400, int? maxUses = default(int?), bool isTemporary = false, bool isUnique = false, RequestOptions options = null); /// @@ -71,18 +62,18 @@ namespace Discord /// /// The options to be used when sending the request. /// - /// An awaitable containing a read-only collection of invite metadata that are created - /// for this channel. + /// A task that represents the asynchronous get operation. The task result contains a read-only collection + /// of invite metadata that are created for this channel. /// Task> GetInvitesAsync(RequestOptions options = null); /// /// Modifies this guild channel. /// - /// The properties to modify the channel with. + /// The delegate containing the properties to modify the channel with. /// The options to be used when sending the request. /// - /// An awaitable . + /// A task that represents the asynchronous modification operation. /// Task ModifyAsync(Action func, RequestOptions options = null); @@ -108,7 +99,7 @@ namespace Discord /// The role to remove the overwrite from. /// The options to be used when sending the request. /// - /// An awaitable . + /// A task representing the asynchronous removal operation. /// Task RemovePermissionOverwriteAsync(IRole role, RequestOptions options = null); /// @@ -117,7 +108,7 @@ namespace Discord /// The user to remove the overwrite from. /// The options to be used when sending the request. /// - /// An awaitable . + /// A task representing the asynchronous removal operation. /// Task RemovePermissionOverwriteAsync(IUser user, RequestOptions options = null); @@ -128,7 +119,7 @@ namespace Discord /// The overwrite to add to the role. /// The options to be used when sending the request. /// - /// An awaitable . + /// A task representing the asynchronous permission addition operation. /// Task AddPermissionOverwriteAsync(IRole role, OverwritePermissions permissions, RequestOptions options = null); /// @@ -138,7 +129,7 @@ namespace Discord /// The overwrite to add to the user. /// The options to be used when sending the request. /// - /// An awaitable . + /// A task representing the asynchronous permission addition operation. /// Task AddPermissionOverwriteAsync(IUser user, OverwritePermissions permissions, RequestOptions options = null); @@ -159,12 +150,11 @@ namespace Discord /// Gets a user in this channel with the provided ID. /// /// The ID of the user. - /// - /// The that determines whether the object should be fetched from cache. - /// + /// The that determines whether the object should be fetched from cache. /// The options to be used when sending the request. /// - /// An awaitable containing a guild user object that represents the user. + /// A task representing the asynchrnous get operation. The task result contains a guild user object that + /// represents the user; null if none is found. /// new Task GetUserAsync(ulong id, CacheMode mode = CacheMode.AllowDownload, RequestOptions options = null); } diff --git a/src/Discord.Net.Core/Entities/Channels/IMessageChannel.cs b/src/Discord.Net.Core/Entities/Channels/IMessageChannel.cs index 0bb6f7818..ef62f5d4f 100644 --- a/src/Discord.Net.Core/Entities/Channels/IMessageChannel.cs +++ b/src/Discord.Net.Core/Entities/Channels/IMessageChannel.cs @@ -14,59 +14,67 @@ namespace Discord /// Sends a message to this message channel. /// /// The message to be sent. - /// Whether the message should be read aloud by Discord or not. - /// The to be sent. + /// Determines whether the message should be read aloud by Discord or not. + /// The to be sent. /// The options to be used when sending the request. /// - /// An awaitable Task containing the message sent to the channel. + /// A task that represents an asynchrnous send operation for delievering the message. The task result + /// contains the sent message. /// Task SendMessageAsync(string text = null, bool isTTS = false, Embed embed = null, RequestOptions options = null); /// /// Sends a file to this message channel with an optional caption. /// + /// + /// This method sends a file as if you are uploading an attachment directly from your Discord client. + /// + /// If you wish to upload an image and have it embedded in a embed, + /// you may upload the file and refer to the file with "attachment://filename.ext" in the + /// . + /// + /// /// The file path of the file. /// The message to be sent. /// Whether the message should be read aloud by Discord or not. - /// The to be sent. + /// The to be sent. /// The options to be used when sending the request. - /// - /// If you wish to upload an image and have it embedded in a embed, you may - /// upload the file and refer to the file with "attachment://filename.ext" in the - /// . - /// /// - /// An awaitable Task containing the message sent to the channel. + /// A task that represents an asynchrnous send operation for delievering the message. The task result + /// contains the sent message. /// Task SendFileAsync(string filePath, string text = null, bool isTTS = false, Embed embed = null, RequestOptions options = null); /// /// Sends a file to this message channel with an optional caption. /// - /// The of the file to be sent. + /// + /// This method sends a file as if you are uploading an attachment directly from your Discord client. + /// + /// If you wish to upload an image and have it embedded in a embed, + /// you may upload the file and refer to the file with "attachment://filename.ext" in the + /// . + /// + /// + /// The of the file to be sent. /// The name of the attachment. /// The message to be sent. /// Whether the message should be read aloud by Discord or not. - /// The to be sent. + /// The to be sent. /// The options to be used when sending the request. - /// - /// If you wish to upload an image and have it embedded in a embed, you may - /// upload the file and refer to the file with "attachment://filename.ext" in the - /// . - /// /// - /// An awaitable containing the message sent to the channel. + /// A task that represents an asynchrnous send operation for delievering the message. The task result + /// contains the sent message. /// Task SendFileAsync(Stream stream, string filename, string text = null, bool isTTS = false, Embed embed = null, RequestOptions options = null); /// /// Gets a message from this message channel. /// - /// The ID of the message. - /// The that determines whether the object should be fetched from - /// cache. + /// The snowflake identifier of the message. + /// The that determines whether the object should be fetched from cache. /// The options to be used when sending the request. /// - /// An awaitable containing the message gotten from either the cache or the download; - /// null if none is found or if the message fails to be retrieved. + /// A task that represents an asynchrnous get operation for retrieving the message. The task result contains + /// the retrieved message; null if no message is found with the specified identifier. /// Task GetMessageAsync(ulong id, CacheMode mode = CacheMode.AllowDownload, RequestOptions options = null); @@ -116,25 +124,45 @@ namespace Discord /// /// The options to be used when sending the request. /// - /// An awaitable Task containing a collection of messages. + /// A task that represents the asynchronous get operation for retrieving pinned messages in this channel. + /// The task result contains a collection of messages found in the pinned messages. /// Task> GetPinnedMessagesAsync(RequestOptions options = null); - /// Deletes a message based on the message ID in this channel. + /// + /// Deletes a message. + /// + /// The snowflake identifier of the message that would be removed. + /// The options to be used when sending the request. + /// + /// A task that represents the asynchronous removal operation. + /// Task DeleteMessageAsync(ulong messageId, RequestOptions options = null); /// Deletes a message based on the provided message in this channel. + /// The message that would be removed. + /// The options to be used when sending the request. + /// + /// A task that represents the asynchronous removal operation. + /// Task DeleteMessageAsync(IMessage message, RequestOptions options = null); /// /// Broadcasts the "user is typing" message to all users in this channel, lasting 10 seconds. /// /// The options to be used when sending the request. + /// + /// A task that represents the asynchronous operation that triggers the broadcast. + /// Task TriggerTypingAsync(RequestOptions options = null); /// /// Continuously broadcasts the "user is typing" message to all users in this channel until the returned /// object is disposed. /// /// The options to be used when sending the request. + /// + /// A disposable object that, upon its disposal, will stop the client from broadcasting its typing state in + /// this channel. + /// IDisposable EnterTypingState(RequestOptions options = null); } } diff --git a/src/Discord.Net.Core/Entities/Channels/INestedChannel.cs b/src/Discord.Net.Core/Entities/Channels/INestedChannel.cs index 99a4e6cd5..c6fcba9de 100644 --- a/src/Discord.Net.Core/Entities/Channels/INestedChannel.cs +++ b/src/Discord.Net.Core/Entities/Channels/INestedChannel.cs @@ -11,7 +11,7 @@ namespace Discord /// Gets the parent (category) ID of this channel in the guild's channel list. /// /// - /// An representing the snowflake identifier of the parent of this channel; + /// A representing the snowflake identifier of the parent of this channel; /// null if none is set. /// ulong? CategoryId { get; } @@ -21,7 +21,8 @@ namespace Discord /// The that determines whether the object should be fetched from cache. /// The options to be used when sending the request. /// - /// A category channel representing the parent of this channel; null if none is set. + /// A task that represents the asynchrnous get operation. The task result contains the category channel + /// representing the parent of this channel; null if none is set. /// Task GetCategoryAsync(CacheMode mode = CacheMode.AllowDownload, RequestOptions options = null); } diff --git a/src/Discord.Net.Core/Entities/Channels/IPrivateChannel.cs b/src/Discord.Net.Core/Entities/Channels/IPrivateChannel.cs index 41b409141..cd2307c2d 100644 --- a/src/Discord.Net.Core/Entities/Channels/IPrivateChannel.cs +++ b/src/Discord.Net.Core/Entities/Channels/IPrivateChannel.cs @@ -11,7 +11,7 @@ namespace Discord /// Gets the users that can access this channel. /// /// - /// A collection of users that can access this channel. + /// A read-only collection of users that can access this channel. /// IReadOnlyCollection Recipients { get; } } diff --git a/src/Discord.Net.Core/Entities/Channels/ITextChannel.cs b/src/Discord.Net.Core/Entities/Channels/ITextChannel.cs index d043297b2..e619c1735 100644 --- a/src/Discord.Net.Core/Entities/Channels/ITextChannel.cs +++ b/src/Discord.Net.Core/Entities/Channels/ITextChannel.cs @@ -14,7 +14,7 @@ namespace Discord /// Determines whether the channel is NSFW. /// /// - /// true if the channel has the NSFW flag enabled; otherwise, false. + /// true if the channel has the NSFW flag enabled; otherwise false. /// bool IsNsfw { get; } @@ -22,7 +22,7 @@ namespace Discord /// Gets the current topic for this text channel. /// /// - /// The topic set in the channel, or null if none is set. + /// A string representing the topic set in the channel; null if none is set. /// string Topic { get; } @@ -30,30 +30,42 @@ namespace Discord /// Bulk-deletes multiple messages. /// /// + /// This method attempts to remove the messages specified in bulk. /// - /// This method can only remove messages that are posted within 14 days! + /// Due to the limitation set by Discord, this method can only remove messages that are posted within 14 days! /// /// /// The messages to be bulk-deleted. /// The options to be used when sending the request. + /// + /// A task that represents the asynchronous bulk-removal operation. + /// Task DeleteMessagesAsync(IEnumerable messages, RequestOptions options = null); /// /// Bulk-deletes multiple messages. /// /// + /// This method attempts to remove the messages specified in bulk. /// - /// This method can only remove messages that are posted within 14 days! + /// Due to the limitation set by Discord, this method can only remove messages that are posted within 14 days! /// /// - /// The IDs of the messages to be bulk-deleted. + /// The snowflake identifier of the messages to be bulk-deleted. /// The options to be used when sending the request. + /// + /// A task that represents the asynchronous bulk-removal operation. + /// Task DeleteMessagesAsync(IEnumerable messageIds, RequestOptions options = null); /// /// Modifies this text channel. /// - /// The properties to modify the channel with. + /// The delegate containing the properties to modify the channel with. /// The options to be used when sending the request. + /// + /// A task that represents the asynchronous modification operation. + /// + /// Task ModifyAsync(Action func, RequestOptions options = null); /// @@ -63,7 +75,8 @@ namespace Discord /// The avatar of the webhook. /// The options to be used when sending the request. /// - /// An awaitable containing the created webhook. + /// A task that represents the asynchronous creation operation. The task result contains the newly created + /// webhook. /// Task CreateWebhookAsync(string name, Stream avatar = null, RequestOptions options = null); /// @@ -72,8 +85,8 @@ namespace Discord /// The identifier of the webhook. /// The options to be used when sending the request. /// - /// An awaitable containing a webhook associated with the identifier; null if not - /// found. + /// A task that represents the asynchronous get operation. The task result contains a webhook associated + /// with the identifier; null if the webhook is not found. /// Task GetWebhookAsync(ulong id, RequestOptions options = null); /// @@ -81,7 +94,8 @@ namespace Discord /// /// The options to be used when sending the request. /// - /// An awaitable containing a collection of found webhooks. + /// A task that represents the asynchronous get operation. The task result contains a read-only collection + /// of webhooks that is available in this channel. /// Task> GetWebhooksAsync(RequestOptions options = null); } diff --git a/src/Discord.Net.Core/Entities/Channels/IVoiceChannel.cs b/src/Discord.Net.Core/Entities/Channels/IVoiceChannel.cs index 3119a5ae7..b222ca004 100644 --- a/src/Discord.Net.Core/Entities/Channels/IVoiceChannel.cs +++ b/src/Discord.Net.Core/Entities/Channels/IVoiceChannel.cs @@ -9,13 +9,20 @@ namespace Discord public interface IVoiceChannel : INestedChannel, IAudioChannel { /// - /// Gets the bitrate, in bits per second, clients in this voice channel are requested to use. + /// Gets the bitrate that the clients in this voice channel are requested to use. /// + /// + /// An representing the bitrate (bps) that this voice channel defines and requests the + /// client(s) to use. + /// int Bitrate { get; } /// - /// Gets the max amount of users allowed to be connected to this channel at one time, or - /// null if none is set. + /// Gets the max number of users allowed to be connected to this channel at once. /// + /// + /// An representing the maxmimum number of users that are allowed to be connected to this + /// channel at once; null if a limit is not set. + /// int? UserLimit { get; } /// @@ -23,6 +30,10 @@ namespace Discord /// /// The properties to modify the channel with. /// The options to be used when sending the request. + /// + /// A task that represents the asynchronous modification operation. + /// + /// Task ModifyAsync(Action func, RequestOptions options = null); } } diff --git a/src/Discord.Net.Core/Entities/Channels/ReorderChannelProperties.cs b/src/Discord.Net.Core/Entities/Channels/ReorderChannelProperties.cs index 55427aec7..903a2a047 100644 --- a/src/Discord.Net.Core/Entities/Channels/ReorderChannelProperties.cs +++ b/src/Discord.Net.Core/Entities/Channels/ReorderChannelProperties.cs @@ -1,7 +1,7 @@ namespace Discord { /// - /// Properties that are used to reorder an . + /// Provides properties that are used to reorder an . /// public class ReorderChannelProperties { @@ -20,7 +20,7 @@ namespace Discord /// public int Position { get; } - /// Creates a used to reorder a channel. + /// Initializes a new instance of the class used to reorder a channel. /// Sets the ID of the channel to apply this position to. /// Sets the new zero-based position of this channel. public ReorderChannelProperties(ulong id, int position) diff --git a/src/Discord.Net.Core/Entities/Channels/TextChannelProperties.cs b/src/Discord.Net.Core/Entities/Channels/TextChannelProperties.cs index 03b56b26c..471f74c7d 100644 --- a/src/Discord.Net.Core/Entities/Channels/TextChannelProperties.cs +++ b/src/Discord.Net.Core/Entities/Channels/TextChannelProperties.cs @@ -1,11 +1,9 @@ -using System; - namespace Discord { /// - /// Properties that are used to modify an with the specified changes. + /// Provides properties that are used to modify an with the specified changes. /// - /// + /// public class TextChannelProperties : GuildChannelProperties { /// diff --git a/src/Discord.Net.Core/Entities/Channels/VoiceChannelProperties.cs b/src/Discord.Net.Core/Entities/Channels/VoiceChannelProperties.cs index 46e8f8550..fb4d47800 100644 --- a/src/Discord.Net.Core/Entities/Channels/VoiceChannelProperties.cs +++ b/src/Discord.Net.Core/Entities/Channels/VoiceChannelProperties.cs @@ -1,7 +1,7 @@ namespace Discord { /// - /// Properties that are used to modify an with the specified changes. + /// Provides properties that are used to modify an with the specified changes. /// public class VoiceChannelProperties : GuildChannelProperties { diff --git a/src/Discord.Net.Core/Entities/Emotes/Emoji.cs b/src/Discord.Net.Core/Entities/Emotes/Emoji.cs index c7a2dc5eb..102abf7e2 100644 --- a/src/Discord.Net.Core/Entities/Emotes/Emoji.cs +++ b/src/Discord.Net.Core/Entities/Emotes/Emoji.cs @@ -12,10 +12,13 @@ namespace Discord /// /// Gets the Unicode representation of this emote. /// + /// + /// A string that resolves to . + /// public override string ToString() => Name; /// - /// Creates a Unicode emoji. + /// Initializes a new class with the provided Unicode. /// /// The pure UTF-8 encoding of an emoji. public Emoji(string unicode) diff --git a/src/Discord.Net.Core/Entities/Emotes/Emote.cs b/src/Discord.Net.Core/Entities/Emotes/Emote.cs index 32d49fede..d8a4d4088 100644 --- a/src/Discord.Net.Core/Entities/Emotes/Emote.cs +++ b/src/Discord.Net.Core/Entities/Emotes/Emote.cs @@ -17,14 +17,18 @@ namespace Discord /// /// Gets whether this emote is animated. /// + /// + /// A boolean that determines whether or not this emote is an animated one. + /// public bool Animated { get; } - /// - /// Gets the date when this emote is created. - /// + /// public DateTimeOffset CreatedAt => SnowflakeUtils.FromSnowflake(Id); /// /// Gets the image URL of this emote. /// + /// + /// A string that points to the URL of this emote. + /// public string Url => CDN.GetEmojiUrl(Id, Animated); internal Emote(ulong id, string name, bool animated) @@ -59,7 +63,7 @@ namespace Discord } /// Parses an from its raw format. - /// The raw encoding of an emote; for example, <:dab:277855270321782784>. + /// The raw encoding of an emote (e.g. <:dab:277855270321782784>). /// An emote. /// Invalid emote format. public static Emote Parse(string text) @@ -99,6 +103,9 @@ namespace Discord /// /// Returns the raw representation of the emote. /// + /// + /// A string representing the raw presentation of the emote (e.g. <:thonkang:282745590985523200>). + /// public override string ToString() => $"<{(Animated ? "a" : "")}:{Name}:{Id}>"; } } diff --git a/src/Discord.Net.Core/Entities/Emotes/EmoteProperties.cs b/src/Discord.Net.Core/Entities/Emotes/EmoteProperties.cs index a52f81ca7..41679d2af 100644 --- a/src/Discord.Net.Core/Entities/Emotes/EmoteProperties.cs +++ b/src/Discord.Net.Core/Entities/Emotes/EmoteProperties.cs @@ -3,7 +3,7 @@ using System.Collections.Generic; namespace Discord { /// - /// Properties that are used to modify an with the specified changes. + /// Provides properties that are used to modify an with the specified changes. /// /// public class EmoteProperties diff --git a/src/Discord.Net.Core/Entities/Emotes/GuildEmote.cs b/src/Discord.Net.Core/Entities/Emotes/GuildEmote.cs index f734c3648..3e13b1364 100644 --- a/src/Discord.Net.Core/Entities/Emotes/GuildEmote.cs +++ b/src/Discord.Net.Core/Entities/Emotes/GuildEmote.cs @@ -10,16 +10,25 @@ namespace Discord public class GuildEmote : Emote { /// - /// Gets whether this emoji is managed. + /// Gets whether this emoji is managed by an integration. /// + /// + /// A boolean that determines whether or not this emote is managed by a Twitch integration. + /// public bool IsManaged { get; } /// /// Gets whether this emoji must be wrapped in colons. /// + /// + /// A boolean that determines whether or not this emote requires the use of colons in chat to be used. + /// public bool RequireColons { get; } /// - /// Gets the roles this emoji is whitelisted to. + /// Gets the roles that are allowed to use this emoji. /// + /// + /// A read-only list containing snowflake identifiers for roles that are allowed to use this emoji. + /// public IReadOnlyList RoleIds { get; } internal GuildEmote(ulong id, string name, bool animated, bool isManaged, bool requireColons, IReadOnlyList roleIds) : base(id, name, animated) diff --git a/src/Discord.Net.Core/Entities/Emotes/IEmote.cs b/src/Discord.Net.Core/Entities/Emotes/IEmote.cs index e39601852..9141e8537 100644 --- a/src/Discord.Net.Core/Entities/Emotes/IEmote.cs +++ b/src/Discord.Net.Core/Entities/Emotes/IEmote.cs @@ -8,6 +8,9 @@ namespace Discord /// /// Gets the display name or Unicode representation of this emote. /// + /// + /// A string representing the display name or the Unicode representation (e.g. 🤔) of this emote. + /// string Name { get; } } } diff --git a/src/Discord.Net.Core/Entities/Guilds/GuildEmbedProperties.cs b/src/Discord.Net.Core/Entities/Guilds/GuildEmbedProperties.cs index 2977cd10c..34473e93c 100644 --- a/src/Discord.Net.Core/Entities/Guilds/GuildEmbedProperties.cs +++ b/src/Discord.Net.Core/Entities/Guilds/GuildEmbedProperties.cs @@ -1,7 +1,7 @@ namespace Discord { /// - /// Properties that are used to modify the widget of an with the specified changes. + /// Provides properties that are used to modify the widget of an with the specified changes. /// public class GuildEmbedProperties { diff --git a/src/Discord.Net.Core/Entities/Guilds/GuildIntegrationProperties.cs b/src/Discord.Net.Core/Entities/Guilds/GuildIntegrationProperties.cs index c8b5b3072..2ca19b50a 100644 --- a/src/Discord.Net.Core/Entities/Guilds/GuildIntegrationProperties.cs +++ b/src/Discord.Net.Core/Entities/Guilds/GuildIntegrationProperties.cs @@ -1,7 +1,7 @@ namespace Discord { /// - /// Properties used to modify an with the specified changes. + /// Provides properties used to modify an with the specified changes. /// public class GuildIntegrationProperties { diff --git a/src/Discord.Net.Core/Entities/Guilds/GuildProperties.cs b/src/Discord.Net.Core/Entities/Guilds/GuildProperties.cs index eccd852dd..0ffe8db35 100644 --- a/src/Discord.Net.Core/Entities/Guilds/GuildProperties.cs +++ b/src/Discord.Net.Core/Entities/Guilds/GuildProperties.cs @@ -1,7 +1,7 @@ namespace Discord { /// - /// Properties that are used to modify an with the specified changes. + /// Provides properties that are used to modify an with the specified changes. /// /// public class GuildProperties diff --git a/src/Discord.Net.Core/Entities/Guilds/IGuild.cs b/src/Discord.Net.Core/Entities/Guilds/IGuild.cs index 2f7aeca52..980b0dcfb 100644 --- a/src/Discord.Net.Core/Entities/Guilds/IGuild.cs +++ b/src/Discord.Net.Core/Entities/Guilds/IGuild.cs @@ -22,7 +22,7 @@ namespace Discord /// automatically moved to the AFK voice channel. /// /// - /// An representing the amount of time in seconds for a user to be marked as inactive + /// An representing the amount of time in seconds for a user to be marked as inactive /// and moved into the AFK voice channel. /// int AFKTimeout { get; } @@ -98,63 +98,88 @@ namespace Discord /// Gets the ID of the AFK voice channel for this guild. /// /// - /// An representing the snowflake identifier of the AFK voice channel; null if + /// A representing the snowflake identifier of the AFK voice channel; null if /// none is set. /// ulong? AFKChannelId { get; } /// - /// Gets the ID of the the default channel for this guild. + /// Gets the ID of the default channel for this guild. /// + /// + /// This property retrieves the snowflake identifier of the first viewable text channel for this guild. + /// + /// This channel does not guarantee the user can send message to it, as it only looks for the first viewable + /// text channel. + /// + /// + /// + /// A representing the snowflake identifier of the default text channel; 0 if + /// none can be found. + /// ulong DefaultChannelId { get; } /// - /// Gets the ID of the embed channel set in the widget settings of this guild, or null if none is set. + /// Gets the ID of the widget embed channel of this guild. /// + /// + /// A representing the snowflake identifier of the embedded channel found within the + /// widget settings of this guild; null if none is set. + /// ulong? EmbedChannelId { get; } /// - /// Gets the ID of the channel where randomized welcome messages are sent, or null if none is set. + /// Gets the ID of the channel where randomized welcome messages are sent. /// + /// + /// A representing the snowflake identifier of the system channel where randomized + /// welcome messages are sent; null if none is set. + /// ulong? SystemChannelId { get; } /// - /// Gets the ID of the user that created this guild. + /// Gets the ID of the user that owns this guild. /// + /// + /// A representing the snowflake identifier of the user that owns this guild. + /// ulong OwnerId { get; } /// /// Gets the ID of the region hosting this guild's voice channels. /// + /// + /// A string containing the identifier for the voice region that this guild uses (e.g. eu-central). + /// string VoiceRegionId { get; } /// - /// Gets the currently associated with this guild. + /// Gets the currently associated with this guild. /// /// - /// currently associated with this guild. + /// An currently associated with this guild. /// IAudioClient AudioClient { get; } /// /// Gets the built-in role containing all users in this guild. /// /// - /// Built-in role that represents an @everyone role in this guild. + /// A role object that represents an @everyone role in this guild. /// IRole EveryoneRole { get; } /// /// Gets a collection of all custom emotes for this guild. /// /// - /// A collection of all custom emotes for this guild. + /// A read-only collection of all custom emotes for this guild. /// IReadOnlyCollection Emotes { get; } /// /// Gets a collection of all extra features added to this guild. /// /// - /// A collection of enabled features in this guild. + /// A read-only collection of enabled features in this guild. /// IReadOnlyCollection Features { get; } /// /// Gets a collection of all roles in this guild. /// /// - /// A collection of roles found within this guild. + /// A read-only collection of roles found within this guild. /// IReadOnlyCollection Roles { get; } @@ -164,7 +189,7 @@ namespace Discord /// The delegate containing the properties to modify the guild with. /// The options to be used when sending the request. /// - /// An awaitable . + /// A task that represents the asynchronous modification operation. /// Task ModifyAsync(Action func, RequestOptions options = null); /// @@ -173,7 +198,7 @@ namespace Discord /// The delegate containing the properties to modify the guild widget with. /// The options to be used when sending the request. /// - /// An awaitable . + /// A task that represents the asynchronous modification operation. /// Task ModifyEmbedAsync(Action func, RequestOptions options = null); /// @@ -182,7 +207,7 @@ namespace Discord /// The properties used to modify the channel positions with. /// The options to be used when sending the request. /// - /// An awaitable . + /// A task that represents the asynchronous reorder operation. /// Task ReorderChannelsAsync(IEnumerable args, RequestOptions options = null); /// @@ -191,28 +216,32 @@ namespace Discord /// The properties used to modify the role positions with. /// The options to be used when sending the request. /// - /// An awaitable . + /// A task that represents the asynchronous reorder operation. /// Task ReorderRolesAsync(IEnumerable args, RequestOptions options = null); /// /// Leaves this guild. /// /// - /// This method will make the currently logged-in user leave the guild. If the user is the owner, use - /// instead. + /// This method will make the currently logged-in user leave the guild. + /// + /// If the user is the owner of this guild, use instead. + /// /// /// The options to be used when sending the request. /// - /// An awaitable . + /// A task that represents the asynchronous leave operation. /// Task LeaveAsync(RequestOptions options = null); /// - /// Gets a collection of all users banned on this guild. + /// Gets a collection of all users banned in this guild. /// /// The options to be used when sending the request. /// - /// An awaitable containing a collection of banned users with reasons. + /// A task that represents the asynchronous get operation. The task result contains a read-only collection of + /// ban objects that this guild currently possesses, with each object containing the user banned and reason + /// behind the ban. /// Task> GetBansAsync(RequestOptions options = null); /// @@ -221,8 +250,8 @@ namespace Discord /// The banned user. /// The options to be used when sending the request. /// - /// An awaitable containing the ban object, which contains the user information and the - /// reason for the ban; null if the ban entry cannot be found. + /// A task that represents the asynchronous get operation. The task result contains a ban object, which + /// contains the user information and the reason for the ban; null if the ban entry cannot be found. /// Task GetBanAsync(IUser user, RequestOptions options = null); /// @@ -231,216 +260,197 @@ namespace Discord /// The snowflake identifier for the banned user. /// The options to be used when sending the request. /// - /// An awaitable containing the ban object, which contains the user information and the - /// reason for the ban; null if the ban entry cannot be found. + /// A task that represents the asynchronous get operation. The task result contains a ban object, which + /// contains the user information and the reason for the ban; null if the ban entry cannot be found. /// Task GetBanAsync(ulong userId, RequestOptions options = null); /// /// Bans the user from this guild and optionally prunes their recent messages. /// /// The user to ban. - /// - /// The number of days to remove messages from this for - must be between [0, 7]. - /// + /// The number of days to remove messages from this user for, and this number 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. + /// is not between 0 to 7. /// - /// An awaitable . + /// A task that represents the asynchronous add operation for the ban. /// Task AddBanAsync(IUser user, int pruneDays = 0, string reason = null, RequestOptions options = null); /// /// Bans the user from this guild and optionally prunes their recent messages. /// /// The snowflake ID of the user to ban. - /// - /// The number of days to remove messages from this user for - must be between [0, 7]. - /// + /// The number of days to remove messages from this user for, and this number 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. + /// is not between 0 to 7. /// - /// An awaitable . + /// A task that represents the asynchronous add operation for the ban. /// Task AddBanAsync(ulong userId, int pruneDays = 0, string reason = null, RequestOptions options = null); /// - /// Unbans the provided user if they are currently banned. + /// Unbans the user if they are currently banned. /// /// The user to be unbanned. /// The options to be used when sending the request. /// - /// An awaitable . + /// A task that represents the asynchronous removal operation for the ban. /// Task RemoveBanAsync(IUser user, RequestOptions options = null); /// - /// Unbans the provided user ID if it is currently banned. + /// Unbans the user if they are currently banned. /// - /// The snowflake ID of the user to be unbanned. + /// The snowflake identifier of the user to be unbanned. /// The options to be used when sending the request. /// - /// An awaitable . + /// A task that represents the asynchronous removal operation for the ban. /// Task RemoveBanAsync(ulong userId, RequestOptions options = null); /// /// Gets a collection of all channels in this guild. /// - /// - /// The that determines whether the object should be fetched from cache. - /// + /// The that determines whether the object should be fetched from cache. /// The options to be used when sending the request. /// - /// An awaitable containing a collection of generic channels found within this guild. + /// A task that represents the asynchronous get operation. The task result contains a read-only collection of + /// generic channels found within this guild. /// Task> GetChannelsAsync(CacheMode mode = CacheMode.AllowDownload, RequestOptions options = null); /// - /// Gets the channel in this guild with the provided ID. + /// Gets a channel in this guild. /// - /// The channel ID. - /// - /// The that determines whether the object should be fetched from cache. - /// + /// The snowflake identifier for the channel. + /// The that determines whether the object should be fetched from cache. /// The options to be used when sending the request. /// - /// An awaitable containing the generic channel with the specified ID, or - /// null if none is found. + /// A task that represents the asynchronous get operation. The task result contains the generic channel + /// associated with the specified ; null if none is found. /// Task GetChannelAsync(ulong id, CacheMode mode = CacheMode.AllowDownload, RequestOptions options = null); /// /// Gets a collection of all text channels in this guild. /// - /// - /// The that determines whether the object should be fetched from cache. - /// + /// The that determines whether the object should be fetched from cache. /// The options to be used when sending the request. /// - /// An awaitable containing a collection of text channels found within this guild. + /// A task that represents the asynchronous get operation. The task result contains a read-only collection of + /// message channels found within this guild. /// Task> GetTextChannelsAsync(CacheMode mode = CacheMode.AllowDownload, RequestOptions options = null); /// - /// Gets a text channel in this guild with the provided ID, or null if not found. + /// Gets a text channel in this guild. /// - /// The text channel ID. - /// - /// The that determines whether the object should be fetched from cache. - /// + /// The snowflake identifier for the text channel. + /// The that determines whether the object should be fetched from cache. /// The options to be used when sending the request. /// - /// An awaitable containing the text channel with the specified ID, or - /// null if none is found. + /// A task that represents the asynchronous get operation. The task result contains the text channel + /// associated with the specified ; null if none is found. /// Task GetTextChannelAsync(ulong id, CacheMode mode = CacheMode.AllowDownload, RequestOptions options = null); /// /// Gets a collection of all voice channels in this guild. /// - /// - /// The that determines whether the object should be fetched from cache. - /// + /// The that determines whether the object should be fetched from cache. /// The options to be used when sending the request. /// - /// An awaitable containing a collection of voice channels found within this guild. + /// A task that represents the asynchronous get operation. The task result contains a read-only collection of + /// voice channels found within this guild. /// Task> GetVoiceChannelsAsync(CacheMode mode = CacheMode.AllowDownload, RequestOptions options = null); /// /// Gets a collection of all category channels in this guild. /// - /// - /// The that determines whether the object should be fetched from cache. - /// + /// The that determines whether the object should be fetched from cache. /// The options to be used when sending the request. /// - /// An awaitable containing a collection of category channels found within this guild. + /// A task that represents the asynchronous get operation. The task result contains a read-only collection of + /// category channels found within this guild. /// Task> GetCategoriesAsync(CacheMode mode = CacheMode.AllowDownload, RequestOptions options = null); /// - /// Gets the voice channel in this guild with the provided ID. + /// Gets a voice channel in this guild. /// - /// The text channel ID. - /// - /// The that determines whether the object should be fetched from cache. - /// + /// The snowflake identifier for the voice channel. + /// The that determines whether the object should be fetched from cache. /// The options to be used when sending the request. /// - /// An awaitable containing the voice channel with the specified ID, or - /// null if none is found. + /// A task that represents the asynchronous get operation. The task result contains the voice channel associated + /// with the specified ; null if none is found. /// Task GetVoiceChannelAsync(ulong id, CacheMode mode = CacheMode.AllowDownload, RequestOptions options = null); /// /// Gets the AFK voice channel in this guild. /// - /// - /// The that determines whether the object should be fetched from cache. - /// + /// The that determines whether the object should be fetched from cache. /// The options to be used when sending the request. /// - /// An awaitable containing the AFK voice channel set within this guild, or - /// null if none is set. + /// A task that represents the asynchronous get operation. The task result contains the voice channel that the + /// AFK users will be moved to after they have idled for too long; null if none is set. /// Task GetAFKChannelAsync(CacheMode mode = CacheMode.AllowDownload, RequestOptions options = null); /// - /// Gets the default system text channel in this guild with the provided ID. + /// Gets the system channel where randomized welcome messages are sent in this guild. /// - /// - /// The that determines whether the object should be fetched from cache. - /// + /// The that determines whether the object should be fetched from cache. /// The options to be used when sending the request. /// - /// An awaitable containing the system channel within this guild, or - /// null if none is set. + /// A task that represents the asynchronous get operation. The task result contains the text channel where + /// randomized welcome messages will be sent to; null if none is set. /// Task GetSystemChannelAsync(CacheMode mode = CacheMode.AllowDownload, RequestOptions options = null); /// - /// Gets the top viewable text channel in this guild with the provided ID. + /// Gets the first viewable text channel in this guild. /// - /// - /// The that determines whether the object should be fetched from cache. - /// + /// The that determines whether the object should be fetched from cache. /// The options to be used when sending the request. /// - /// An awaitable containing the first viewable text channel in this guild, or - /// null if none is found. + /// A task that represents the asynchronous get operation. The task result contains the first viewable text + /// channel in this guild; null if none is found. /// Task GetDefaultChannelAsync(CacheMode mode = CacheMode.AllowDownload, RequestOptions options = null); /// /// Gets the embed channel (i.e. the channel set in the guild's widget settings) in this guild. /// - /// - /// The that determines whether the object should be fetched from cache. - /// + /// The that determines whether the object should be fetched from cache. /// The options to be used when sending the request. /// - /// An awaitable containing the embed channel set within the server's widget settings, or - /// null if none is set. + /// A task that represents the asynchronous get operation. The task result contains the embed channel set + /// within the server's widget settings; null if none is set. /// Task GetEmbedChannelAsync(CacheMode mode = CacheMode.AllowDownload, RequestOptions options = null); /// - /// Creates a new text channel. + /// Creates a new text channel in this guild. /// /// The new name for the text channel. /// The delegate containing the properties to be applied to the channel upon its creation. /// The options to be used when sending the request. /// - /// An awaitable containing the newly created text channel. + /// A task that represents the asynchronous creation operation. The task result contains the newly created + /// text channel. /// Task CreateTextChannelAsync(string name, Action func = null, RequestOptions options = null); /// - /// Creates a new voice channel. + /// Creates a new voice channel in this guild. /// /// The new name for the voice channel. /// The delegate containing the properties to be applied to the channel upon its creation. /// The options to be used when sending the request. /// - /// An awaitable containing the newly created voice channel. + /// A task that represents the asynchronous creation operation. The task result contains the newly created + /// voice channel. /// Task CreateVoiceChannelAsync(string name, Action func = null, RequestOptions options = null); /// - /// Creates a new channel category. + /// Creates a new channel category in this guild. /// /// The new name for the category. /// The options to be used when sending the request. /// - /// An awaitable containing the newly created category channel. + /// A task that represents the asynchronous creation operation. The task result contains the newly created + /// category channel. /// Task CreateCategoryAsync(string name, RequestOptions options = null); @@ -448,11 +458,12 @@ namespace Discord Task CreateIntegrationAsync(ulong id, string type, RequestOptions options = null); /// - /// Gets a collection of all invites to this guild. + /// Gets a collection of all invites in this guild. /// /// The options to be used when sending the request. /// - /// An awaitable containing a collection of invites found within this guild. + /// A task that represents the asynchronous get operation. The task result contains a read-only collection of + /// invite metadata, each representing information for an invite found within this guild. /// Task> GetInvitesAsync(RequestOptions options = null); /// @@ -460,17 +471,17 @@ namespace Discord /// /// The options to be used when sending the request. /// - /// An awaitable containing the partial metadata of the vanity invite found within - /// this guild. + /// A task that represents the asynchronous get operation. The task result contains the partial metadata of + /// the vanity invite found within this guild; null if none is found. /// Task GetVanityInviteAsync(RequestOptions options = null); /// /// Gets a role in this guild. /// - /// The role ID. + /// The snowflake identifier for the role. /// - /// A role that matches the provided snowflake identifier; null if none is found. + /// A role that is associated with the specified ; null if none is found. /// IRole GetRole(ulong id); /// @@ -482,7 +493,8 @@ namespace Discord /// Whether the role is separated from others on the sidebar. /// The options to be used when sending the request. /// - /// An awaitable containing the newly crated role. + /// A task that represents the asynchronous creation operation. The task result contains the newly created + /// role. /// Task CreateRoleAsync(string name, GuildPermissions? permissions = null, Color? color = null, bool isHoisted = false, RequestOptions options = null); @@ -492,27 +504,33 @@ namespace Discord /// /// This method retrieves all users found within this guild. /// - /// This may return an incomplete list on the WebSocket implementation. + /// This may return an incomplete collection in the WebSocket implementation due to how Discord does not + /// send a complete user list for large guilds. /// /// - /// - /// The that determines whether the object should be fetched from cache. - /// + /// The that determines whether the object should be fetched from cache. /// The options to be used when sending the request. /// - /// An awaitable containing a collection of users found within this guild. + /// A task that represents the asynchronous get operation. The task result contains a collection of guild + /// users found within this guild. /// Task> GetUsersAsync(CacheMode mode = CacheMode.AllowDownload, RequestOptions options = null); /// - /// Gets a user found in this guild. + /// Gets a user from this guild. /// - /// The user ID to search for. - /// The that determines whether the object should be fetched from - /// cache. + /// + /// This method retrieves a user found within this guild. + /// + /// This may return null in the WebSocket implementation due to incomplete user collection in + /// large guilds. + /// + /// + /// The snowflake identifier of the user. + /// The that determines whether the object should be fetched from cache. /// The options to be used when sending the request. /// - /// An awaitable containing the guild user with the specified ID; null if none is - /// found. + /// A task that represents the asynchronous get operation. The task result contains the guild user + /// associated with the specified ; null if none is found. /// Task GetUserAsync(ulong id, CacheMode mode = CacheMode.AllowDownload, RequestOptions options = null); /// @@ -521,7 +539,8 @@ namespace Discord /// The that determines whether the object should be fetched from cache. /// The options to be used when sending the request. /// - /// An awaitable containing the currently logged-in user within this guild. + /// A task that represents the asynchronous get operation. The task result contains the currently logged-in + /// user within this guild. /// Task GetCurrentUserAsync(CacheMode mode = CacheMode.AllowDownload, RequestOptions options = null); /// @@ -530,29 +549,34 @@ namespace Discord /// The that determines whether the object should be fetched from cache. /// The options to be used when sending the request. /// - /// An awaitable containing the owner of this guild. + /// A task that represents the asynchronous get operation. The task result contains the owner of this guild. /// Task GetOwnerAsync(CacheMode mode = CacheMode.AllowDownload, RequestOptions options = null); /// /// Downloads all users for this guild if the current list is incomplete. /// /// - /// An awaitable . + /// A task that represents the asynchronous download operation. /// Task DownloadUsersAsync(); /// /// Prunes inactive users. /// /// - /// This method removes all users that have not logged on in the provided number of days or, if - /// is true, returns the number of users that would be removed. + /// + /// This method removes all users that have not logged on in the provided number of . + /// + /// + /// If is true, this method will only return the number of users that + /// would be removed without kicking the users. + /// /// /// The number of days required for the users to be kicked. /// Whether this prune action is a simulation. /// The options to be used when sending the request. /// - /// An awaitable containing the number of users to be or has been removed from this - /// guild. + /// A task that represents the asynchronous prune operation. The task result contains the number of users to + /// be or has been removed from this guild. /// Task PruneUsersAsync(int days = 30, bool simulate = false, RequestOptions options = null); @@ -560,12 +584,11 @@ namespace Discord /// Gets the specified number of audit log entries for this guild. /// /// The number of audit log entries to fetch. - /// - /// The that determines whether the object should be fetched from cache. - /// + /// The that determines whether the object should be fetched from cache. /// The options to be used when sending the request. /// - /// An awaitable containing a collection of requested audit log entries. + /// A task that represents the asynchronous get operation. The task result contains a read-only collection + /// of the requested audit log entries. /// Task> GetAuditLogAsync(int limit = DiscordConfig.MaxAuditLogEntriesPerBatch, CacheMode mode = CacheMode.AllowDownload, RequestOptions options = null); @@ -573,11 +596,11 @@ namespace Discord /// /// Gets a webhook found within this guild. /// - /// The webhook ID. + /// The identifier for the webhook. /// The options to be used when sending the request. /// - /// An awaitable containing the webhook with the specified ID; null if none is - /// found. + /// A task that represents the asynchronous get operation. The task result contains the webhook with the + /// specified ; null if none is found. /// Task GetWebhookAsync(ulong id, RequestOptions options = null); /// @@ -585,18 +608,19 @@ namespace Discord /// /// The options to be used when sending the request. /// - /// An awaitable containing a collection of webhooks found within the guild. + /// A task that represents the asynchronous get operation. The task result contains a read-only collection + /// of webhooks found within the guild. /// Task> GetWebhooksAsync(RequestOptions options = null); /// /// Gets a specific emote from this guild. /// - /// The guild emote ID. + /// The snowflake identifier for the guild emote. /// The options to be used when sending the request. /// - /// An awaitable containing the emote found with the specified ID; null if none is - /// found. + /// A task that represents the asynchronous get operation. The task result contains the emote found with the + /// specified ; null if none is found. /// Task GetEmoteAsync(ulong id, RequestOptions options = null); /// @@ -607,7 +631,7 @@ namespace Discord /// The roles to limit the emote usage to. /// The options to be used when sending the request. /// - /// An awaitable containing the created emote. + /// A task that represents the asynchronous creation operation. The task result contains the created emote. /// Task CreateEmoteAsync(string name, Image image, Optional> roles = default(Optional>), RequestOptions options = null); @@ -618,7 +642,8 @@ namespace Discord /// The delegate containing the properties to modify the emote with. /// The options to be used when sending the request. /// - /// An awaitable containing the newly modified emote. + /// A task that represents the asynchronous modification operation. The task result contains the modified + /// emote. /// Task ModifyEmoteAsync(GuildEmote emote, Action func, RequestOptions options = null); /// @@ -627,7 +652,7 @@ namespace Discord /// The emote to delete. /// The options to be used when sending the request. /// - /// An awaitable . + /// A task that represents the asynchronous removal operation. /// Task DeleteEmoteAsync(GuildEmote emote, RequestOptions options = null); } diff --git a/src/Discord.Net.Core/Entities/Permissions/GuildPermissions.cs b/src/Discord.Net.Core/Entities/Permissions/GuildPermissions.cs index 9ad7d34b4..bac14a5c8 100644 --- a/src/Discord.Net.Core/Entities/Permissions/GuildPermissions.cs +++ b/src/Discord.Net.Core/Entities/Permissions/GuildPermissions.cs @@ -148,7 +148,7 @@ namespace Discord RawValue = value; } - /// Creates a new with the provided permissions. + /// Creates a new structure with the provided permissions. public GuildPermissions( bool createInstantInvite = false, bool kickMembers = false, diff --git a/src/Discord.Net.Core/Entities/Roles/Color.cs b/src/Discord.Net.Core/Entities/Roles/Color.cs index b3de6d5ff..a8917ec07 100644 --- a/src/Discord.Net.Core/Entities/Roles/Color.cs +++ b/src/Discord.Net.Core/Entities/Roles/Color.cs @@ -18,61 +18,60 @@ namespace Discord /// A color class with the hex value of 1ABC9C. public static readonly Color Teal = new Color(0x1ABC9C); /// Gets the dark teal color value. - /// A color class with the hex value of 11806A. public static readonly Color DarkTeal = new Color(0x11806A); /// Gets the green color value. - /// A color class with the hex value of 2ECC71. + /// A color class with the hex value of 11806A. public static readonly Color Green = new Color(0x2ECC71); /// Gets the dark green color value. - /// A color class with the hex value of 1F8B4C. + /// A color class with the hex value of 2ECC71. public static readonly Color DarkGreen = new Color(0x1F8B4C); /// Gets the blue color value. - /// A color class with the hex value of 3498DB. + /// A color class with the hex value of 1F8B4C. public static readonly Color Blue = new Color(0x3498DB); /// Gets the dark blue color value. - /// A color class with the hex value of 206694. + /// A color class with the hex value of 3498DB. public static readonly Color DarkBlue = new Color(0x206694); /// Gets the purple color value. - /// A color class with the hex value of 9B59B6. + /// A color class with the hex value of 206694. public static readonly Color Purple = new Color(0x9B59B6); /// Gets the dark purple color value. - /// A color class with the hex value of 71368A. + /// A color class with the hex value of 9B59B6. public static readonly Color DarkPurple = new Color(0x71368A); /// Gets the magenta color value. - /// A color class with the hex value of E91E63. + /// A color class with the hex value of 71368A. public static readonly Color Magenta = new Color(0xE91E63); /// Gets the dark magenta color value. - /// A color class with the hex value of AD1457. + /// A color class with the hex value of E91E63. public static readonly Color DarkMagenta = new Color(0xAD1457); /// Gets the gold color value. - /// A color class with the hex value of F1C40F. + /// A color class with the hex value of AD1457. public static readonly Color Gold = new Color(0xF1C40F); /// Gets the light orange color value. - /// A color class with the hex value of C27C0E. + /// A color class with the hex value of F1C40F. public static readonly Color LightOrange = new Color(0xC27C0E); /// Gets the orange color value. - /// A color class with the hex value of E67E22. + /// A color class with the hex value of C27C0E. public static readonly Color Orange = new Color(0xE67E22); /// Gets the dark orange color value. - /// A color class with the hex value of A84300. + /// A color class with the hex value of E67E22. public static readonly Color DarkOrange = new Color(0xA84300); /// Gets the red color value. - /// A color class with the hex value of E74C3C. + /// A color class with the hex value of A84300. public static readonly Color Red = new Color(0xE74C3C); /// Gets the dark red color value. - /// A color class with the hex value of 992D22. - public static readonly Color DarkRed = new Color(0x992D22); + /// A color class with the hex value of E74C3C. + public static readonly Color DarkRed = new Color(0x992D22); /// Gets the light grey color value. - /// A color class with the hex value of 979C9F. + /// A color class with the hex value of 992D22. public static readonly Color LightGrey = new Color(0x979C9F); /// Gets the lighter grey color value. - /// A color class with the hex value of 95A5A6. + /// A color class with the hex value of 979C9F. public static readonly Color LighterGrey = new Color(0x95A5A6); /// Gets the dark grey color value. - /// A color class with the hex value of 607D8B. + /// A color class with the hex value of 95A5A6. public static readonly Color DarkGrey = new Color(0x607D8B); /// Gets the darker grey color value. - /// A color class with the hex value of 546E7A. + /// A color class with the hex value of 607D8B. public static readonly Color DarkerGrey = new Color(0x546E7A); /// Gets the encoded value for this color. diff --git a/src/Discord.Net.Core/Entities/Roles/ReorderRoleProperties.cs b/src/Discord.Net.Core/Entities/Roles/ReorderRoleProperties.cs index 6c6c1ebc9..0074c0a3b 100644 --- a/src/Discord.Net.Core/Entities/Roles/ReorderRoleProperties.cs +++ b/src/Discord.Net.Core/Entities/Roles/ReorderRoleProperties.cs @@ -16,7 +16,7 @@ namespace Discord /// Gets the new zero-based position of the role. /// /// - /// A representing the new zero-based position of the role. + /// An representing the new zero-based position of the role. /// public int Position { get; } diff --git a/src/Discord.Net.Core/Entities/Users/IGuildUser.cs b/src/Discord.Net.Core/Entities/Users/IGuildUser.cs index 4d54a49c4..633056733 100644 --- a/src/Discord.Net.Core/Entities/Users/IGuildUser.cs +++ b/src/Discord.Net.Core/Entities/Users/IGuildUser.cs @@ -10,36 +10,60 @@ namespace Discord public interface IGuildUser : IUser, IVoiceState { /// - /// Gets when this user joined this guild. + /// Gets when this user joined the guild. /// + /// + /// A representing the time of which the user has joined the guild; + /// null when it cannot be obtained. + /// DateTimeOffset? JoinedAt { get; } /// /// Gets the nickname for this user. /// + /// + /// A string representing the nickname of the user; null if none is set. + /// string Nickname { get; } /// /// Gets the guild-level permissions for this user. /// + /// + /// A structure for this user, representing what + /// permissions this user has in the guild. + /// GuildPermissions GuildPermissions { get; } /// /// Gets the guild for this user. /// + /// + /// A guild object that this user belongs to. + /// IGuild Guild { get; } /// /// Gets the ID of the guild for this user. /// + /// + /// An representing the snowflake identifier of the guild that this user belongs to. + /// ulong GuildId { get; } /// - /// Returns a collection of the ids of the roles this user is a member of in this guild, including the - /// guild's @everyone role. + /// Gets a collection of IDs for the roles that this user currently possesses in the guild. /// + /// + /// A read-only collection of , each representing a snowflake identifier for a role that + /// this user posesses. + /// IReadOnlyCollection RoleIds { get; } /// /// Gets the level permissions granted to this user to a given channel. /// /// The channel to get the permission from. + /// + /// A structure representing the permissions that a user has in the + /// specified channel. + /// ChannelPermissions GetPermissions(IGuildChannel channel); /// @@ -47,37 +71,56 @@ namespace Discord /// /// The reason for the kick which will be recorded in the audit log. /// The options to be used when sending the request. + /// + /// A task that represents the asynchronous kick operation. + /// Task KickAsync(string reason = null, RequestOptions options = null); /// /// Modifies this user's properties in this guild. /// - /// The properties to modify the user with. + /// The delegate containing the properties to modify the user with. /// The options to be used when sending the request. + /// + /// A task that represents the asynchronous modification operation. + /// + /// Task ModifyAsync(Action func, RequestOptions options = null); /// - /// Adds a to this user in this guild. + /// Adds the specified to this user in this guild. /// /// The role to be added to the user. /// The options to be used when sending the request. + /// + /// A task that represents the asynchronous role addition operation. + /// Task AddRoleAsync(IRole role, RequestOptions options = null); /// - /// Adds to this user in this guild. + /// Adds the specified to this user in this guild. /// /// The roles to be added to the user. /// The options to be used when sending the request. + /// + /// A task that represents the asynchronous role addition operation. + /// Task AddRolesAsync(IEnumerable roles, RequestOptions options = null); /// - /// Removes a from this user in this guild. + /// Removes the specified from this user in this guild. /// /// The role to be removed from the user. /// The options to be used when sending the request. + /// + /// A task that represents the asynchronous role removal operation. + /// Task RemoveRoleAsync(IRole role, RequestOptions options = null); /// - /// Removes from this user in this guild. + /// Removes the specified from this user in this guild. /// /// The roles to be removed from the user. /// The options to be used when sending the request. + /// + /// A task that represents the asynchronous role removal operation. + /// Task RemoveRolesAsync(IEnumerable roles, RequestOptions options = null); } } diff --git a/src/Discord.Net.Core/Entities/Users/ISelfUser.cs b/src/Discord.Net.Core/Entities/Users/ISelfUser.cs index 1ead0cbba..c1d7874eb 100644 --- a/src/Discord.Net.Core/Entities/Users/ISelfUser.cs +++ b/src/Discord.Net.Core/Entities/Users/ISelfUser.cs @@ -13,12 +13,18 @@ namespace Discord /// string Email { get; } /// - /// Returns true if this user's email has been verified. + /// Indicates whether or not this user has their email verified. /// + /// + /// true if this user's email has been verified; false if not. + /// bool IsVerified { get; } /// - /// Returns true if this user has enabled MFA on their account. + /// Indicates whether or not this user has MFA enabled on their account. /// + /// + /// true if this user has enabled multi-factor authentication on their account; false if not. + /// bool IsMfaEnabled { get; } /// diff --git a/src/Discord.Net.Core/Net/RateLimitedException.cs b/src/Discord.Net.Core/Net/RateLimitedException.cs index 6e084886e..c19487fad 100644 --- a/src/Discord.Net.Core/Net/RateLimitedException.cs +++ b/src/Discord.Net.Core/Net/RateLimitedException.cs @@ -3,7 +3,7 @@ using System; namespace Discord.Net { /// - /// Describes an exception that indicates the user is being rate limited by Discord. + /// The exception that is thrown when the user is being rate limited by Discord. /// public class RateLimitedException : TimeoutException { diff --git a/src/Discord.Net.Rest/Entities/Channels/RestTextChannel.cs b/src/Discord.Net.Rest/Entities/Channels/RestTextChannel.cs index 2a9000f16..f1a282dc9 100644 --- a/src/Discord.Net.Rest/Entities/Channels/RestTextChannel.cs +++ b/src/Discord.Net.Rest/Entities/Channels/RestTextChannel.cs @@ -16,14 +16,13 @@ namespace Discord.Rest { /// public string Topic { get; private set; } + /// public ulong? CategoryId { get; private set; } /// public string Mention => MentionUtils.MentionChannel(Id); - - private bool _nsfw; /// - public bool IsNsfw => _nsfw; + public bool IsNsfw { get; private set; } internal RestTextChannel(BaseDiscordClient discord, IGuild guild, ulong id) : base(discord, guild, id) @@ -40,7 +39,7 @@ namespace Discord.Rest base.Update(model); CategoryId = model.CategoryId; Topic = model.Topic.Value; - _nsfw = model.Nsfw.GetValueOrDefault(); + IsNsfw = model.Nsfw.GetValueOrDefault(); } /// @@ -239,6 +238,7 @@ namespace Discord.Rest } // INestedChannel + /// async Task INestedChannel.GetCategoryAsync(CacheMode mode, RequestOptions options) { if (CategoryId.HasValue && mode == CacheMode.AllowDownload) diff --git a/src/Discord.Net.Rest/Entities/Channels/RestVoiceChannel.cs b/src/Discord.Net.Rest/Entities/Channels/RestVoiceChannel.cs index f54013950..a2b086258 100644 --- a/src/Discord.Net.Rest/Entities/Channels/RestVoiceChannel.cs +++ b/src/Discord.Net.Rest/Entities/Channels/RestVoiceChannel.cs @@ -18,6 +18,7 @@ namespace Discord.Rest public int Bitrate { get; private set; } /// public int? UserLimit { get; private set; } + /// public ulong? CategoryId { get; private set; } internal RestVoiceChannel(BaseDiscordClient discord, IGuild guild, ulong id) diff --git a/src/Discord.Net.Rest/Entities/Messages/RestSystemMessage.cs b/src/Discord.Net.Rest/Entities/Messages/RestSystemMessage.cs index b9dda08ae..4d61f8638 100644 --- a/src/Discord.Net.Rest/Entities/Messages/RestSystemMessage.cs +++ b/src/Discord.Net.Rest/Entities/Messages/RestSystemMessage.cs @@ -1,4 +1,4 @@ -using System.Diagnostics; +using System.Diagnostics; using Model = Discord.API.Message; namespace Discord.Rest @@ -6,6 +6,7 @@ namespace Discord.Rest [DebuggerDisplay(@"{DebuggerDisplay,nq}")] public class RestSystemMessage : RestMessage, ISystemMessage { + /// public MessageType Type { get; private set; } internal RestSystemMessage(BaseDiscordClient discord, ulong id, IMessageChannel channel, IUser author) diff --git a/src/Discord.Net.WebSocket/Entities/Guilds/SocketGuild.cs b/src/Discord.Net.WebSocket/Entities/Guilds/SocketGuild.cs index 302935b80..2c618f375 100644 --- a/src/Discord.Net.WebSocket/Entities/Guilds/SocketGuild.cs +++ b/src/Discord.Net.WebSocket/Entities/Guilds/SocketGuild.cs @@ -54,8 +54,14 @@ namespace Discord.WebSocket /// Gets the number of members. /// /// - /// This property retrieves the number of members returned by Discord and is the most accurate. You may see - /// discrepancy between the collection and this property. + /// This property retrieves the number of members returned by Discord. + /// + /// Due to how this property is returned by Discord instead of relying on the WebSocket cache, the + /// number here is the most accurate in terms of counting the number of users within this guild. Use + /// this instead of enumerating the count of the + /// collection, as you may see discrepancy between the count of + /// collection and this property. + /// /// public int MemberCount { get; internal set; } /// Gets the number of members downloaded to the local guild cache. @@ -95,12 +101,18 @@ namespace Discord.WebSocket /// public IAudioClient AudioClient => _audioClient; /// - /// Gets the first viewable text channel. + /// Gets the default channel in this guild. /// /// - /// This method gets the first viewable text channel for the logged-in user. This property does not - /// guarantee the user can send message to it. + /// This property retrieves the first viewable text channel for this guild. + /// + /// This channel does not guarantee the user can send message to it, as it only looks for the first viewable + /// text channel. + /// /// + /// + /// A representing the first viewable channel that the user has access to. + /// public SocketTextChannel DefaultChannel => TextChannels .Where(c => CurrentUser.GetPermissions(c).ViewChannel) .OrderBy(c => c.Position) @@ -109,7 +121,8 @@ namespace Discord.WebSocket /// Gets the AFK voice channel in this guild. /// /// - /// A voice channel set within this guild that AFK users get moved to; otherwise null if none is set. + /// A that the AFK users will be moved to after they have idled for too + /// long; null if none is set. /// public SocketVoiceChannel AFKChannel { @@ -120,10 +133,10 @@ namespace Discord.WebSocket } } /// - /// Gets the embed channel set in the widget settings of this guild. + /// Gets the embed channel (i.e. the channel set in the guild's widget settings) in this guild. /// /// - /// A channel set in the widget settings of this guild; otherwise null if none is set. + /// A channel set within the server's widget settings; null if none is set. /// public SocketGuildChannel EmbedChannel { @@ -134,11 +147,10 @@ namespace Discord.WebSocket } } /// - /// Gets the channel where randomized welcome messages are sent. + /// Gets the system channel where randomized welcome messages are sent in this guild. /// /// - /// A channel where randomized welcome messages are sent in this guild; otherwise null if none is - /// set. + /// A text channel where randomized welcome messages will be sent to; null if none is set. /// public SocketTextChannel SystemChannel { @@ -149,21 +161,27 @@ namespace Discord.WebSocket } } /// - /// Gets a collection of text channels present in this guild. + /// Gets a collection of all text channels in this guild. /// /// - /// A collection of text channels in this guild. + /// A read-only collection of message channels found within this guild. /// public IReadOnlyCollection TextChannels => Channels.Select(x => x as SocketTextChannel).Where(x => x != null).ToImmutableArray(); /// - /// Gets a collection of voice channels present in this guild. + /// Gets a collection of all voice channels in this guild. /// + /// + /// A read-only collection of voice channels found within this guild. + /// public IReadOnlyCollection VoiceChannels => Channels.Select(x => x as SocketVoiceChannel).Where(x => x != null).ToImmutableArray(); /// - /// Gets a collection of category channels present in this guild. + /// Gets a collection of all category channels in this guild. /// + /// + /// A read-only collection of category channels found within this guild. + /// public IReadOnlyCollection CategoryChannels => Channels.Select(x => x as SocketCategoryChannel).Where(x => x != null).ToImmutableArray(); /// @@ -171,14 +189,17 @@ namespace Discord.WebSocket /// public SocketGuildUser CurrentUser => _members.TryGetValue(Discord.CurrentUser.Id, out SocketGuildUser member) ? member : null; /// - /// Gets the @everyone role in this guild. + /// Gets the built-in role containing all users in this guild. /// + /// + /// A role object that represents an @everyone role in this guild. + /// public SocketRole EveryoneRole => GetRole(Id); /// - /// Gets a collection of channels present in this guild. + /// Gets a collection of all channels in this guild. /// /// - /// Collection of channels. + /// A read-only collection of generic channels found within this guild. /// public IReadOnlyCollection Channels { @@ -189,37 +210,31 @@ namespace Discord.WebSocket return channels.Select(x => state.GetChannel(x) as SocketGuildChannel).Where(x => x != null).ToReadOnlyCollection(channels); } } - /// - /// Gets a collection of emotes created in this guild. - /// - /// - /// Collection of emotes. - /// + /// public IReadOnlyCollection Emotes => _emotes; - /// - /// Gets a collection of features enabled in this guild. - /// - /// - /// Collection of features in string. - /// + /// public IReadOnlyCollection Features => _features; /// /// Gets a collection of users in this guild. /// /// - /// This property may not always return all the members for large guilds (i.e. guilds containing 100+ users). - /// You may need to enable to fetch the full user list - /// upon startup, or use to manually download the users. + /// This property retrieves all users found within this guild. + /// + /// This property may not always return all the members for large guilds (i.e. guilds containing 100+ users). + /// If you are simply looking to get the number of users present in this guild, consider instead. + /// Otherwise, you may need to enable to fetch the full user list + /// upon startup, or use to manually download the users. + /// /// /// - /// Collection of users. + /// A collection of guild users found within this guild. /// public IReadOnlyCollection Users => _members.ToReadOnlyCollection(); /// - /// Gets a collection of roles in this guild. + /// Gets a collection of all roles in this guild. /// /// - /// Collection of roles. + /// A read-only collection of roles found within this guild. /// public IReadOnlyCollection Roles => _roles.ToReadOnlyCollection(); @@ -407,11 +422,13 @@ namespace Discord.WebSocket //Bans /// - /// Returns a collection of the banned users in this guild. + /// Gets a collection of all users banned in this guild. /// /// The options to be used when sending the request. /// - /// A collection of bans. + /// A task that represents the asynchronous get operation. The task result contains a read-only collection of + /// ban objects that this guild currently possesses, with each object containing the user banned and reason + /// behind the ban. /// public Task> GetBansAsync(RequestOptions options = null) => GuildHelper.GetBansAsync(this, Discord, options); @@ -421,8 +438,8 @@ namespace Discord.WebSocket /// The banned user. /// The options to be used when sending the request. /// - /// An awaitable containing a REST-based ban object, which contains the user information - /// and the reason for the ban; null if the ban entry cannot be found. + /// A task that represents the asynchronous get operation. The task result contains a ban object, which + /// contains the user information and the reason for the ban; null if the ban entry cannot be found. /// public Task GetBanAsync(IUser user, RequestOptions options = null) => GuildHelper.GetBanAsync(this, Discord, user.Id, options); @@ -432,8 +449,8 @@ namespace Discord.WebSocket /// The snowflake identifier for the banned user. /// The options to be used when sending the request. /// - /// An awaitable containing a REST-based ban object, which contains the user information - /// and the reason for the ban; null if the ban entry cannot be found. + /// A task that represents the asynchronous get operation. The task result contains a ban object, which + /// contains the user information and the reason for the ban; null if the ban entry cannot be found. /// public Task GetBanAsync(ulong userId, RequestOptions options = null) => GuildHelper.GetBanAsync(this, Discord, userId, options); @@ -454,11 +471,11 @@ namespace Discord.WebSocket //Channels /// - /// Returns a guild channel with the provided ID. + /// Gets a channel in this guild. /// - /// The channel ID. + /// The snowflake identifier for the channel. /// - /// The guild channel associated with the ID. + /// A generic channel associated with the specified ; null if none is found. /// public SocketGuildChannel GetChannel(ulong id) { @@ -468,56 +485,59 @@ namespace Discord.WebSocket return null; } /// - /// Returns a text channel with the provided ID. + /// Gets a text channel in this guild. /// - /// The channel ID. + /// The snowflake identifier for the text channel. /// - /// The text channel associated with the ID. + /// A text channel associated with the specified ; null if none is found. /// public SocketTextChannel GetTextChannel(ulong id) => GetChannel(id) as SocketTextChannel; /// - /// Returns a voice channel with the provided ID. + /// Gets a voice channel in this guild. /// - /// The channel ID. + /// The snowflake identifier for the voice channel. /// - /// The voice channel associated with the ID. + /// A voice channel associated with the specified ; null if none is found. /// public SocketVoiceChannel GetVoiceChannel(ulong id) => GetChannel(id) as SocketVoiceChannel; /// - /// Creates a text channel with the provided name. + /// Creates a new text channel in this guild. /// - /// The name of the new channel. - /// The options to be used when sending the request. + /// The new name for the text channel. /// The delegate containing the properties to be applied to the channel upon its creation. - /// is null. + /// The options to be used when sending the request. + /// is null. /// - /// The created text channel. + /// A task that represents the asynchronous creation operation. The task result contains the newly created + /// text channel. /// public Task CreateTextChannelAsync(string name, Action func = null, RequestOptions options = null) => GuildHelper.CreateTextChannelAsync(this, Discord, name, options, func); /// - /// Creates a voice channel with the provided name. + /// Creates a new voice channel in this guild. /// - /// The name of the new channel. + /// The new name for the voice channel. /// The delegate containing the properties to be applied to the channel upon its creation. /// The options to be used when sending the request. - /// is null. + /// is null. /// - /// The created voice channel. + /// A task that represents the asynchronous creation operation. The task result contains the newly created + /// voice channel. /// public Task CreateVoiceChannelAsync(string name, Action func = null, RequestOptions options = null) => GuildHelper.CreateVoiceChannelAsync(this, Discord, name, options, func); /// - /// Creates a category channel with the provided name. + /// Creates a new channel category in this guild. /// - /// The name of the new channel. + /// The new name for the category. /// The options to be used when sending the request. - /// is null. + /// is null. /// - /// The created category channel. + /// A task that represents the asynchronous creation operation. The task result contains the newly created + /// category channel. /// public Task CreateCategoryChannelAsync(string name, RequestOptions options = null) => GuildHelper.CreateCategoryChannelAsync(this, Discord, name, options); @@ -544,11 +564,12 @@ namespace Discord.WebSocket //Invites /// - /// Returns a collection of invites associated with this channel. + /// Gets a collection of all invites in this guild. /// /// The options to be used when sending the request. /// - /// An awaitable containing a collection of invites. + /// A task that represents the asynchronous get operation. The task result contains a read-only collection of + /// invite metadata, each representing information for an invite found within this guild. /// public Task> GetInvitesAsync(RequestOptions options = null) => GuildHelper.GetInvitesAsync(this, Discord, options); @@ -557,18 +578,19 @@ namespace Discord.WebSocket /// /// The options to be used when sending the request. /// - /// A partial metadata of the vanity invite found within this guild. + /// A task that represents the asynchronous get operation. The task result contains the partial metadata of + /// the vanity invite found within this guild; null if none is found. /// public Task GetVanityInviteAsync(RequestOptions options = null) => GuildHelper.GetVanityInviteAsync(this, Discord, options); //Roles /// - /// Gets a role. + /// Gets a role in this guild. /// - /// The snowflake identifier of the role. + /// The snowflake identifier for the role. /// - /// The role associated with the snowflake identifier. + /// A role that is associated with the specified ; null if none is found. /// public SocketRole GetRole(ulong id) { @@ -578,18 +600,17 @@ namespace Discord.WebSocket } /// - /// Creates a role. + /// Creates a new role with the provided name. /// - /// The name of the new role. - /// - /// The permissions that the new role possesses. Set to null to use the default permissions. - /// - /// The color of the role. Set to null to use the default color. - /// Used to determine if users of this role are separated in the user list. + /// The new name for the role. + /// The guild permission that the role should possess. + /// The color of the role. + /// Whether the role is separated from others on the sidebar. /// The options to be used when sending the request. - /// is null. + /// is null. /// - /// The created role. + /// A task that represents the asynchronous creation operation. The task result contains the newly created + /// role. /// public Task CreateRoleAsync(string name, GuildPermissions? permissions = default(GuildPermissions?), Color? color = default(Color?), bool isHoisted = false, RequestOptions options = null) @@ -611,9 +632,16 @@ namespace Discord.WebSocket /// /// Gets a user from this guild. /// - /// The snowflake identifier of the user (e.g. `168693960628371456`). + /// + /// This method retrieves a user found within this guild. + /// + /// This may return null in the WebSocket implementation due to incomplete user collection in + /// large guilds. + /// + /// + /// The snowflake identifier of the user. /// - /// A WebSocket-based guild user associated with the snowflake identifier. + /// A guild user associated with the specified ; null if none is found. /// public SocketGuildUser GetUser(ulong id) { @@ -675,9 +703,7 @@ namespace Discord.WebSocket return null; } - /// - /// Downloads the users of this guild to the WebSocket cache. - /// + /// public async Task DownloadUsersAsync() { await Discord.DownloadUsersAsync(new[] { this }).ConfigureAwait(false); @@ -688,6 +714,15 @@ namespace Discord.WebSocket } //Audit logs + /// + /// Gets the specified number of audit log entries for this guild. + /// + /// The number of audit log entries to fetch. + /// 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 + /// of the requested audit log entries. + /// public IAsyncEnumerable> GetAuditLogsAsync(int limit, RequestOptions options = null) => GuildHelper.GetAuditLogsAsync(this, Discord, null, limit, options); @@ -914,7 +949,7 @@ namespace Discord.WebSocket /// Gets the name of the guild. /// /// - /// A string that resolves to the of this guild. + /// A string that resolves to . /// public override string ToString() => Name; private string DebuggerDisplay => $"{Name} ({Id})"; @@ -1025,6 +1060,7 @@ namespace Discord.WebSocket Task IGuild.GetOwnerAsync(CacheMode mode, RequestOptions options) => Task.FromResult(Owner); + /// async Task> IGuild.GetAuditLogAsync(int limit, CacheMode cacheMode, RequestOptions options) { if (cacheMode == CacheMode.AllowDownload)