diff --git a/src/Discord.Net.Commands/CommandService.cs b/src/Discord.Net.Commands/CommandService.cs index 096fc9e11..96677c203 100644 --- a/src/Discord.Net.Commands/CommandService.cs +++ b/src/Discord.Net.Commands/CommandService.cs @@ -130,33 +130,33 @@ namespace Discord.Commands } /// - /// Add a command module from a . + /// Add a command module from a . /// /// The type of module. - /// - /// The for your dependency injection solution if using one; otherwise, pass - /// null. - /// + /// The for your dependency injection solution if using one; otherwise, pass null . + /// This module has already been added. + /// + /// The fails to be built; an invalid type may have been provided. + /// /// - /// An awaitable containing the built module. + /// A task that represents the asynchronous operation for adding the module. The task result contains the + /// built module. /// - /// This module has already been added. - /// The fails to be built; an invalid type may have been provided. public Task AddModuleAsync(IServiceProvider services) => AddModuleAsync(typeof(T), services); /// - /// Adds a command module from a . + /// Adds a command module from a . /// /// The type of module. - /// - /// The for your dependency injection solution if using one; otherwise, pass - /// null. - /// + /// The for your dependency injection solution if using one; otherwise, pass null . + /// This module has already been added. + /// + /// The fails to be built; an invalid type may have been provided. + /// /// - /// An awaitable containing the built module. + /// A task that represents the asynchronous operation for adding the module. The task result contains the + /// built module. /// - /// This module has already been added. - /// The fails to be built; an invalid type may have been provided. public async Task AddModuleAsync(Type type, IServiceProvider services) { services = services ?? EmptyServiceProvider.Instance; @@ -186,13 +186,11 @@ namespace Discord.Commands /// /// Add command modules from an . /// - /// The containing command modules. - /// - /// The for your dependency injection solution if using one; otherwise, pass - /// null. - /// + /// The containing command modules. + /// The for your dependency injection solution if using one; otherwise, pass null. /// - /// An awaitable containing the built module. + /// A task that represents the asynchronous operation for adding the command modules. The task result + /// contains an enumerable collection of modules added. /// public async Task> AddModulesAsync(Assembly assembly, IServiceProvider services) { @@ -234,7 +232,8 @@ namespace Discord.Commands /// /// The to be removed from the service. /// - /// Returns whether the module is successfully removed. + /// A task that represents the asynchronous removal operation. The task result contains a value that + /// indicates whether the is successfully removed. /// public async Task RemoveModuleAsync(ModuleInfo module) { @@ -253,7 +252,8 @@ namespace Discord.Commands /// /// The of the module. /// - /// Returns whether the module is successfully removed. + /// A task that represents the asynchronous removal operation. The task result contains a value that + /// indicates whether the module is successfully removed. /// public Task RemoveModuleAsync() => RemoveModuleAsync(typeof(T)); /// @@ -261,7 +261,8 @@ namespace Discord.Commands /// /// The of the module. /// - /// Returns whether the module is successfully removed. + /// A task that represents the asynchronous removal operation. The task result contains a value that + /// indicates whether the module is successfully removed. /// public async Task RemoveModuleAsync(Type type) { @@ -455,7 +456,10 @@ namespace Discord.Commands /// The position of which the command starts at. /// The service to be used in the command's dependency injection. /// The handling mode when multiple command matches are found. - /// The result of the command execution. + /// + /// A task that represents the asynchronous execution operation. The task result contains the result of the + /// command execution. + /// public Task ExecuteAsync(ICommandContext context, int argPos, IServiceProvider services, MultiMatchHandling multiMatchHandling = MultiMatchHandling.Exception) => ExecuteAsync(context, context.Message.Content.Substring(argPos), services, multiMatchHandling); /// @@ -465,7 +469,10 @@ namespace Discord.Commands /// The command string. /// The service to be used in the command's dependency injection. /// The handling mode when multiple command matches are found. - /// The result of the command execution. + /// + /// A task that represents the asynchronous execution operation. The task result contains the result of the + /// command execution. + /// public async Task ExecuteAsync(ICommandContext context, string input, IServiceProvider services, MultiMatchHandling multiMatchHandling = MultiMatchHandling.Exception) { services = services ?? EmptyServiceProvider.Instance; diff --git a/src/Discord.Net.Commands/CommandServiceConfig.cs b/src/Discord.Net.Commands/CommandServiceConfig.cs index 6464a4811..0d52eacc1 100644 --- a/src/Discord.Net.Commands/CommandServiceConfig.cs +++ b/src/Discord.Net.Commands/CommandServiceConfig.cs @@ -55,7 +55,9 @@ namespace Discord.Commands /// public Dictionary QuotationMarkAliasMap { get; set; } = QuotationAliasUtils.GetDefaultAliasMap; - /// Determines whether extra parameters should be ignored. + /// + /// Gets or sets a value that indicates whether extra parameters should be ignored. + /// public bool IgnoreExtraArgs { get; set; } = false; } } diff --git a/src/Discord.Net.Commands/Readers/TypeReader.cs b/src/Discord.Net.Commands/Readers/TypeReader.cs index 037213ae9..af780993d 100644 --- a/src/Discord.Net.Commands/Readers/TypeReader.cs +++ b/src/Discord.Net.Commands/Readers/TypeReader.cs @@ -15,7 +15,7 @@ namespace Discord.Commands /// The raw input of the command. /// The service collection used for dependency injection. /// - /// An awaitable Task containing the result of the type reading process. + /// A task that represents the asynchronous parsing operation. The task result contains the parsing result. /// public abstract Task ReadAsync(ICommandContext context, string input, IServiceProvider services); } diff --git a/src/Discord.Net.Core/Entities/Channels/IAudioChannel.cs b/src/Discord.Net.Core/Entities/Channels/IAudioChannel.cs index 6d8ef2cd3..a6efa0de6 100644 --- a/src/Discord.Net.Core/Entities/Channels/IAudioChannel.cs +++ b/src/Discord.Net.Core/Entities/Channels/IAudioChannel.cs @@ -25,7 +25,7 @@ namespace Discord /// Disconnects from this audio channel. /// /// - /// A task representing the asynchronous disconnection operation. + /// A task representing the asynchronous operation for disconnecting from the audio channel. /// Task DisconnectAsync(); } diff --git a/src/Discord.Net.Core/Entities/Channels/IGuildChannel.cs b/src/Discord.Net.Core/Entities/Channels/IGuildChannel.cs index 7c4dd8675..6bd2d3e7d 100644 --- a/src/Discord.Net.Core/Entities/Channels/IGuildChannel.cs +++ b/src/Discord.Net.Core/Entities/Channels/IGuildChannel.cs @@ -58,7 +58,7 @@ namespace Discord /// Task CreateInviteAsync(int? maxAge = 86400, int? maxUses = default(int?), bool isTemporary = false, bool isUnique = false, RequestOptions options = null); /// - /// Returns a collection of all invites to this channel. + /// Gets a collection of all invites to this channel. /// /// The options to be used when sending the request. /// @@ -78,7 +78,7 @@ namespace Discord Task ModifyAsync(Action func, RequestOptions options = null); /// - /// Gets the permission overwrite for a specific role, or null if one does not exist. + /// Gets the permission overwrite for a specific role. /// /// The role to get the overwrite from. /// @@ -86,7 +86,7 @@ namespace Discord /// OverwritePermissions? GetPermissionOverwrite(IRole role); /// - /// Gets the permission overwrite for a specific user, or null if one does not exist. + /// Gets the permission overwrite for a specific user. /// /// The user to get the overwrite from. /// @@ -99,7 +99,7 @@ namespace Discord /// The role to remove the overwrite from. /// The options to be used when sending the request. /// - /// A task representing the asynchronous removal operation. + /// A task representing the asynchronous operation for removing the specified permissions from the channel. /// Task RemovePermissionOverwriteAsync(IRole role, RequestOptions options = null); /// @@ -108,7 +108,7 @@ namespace Discord /// The user to remove the overwrite from. /// The options to be used when sending the request. /// - /// A task representing the asynchronous removal operation. + /// A task representing the asynchronous operation for removing the specified permissions from the channel. /// Task RemovePermissionOverwriteAsync(IUser user, RequestOptions options = null); @@ -119,7 +119,7 @@ namespace Discord /// The overwrite to add to the role. /// The options to be used when sending the request. /// - /// A task representing the asynchronous permission addition operation. + /// A task representing the asynchronous permission operation for adding the specified permissions to the channel. /// Task AddPermissionOverwriteAsync(IRole role, OverwritePermissions permissions, RequestOptions options = null); /// @@ -129,16 +129,14 @@ namespace Discord /// The overwrite to add to the user. /// The options to be used when sending the request. /// - /// A task representing the asynchronous permission addition operation. + /// A task representing the asynchronous permission operation for adding the specified permissions to the channel. /// Task AddPermissionOverwriteAsync(IUser user, OverwritePermissions permissions, RequestOptions options = null); /// - /// Gets a collection of all users in this channel. + /// Gets a collection of users that are able to view the channel. /// - /// - /// 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. /// /// A paged collection containing a collection of guild users that can access this channel. Flattening the @@ -147,13 +145,13 @@ namespace Discord /// new IAsyncEnumerable> GetUsersAsync(CacheMode mode = CacheMode.AllowDownload, RequestOptions options = null); /// - /// Gets a user in this channel with the provided ID. + /// Gets a user in this channel. /// - /// The ID of the user. + /// 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. /// - /// A task representing the asynchrnous get operation. The task result contains a guild user object that + /// A task representing the asynchronous 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 ef62f5d4f..50b6a4d66 100644 --- a/src/Discord.Net.Core/Entities/Channels/IMessageChannel.cs +++ b/src/Discord.Net.Core/Entities/Channels/IMessageChannel.cs @@ -18,7 +18,7 @@ namespace Discord /// The to be sent. /// The options to be used when sending the request. /// - /// A task that represents an asynchrnous send operation for delievering the message. The task result + /// A task that represents an asynchronous 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); @@ -39,7 +39,7 @@ namespace Discord /// The to be sent. /// The options to be used when sending the request. /// - /// A task that represents an asynchrnous send operation for delievering the message. The task result + /// A task that represents an asynchronous 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); @@ -61,7 +61,7 @@ namespace Discord /// The to be sent. /// The options to be used when sending the request. /// - /// A task that represents an asynchrnous send operation for delievering the message. The task result + /// A task that represents an asynchronous 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); @@ -73,7 +73,7 @@ namespace Discord /// The that determines whether the object should be fetched from cache. /// The options to be used when sending the request. /// - /// A task that represents an asynchrnous get operation for retrieving the message. The task result contains + /// A task that represents an asynchronous 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); diff --git a/src/Discord.Net.Core/Entities/Channels/INestedChannel.cs b/src/Discord.Net.Core/Entities/Channels/INestedChannel.cs index c6fcba9de..22182a4ca 100644 --- a/src/Discord.Net.Core/Entities/Channels/INestedChannel.cs +++ b/src/Discord.Net.Core/Entities/Channels/INestedChannel.cs @@ -21,7 +21,7 @@ namespace Discord /// The that determines whether the object should be fetched from cache. /// The options to be used when sending the request. /// - /// A task that represents the asynchrnous get operation. The task result contains the category channel + /// A task that represents the asynchronous 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/ITextChannel.cs b/src/Discord.Net.Core/Entities/Channels/ITextChannel.cs index e619c1735..2b5da5b2f 100644 --- a/src/Discord.Net.Core/Entities/Channels/ITextChannel.cs +++ b/src/Discord.Net.Core/Entities/Channels/ITextChannel.cs @@ -11,7 +11,7 @@ namespace Discord public interface ITextChannel : IMessageChannel, IMentionable, INestedChannel { /// - /// Determines whether the channel is NSFW. + /// Gets a value that indicates whether the channel is NSFW. /// /// /// true if the channel has the NSFW flag enabled; otherwise false. diff --git a/src/Discord.Net.Core/Entities/Emotes/Emoji.cs b/src/Discord.Net.Core/Entities/Emotes/Emoji.cs index 102abf7e2..d5e795094 100644 --- a/src/Discord.Net.Core/Entities/Emotes/Emoji.cs +++ b/src/Discord.Net.Core/Entities/Emotes/Emoji.cs @@ -27,7 +27,7 @@ namespace Discord } /// - /// Determines whether the specified emoji is equal to the current emoji. + /// Determines whether the specified emoji is equal to the current one. /// /// The object to compare with the current object. public override bool Equals(object other) diff --git a/src/Discord.Net.Core/Entities/Emotes/GuildEmote.cs b/src/Discord.Net.Core/Entities/Emotes/GuildEmote.cs index 3e13b1364..9affb1e89 100644 --- a/src/Discord.Net.Core/Entities/Emotes/GuildEmote.cs +++ b/src/Discord.Net.Core/Entities/Emotes/GuildEmote.cs @@ -42,6 +42,9 @@ namespace Discord /// /// Gets 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/Guilds/IGuild.cs b/src/Discord.Net.Core/Entities/Guilds/IGuild.cs index 06348aa7f..bba400b31 100644 --- a/src/Discord.Net.Core/Entities/Guilds/IGuild.cs +++ b/src/Discord.Net.Core/Entities/Guilds/IGuild.cs @@ -27,7 +27,7 @@ namespace Discord /// int AFKTimeout { get; } /// - /// Determines if this guild is embeddable (i.e. can use widget). + /// Gets a value that indicates whether this guild is embeddable (i.e. can use widget). /// /// /// true if this guild can be embedded via widgets; otherwise false. diff --git a/src/Discord.Net.Core/Entities/Guilds/IVoiceRegion.cs b/src/Discord.Net.Core/Entities/Guilds/IVoiceRegion.cs index 8516036f1..9cef84914 100644 --- a/src/Discord.Net.Core/Entities/Guilds/IVoiceRegion.cs +++ b/src/Discord.Net.Core/Entities/Guilds/IVoiceRegion.cs @@ -8,26 +8,44 @@ namespace Discord /// /// Gets the unique identifier for this voice region. /// + /// + /// A string that represents the identifier for this voice region (e.g. eu-central). + /// string Id { get; } /// /// Gets the name of this voice region. /// + /// + /// A string that represents the human-readable name of this voice region (e.g. Central Europe). + /// string Name { get; } /// - /// Returns true if this voice region is exclusive to VIP accounts. + /// Gets a value that indicates whether or not this voice region is exclusive to partnered servers. /// + /// + /// true if this voice region is exclusive to VIP accounts; otherwise false. + /// bool IsVip { get; } /// - /// Returns true if this voice region is the closest to your machine. + /// Gets a value that indicates whether this voice region is optimal for your client in terms of latency. /// + /// + /// true if this voice region is the closest to your machine; otherwise false . + /// bool IsOptimal { get; } - /// - /// Returns true if this is a deprecated voice region (avoid switching to these). + /// + /// Gets a value that indicates whether this voice region is no longer being maintained. /// + /// + /// true if this is a deprecated voice region; otherwise false. + /// bool IsDeprecated { get; } - /// - /// Returns true if this is a custom voice region (used for events/etc). + /// + /// Gets a value that indicates whether this voice region is custom-made for events. /// + /// + /// true if this is a custom voice region (used for events/etc); otherwise false/ + /// bool IsCustom { get; } } } diff --git a/src/Discord.Net.Core/Entities/Invites/IInviteMetadata.cs b/src/Discord.Net.Core/Entities/Invites/IInviteMetadata.cs index 2279b59fc..471dc377f 100644 --- a/src/Discord.Net.Core/Entities/Invites/IInviteMetadata.cs +++ b/src/Discord.Net.Core/Entities/Invites/IInviteMetadata.cs @@ -15,15 +15,14 @@ namespace Discord /// IUser Inviter { get; } /// - /// Determines whether the invite has been revoked. + /// Gets a value that indicates whether the invite has been revoked. /// /// /// true if this invite was revoked; otherwise false. /// bool IsRevoked { get; } /// - /// Determines whether the invite is a temporary one (i.e. whether the invite will be removed from the guild - /// when the user logs off). + /// Gets a value that indicates whether the invite is a temporary one. /// /// /// true if users accepting this invite will be removed from the guild when they log off; otherwise diff --git a/src/Discord.Net.Core/Entities/Messages/EmbedBuilder.cs b/src/Discord.Net.Core/Entities/Messages/EmbedBuilder.cs index ed411c8eb..6c5d780ca 100644 --- a/src/Discord.Net.Core/Entities/Messages/EmbedBuilder.cs +++ b/src/Discord.Net.Core/Entities/Messages/EmbedBuilder.cs @@ -492,7 +492,7 @@ namespace Discord } } /// - /// Determines whether the field should be in-line with each other. + /// Gets or sets a value that indicates whether the field should be in-line with each other. /// public bool IsInline { get; set; } diff --git a/src/Discord.Net.Core/Entities/Messages/EmbedField.cs b/src/Discord.Net.Core/Entities/Messages/EmbedField.cs index 12cdcec9b..f6aa2af3b 100644 --- a/src/Discord.Net.Core/Entities/Messages/EmbedField.cs +++ b/src/Discord.Net.Core/Entities/Messages/EmbedField.cs @@ -17,7 +17,7 @@ namespace Discord /// public string Value { get; internal set; } /// - /// Determines whether the field should be in-line with each other. + /// Gets a value that indicates whether the field should be in-line with each other. /// public bool Inline { get; internal set; } @@ -32,6 +32,9 @@ namespace Discord /// /// Gets the name of the field. /// + /// + /// A string that resolves to . + /// public override string ToString() => Name; } } diff --git a/src/Discord.Net.Core/Entities/Messages/IMessage.cs b/src/Discord.Net.Core/Entities/Messages/IMessage.cs index edbe4f4b6..3de57bd50 100644 --- a/src/Discord.Net.Core/Entities/Messages/IMessage.cs +++ b/src/Discord.Net.Core/Entities/Messages/IMessage.cs @@ -17,12 +17,18 @@ namespace Discord /// MessageSource Source { get; } /// - /// Returns true if this message was sent as a text-to-speech message. + /// Gets the value that indicates whether this message was meant to be read-aloud by Discord. /// + /// + /// true if this message was sent as a text-to-speech message; otherwise false. + /// bool IsTTS { get; } /// - /// Returns true if this message was added to its channel's pinned messages. + /// Gets the value that indicates whether this message is pinned. /// + /// + /// true if this message was added to its channel's pinned messages; otherwise false. + /// bool IsPinned { get; } /// /// Returns the content for this message. @@ -56,14 +62,14 @@ namespace Discord /// Returns all attachments included in this message. /// /// - /// Collection of attachments. + /// A read-only collection of attachments. /// IReadOnlyCollection Attachments { get; } /// /// Returns all embeds included in this message. /// /// - /// Collection of embed objects. + /// A read-only collection of embed objects. /// IReadOnlyCollection Embeds { get; } /// @@ -74,21 +80,21 @@ namespace Discord /// Returns the IDs of channels mentioned in this message. /// /// - /// Collection of channel IDs. + /// A read-only collection of channel IDs. /// IReadOnlyCollection MentionedChannelIds { get; } /// /// Returns the IDs of roles mentioned in this message. /// /// - /// Collection of role IDs. + /// A read-only collection of role IDs. /// IReadOnlyCollection MentionedRoleIds { get; } /// /// Returns the IDs of users mentioned in this message. /// /// - /// Collection of user IDs. + /// A read-only collection of user IDs. /// IReadOnlyCollection MentionedUserIds { get; } } diff --git a/src/Discord.Net.Core/Entities/Messages/IUserMessage.cs b/src/Discord.Net.Core/Entities/Messages/IUserMessage.cs index 2ea8a02a7..b31890e51 100644 --- a/src/Discord.Net.Core/Entities/Messages/IUserMessage.cs +++ b/src/Discord.Net.Core/Entities/Messages/IUserMessage.cs @@ -20,7 +20,7 @@ namespace Discord /// A delegate containing the properties to modify the message 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); /// @@ -28,7 +28,7 @@ namespace Discord /// /// The options to be used when sending the request. /// - /// An awaitable . + /// A task that represents the asynchronous operation for pinning this message. /// Task PinAsync(RequestOptions options = null); /// @@ -36,7 +36,7 @@ namespace Discord /// /// The options to be used when sending the request. /// - /// An awaitable . + /// A task that represents the asynchronous operation for unpinning this message. /// Task UnpinAsync(RequestOptions options = null); @@ -56,8 +56,9 @@ namespace Discord /// The emoji used to react to this message. /// The options to be used when sending the request. /// - /// An awaitable . + /// A task that represents the asynchronous operation for adding a reaction to this message. /// + /// Task AddReactionAsync(IEmote emote, RequestOptions options = null); /// /// Removes a reaction from message. @@ -71,20 +72,36 @@ namespace Discord /// The user that added the emoji. /// The options to be used when sending the request. /// - /// An awaitable . + /// A task that represents the asynchronous operation for removing a reaction to this message. /// + /// Task RemoveReactionAsync(IEmote emote, IUser user, RequestOptions options = null); /// /// Removes all reactions from this message. /// /// The options to be used when sending the request. /// - /// An awaitable . + /// A task that represents the asynchronous removal operation. /// Task RemoveAllReactionsAsync(RequestOptions options = null); + /// /// Gets all users that reacted to a message with a given emote. /// + /// + /// + /// var emoji = new Emoji("\U0001f495"); + /// var reactedUsers = await message.GetReactionUsersAsync(emoji, 100).FlattenAsync(); + /// + /// + /// The emoji that represents the reaction that you wish to get. + /// The number of users to request. + /// The options to be used when sending the request. + /// + /// A paged collection containing a read-only collection of users that has reacted to this message. + /// Flattening the paginated response into a collection of users with + /// is required if you wish to access the users. + /// IAsyncEnumerable> GetReactionUsersAsync(IEmote emoji, int limit, RequestOptions options = null); /// diff --git a/src/Discord.Net.Core/Entities/Roles/IRole.cs b/src/Discord.Net.Core/Entities/Roles/IRole.cs index 1fb2732ce..dcfc89cc6 100644 --- a/src/Discord.Net.Core/Entities/Roles/IRole.cs +++ b/src/Discord.Net.Core/Entities/Roles/IRole.cs @@ -24,21 +24,21 @@ namespace Discord /// Color Color { get; } /// - /// Determines whether the role can be separated in the user list. + /// Gets a value that indicates whether the role can be separated in the user list. /// /// /// true if users of this role are separated in the user list; otherwise false. /// bool IsHoisted { get; } /// - /// Determines whether the role is managed by Discord. + /// Gets a value that indicates whether the role is managed by Discord. /// /// /// true if this role is automatically managed by Discord; otherwise false. /// bool IsManaged { get; } /// - /// Determines whether the role is mentionable. + /// Gets a value that indicates whether the role is mentionable. /// /// /// true if this role may be mentioned in messages; otherwise false. @@ -82,7 +82,7 @@ namespace Discord /// A delegate containing the properties to modify the role 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); } diff --git a/src/Discord.Net.Core/Entities/Users/IUser.cs b/src/Discord.Net.Core/Entities/Users/IUser.cs index 96b9ae7ee..ca9f092e0 100644 --- a/src/Discord.Net.Core/Entities/Users/IUser.cs +++ b/src/Discord.Net.Core/Entities/Users/IUser.cs @@ -15,9 +15,7 @@ namespace Discord /// Returns a URL to this user's avatar. /// /// The format to return. - /// - /// The size of the image to return in. This can be any power of two between 16 and 2048. - /// + /// The size of the image to return in. This can be any power of two between 16 and 2048. /// /// User's avatar URL. /// @@ -35,12 +33,18 @@ namespace Discord /// ushort DiscriminatorValue { get; } /// - /// Gets true if this user is a bot user. + /// Gets a value that indicates whether this user is a bot user. /// + /// + /// true if the user is a bot; otherwise false. + /// bool IsBot { get; } /// - /// Gets true if this user is a webhook user. + /// Gets a value that indicates whether this user is a webhook user. /// + /// + /// true if the user is a webhook; otherwise false. + /// bool IsWebhook { get; } /// /// Gets the username for this user. @@ -52,7 +56,7 @@ namespace Discord /// /// The options to be used when sending the request. /// - /// An awaitable Task containing the DM channel. + /// A task that represents the asynchronous operation for getting or creating a DM channel. /// Task GetOrCreateDMChannelAsync(RequestOptions options = null); } diff --git a/src/Discord.Net.Core/Extensions/UserExtensions.cs b/src/Discord.Net.Core/Extensions/UserExtensions.cs index ff3c24bbf..16d9a56e9 100644 --- a/src/Discord.Net.Core/Extensions/UserExtensions.cs +++ b/src/Discord.Net.Core/Extensions/UserExtensions.cs @@ -16,7 +16,7 @@ namespace Discord /// 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 the asynchrnonous send operation. The task result contains the sent message. /// public static async Task SendMessageAsync(this IUser user, string text = null, @@ -43,7 +43,7 @@ namespace Discord /// . /// /// - /// An awaitable Task containing the message sent to the channel. + /// A task that represents the asynchrnonous send operation. The task result contains the sent message. /// public static async Task SendFileAsync(this IUser user, Stream stream, @@ -72,7 +72,7 @@ namespace Discord /// . /// /// - /// An awaitable Task containing the message sent to the channel. + /// A task that represents the asynchrnonous send operation. The task result contains the sent message. /// public static async Task SendFileAsync(this IUser user, string filePath, @@ -85,15 +85,16 @@ namespace Discord } /// - /// Bans the provided user from the guild and optionally prunes their recent messages. + /// Bans the user from the guild and optionally prunes their recent messages. /// /// 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 for - must be between [0, 7] /// The reason of the ban to be written in the audit log. /// The options to be used when sending the request. /// is not between 0 to 7. + /// + /// A task that represents the asynchrnous operation for banning a user. + /// public static Task BanAsync(this IGuildUser user, int pruneDays = 0, string reason = null, RequestOptions options = null) => user.Guild.AddBanAsync(user, pruneDays, reason, options); } diff --git a/src/Discord.Net.Core/IDiscordClient.cs b/src/Discord.Net.Core/IDiscordClient.cs index a962839d0..d6a863556 100644 --- a/src/Discord.Net.Core/IDiscordClient.cs +++ b/src/Discord.Net.Core/IDiscordClient.cs @@ -34,14 +34,14 @@ namespace Discord /// /// /// - /// An awaitable . + /// A task that represents the asynchronous start operation. /// Task StartAsync(); /// /// Stops the connection between Discord and the client. /// /// - /// An awaitable . + /// A task that represents the asynchronous stop operation. /// Task StopAsync(); @@ -54,37 +54,35 @@ namespace Discord /// /// The options to be used when sending the request. /// - /// An awaitable containing the application information. + /// A task that represents the asynchronous get operation. The task result contains the application + /// information. /// Task GetApplicationInfoAsync(RequestOptions options = null); /// - /// Gets a generic channel via the snowflake identifier. + /// Gets a generic channel. /// /// - /// + /// /// var channel = await _client.GetChannelAsync(381889909113225237); /// if (channel != null && channel is IMessageChannel msgChannel) /// { /// await msgChannel.SendMessageAsync($"{msgChannel} is created at {msgChannel.CreatedAt}"); /// } - /// + /// /// /// The snowflake identifier of the channel (e.g. `381889909113225237`). - /// - /// 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 channel associated with the snowflake identifier. + /// A task that represents the asynchronous get operation. The task result contains the channel associated + /// with the snowflake identifier; null when the channel cannot be found. /// Task GetChannelAsync(ulong id, CacheMode mode = CacheMode.AllowDownload, RequestOptions options = null); /// /// Gets a collection of private channels opened in this session. /// - /// - /// 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. /// /// This method will retrieve all private channels (including direct-message, group channel and such) that @@ -95,8 +93,8 @@ namespace Discord /// /// /// - /// An awaitable containing a collection of private channels that have been opened in - /// this session. + /// A task that represents the asynchronous get operation. The task result contains a read-only collection + /// of private channels that the user currently partakes in. /// Task> GetPrivateChannelsAsync(CacheMode mode = CacheMode.AllowDownload, RequestOptions options = null); /// @@ -109,13 +107,11 @@ namespace Discord /// have just started the client, this may return an empty collection. /// /// - /// - /// 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 DM channels that have been opened in this - /// session. + /// A task that represents the asynchronous get operation. The task result contains a read-only collection + /// of direct-message channels that the user currently partakes in. /// Task> GetDMChannelsAsync(CacheMode mode = CacheMode.AllowDownload, RequestOptions options = null); /// @@ -128,64 +124,145 @@ namespace Discord /// have just started the client, this may return an empty collection. /// /// - /// - /// 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 group channels that have been opened in this - /// session. + /// A task that represents the asynchronous get operation. The task result contains a read-only collection + /// of group channels that the user currently partakes in. /// Task> GetGroupChannelsAsync(CacheMode mode = CacheMode.AllowDownload, RequestOptions options = null); + /// + /// Gets the connections that the user has set up. + /// + /// 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 connections. + /// Task> GetConnectionsAsync(RequestOptions options = null); + /// + /// Gets a guild. + /// + /// The guild snowflake identifier. + /// The that determines whether the object should be fetched from cache. + /// The options to be used when sending the request. + /// + /// A task that represents the asynchronous get operation. The task result contains the guild associated + /// with the snowflake identifier; null when the guild cannot be found. + /// Task GetGuildAsync(ulong id, CacheMode mode = CacheMode.AllowDownload, RequestOptions options = null); + /// + /// Gets a collection of guilds that the user is currently in. + /// + /// The that determines whether the object should be fetched from cache. + /// 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 guilds that the current user is in. + /// Task> GetGuildsAsync(CacheMode mode = CacheMode.AllowDownload, RequestOptions options = null); + /// + /// Creates a guild for the logged-in user who is in less than 10 active guilds. + /// + /// + /// This method creates a new guild on behalf of the logged-in user. + /// + /// Due to Discord's limitation, this method will only work for users that are in less than 10 guilds. + /// + /// + /// The name of the new guild. + /// The voice region to create the guild with. + /// The icon of the guild. + /// The options to be used when sending the request. + /// + /// A task that represents the asynchronous creation operation. The task result contains the created guild. + /// Task CreateGuildAsync(string name, IVoiceRegion region, Stream jpegIcon = null, RequestOptions options = null); - + + /// + /// Gets an invite. + /// + /// The invitation identifier. + /// The options to be used when sending the request. + /// + /// A task that represents the asynchronous get operation. The task result contains the invite information. + /// Task GetInviteAsync(string inviteId, RequestOptions options = null); /// - /// Gets a user via the snowflake identifier. + /// Gets a user. /// /// - /// + /// /// var user = await _client.GetUserAsync(168693960628371456); /// if (user != null) /// Console.WriteLine($"{user} is created at {user.CreatedAt}."; /// /// /// The snowflake identifier of the user (e.g. `168693960628371456`). - /// - /// 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 fetched user; null if none is found. + /// A task that represents the asynchronous get operation. The task result contains the user associated with + /// the snowflake identifier; null if the user is not found. /// Task GetUserAsync(ulong id, CacheMode mode = CacheMode.AllowDownload, RequestOptions options = null); /// - /// Gets a user via the username and discriminator combo. + /// Gets a user. /// /// - /// - /// var user = await _client.GetUserAsync("Still", "2876"); - /// if (user != null) - /// Console.WriteLine($"{user} is created at {user.CreatedAt}."; - /// + /// + /// var user = await _client.GetUserAsync("Still", "2876"); + /// if (user != null) + /// Console.WriteLine($"{user} is created at {user.CreatedAt}."; + /// /// /// The name of the user (e.g. `Still`). /// The discriminator value of the user (e.g. `2876`). /// The options to be used when sending the request. /// - /// An awaitable containing the fetched user; null if none is found. + /// A task that represents the asynchronous get operation. The task result contains the user associated with + /// the name and the discriminator; null if the user is not found. /// Task GetUserAsync(string username, string discriminator, RequestOptions options = null); + /// + /// Gets a collection of the available voice regions. + /// + /// + /// The following example gets the most optimal voice region from the collection. + /// + /// var regions = await client.GetVoiceRegionsAsync(); + /// var optimalRegion = regions.FirstOrDefault(x => x.IsOptimal); + /// + /// + /// 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 + /// with all of the available voice regions in this session. + /// Task> GetVoiceRegionsAsync(RequestOptions options = null); + /// + /// Gets a voice region. + /// + /// The identifier of the voice region (e.g. eu-central ). + /// The options to be used when sending the request. + /// + /// A task that represents the asynchronous get operation. The task result contains the voice region + /// associated with the identifier; null if the voice region is not found. + /// Task GetVoiceRegionAsync(string id, RequestOptions options = null); + /// + /// Gets a webhook available. + /// + /// The identifier of the webhook. + /// The options to be used when sending the request. + /// + /// 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); /// @@ -193,8 +270,8 @@ namespace Discord /// /// The options to be used when sending the request. /// - /// An awaitable containing an that represents the number of shards - /// that should be used with this account. + /// A task that represents the asynchronous get operation. The task result contains an + /// that represents the number of shards that should be used with this account. /// Task GetRecommendedShardCountAsync(RequestOptions options = null); } diff --git a/src/Discord.Net.Core/Utils/Cacheable.cs b/src/Discord.Net.Core/Utils/Cacheable.cs index 02da682ae..1857ae7a0 100644 --- a/src/Discord.Net.Core/Utils/Cacheable.cs +++ b/src/Discord.Net.Core/Utils/Cacheable.cs @@ -44,7 +44,8 @@ namespace Discord /// Thrown when used from a user account. /// Thrown when the message is deleted. /// - /// An awaitable containing the downloaded entity. + /// A task that represents the asynchronous download operation. The task result contains the downloaded + /// entity. /// public async Task DownloadAsync() { @@ -57,7 +58,8 @@ namespace Discord /// Thrown when used from a user account. /// Thrown when the message is deleted and is not in cache. /// - /// An awaitable containing a cached or downloaded entity. + /// A task that represents the asynchronous operation that attempts to get the message via cache or to + /// download the message. The task result contains the downloaded entity. /// public async Task GetOrDownloadAsync() => HasValue ? Value : await DownloadAsync().ConfigureAwait(false); } diff --git a/src/Discord.Net.Rest/BaseDiscordClient.cs b/src/Discord.Net.Rest/BaseDiscordClient.cs index 5240c9d7a..1d45e0094 100644 --- a/src/Discord.Net.Rest/BaseDiscordClient.cs +++ b/src/Discord.Net.Rest/BaseDiscordClient.cs @@ -32,9 +32,7 @@ namespace Discord.Rest /// Gets the logged-in user. /// public ISelfUser CurrentUser { get; protected set; } - /// - /// Gets the type of the authentication token. - /// + /// public TokenType TokenType => ApiClient.AuthTokenType; /// Creates a new REST-only Discord client. diff --git a/src/Discord.Net.Rest/Entities/AuditLogs/DataTypes/InviteCreateAuditLogData.cs b/src/Discord.Net.Rest/Entities/AuditLogs/DataTypes/InviteCreateAuditLogData.cs index c210d72f0..1025dd315 100644 --- a/src/Discord.Net.Rest/Entities/AuditLogs/DataTypes/InviteCreateAuditLogData.cs +++ b/src/Discord.Net.Rest/Entities/AuditLogs/DataTypes/InviteCreateAuditLogData.cs @@ -62,8 +62,7 @@ namespace Discord.Rest /// public string Code { get; } /// - /// Determines whether the invite is a temporary one (i.e. whether the invite will be removed from the guild - /// when the user logs off). + /// Gets a value that determines whether the invite is a temporary one. /// /// /// true if users accepting this invite will be removed from the guild when they log off; otherwise diff --git a/src/Discord.Net.Rest/Entities/AuditLogs/DataTypes/InviteDeleteAuditLogData.cs b/src/Discord.Net.Rest/Entities/AuditLogs/DataTypes/InviteDeleteAuditLogData.cs index 956598a86..e77857d83 100644 --- a/src/Discord.Net.Rest/Entities/AuditLogs/DataTypes/InviteDeleteAuditLogData.cs +++ b/src/Discord.Net.Rest/Entities/AuditLogs/DataTypes/InviteDeleteAuditLogData.cs @@ -62,8 +62,7 @@ namespace Discord.Rest /// public string Code { get; } /// - /// Determines whether the invite is a temporary one (i.e. whether the invite will be removed from the guild - /// when the user logs off). + /// Gets a value that indicates whether the invite is a temporary one. /// /// /// true if users accepting this invite will be removed from the guild when they log off; otherwise diff --git a/src/Discord.Net.Rest/Entities/AuditLogs/DataTypes/InviteInfo.cs b/src/Discord.Net.Rest/Entities/AuditLogs/DataTypes/InviteInfo.cs index 35f8937c2..aaad362da 100644 --- a/src/Discord.Net.Rest/Entities/AuditLogs/DataTypes/InviteInfo.cs +++ b/src/Discord.Net.Rest/Entities/AuditLogs/DataTypes/InviteInfo.cs @@ -30,8 +30,7 @@ namespace Discord.Rest /// public string Code { get; } /// - /// Determines whether the invite is a temporary one (i.e. whether the invite will be removed from the guild - /// when the user logs off). + /// Gets a value that indicates whether the invite is a temporary one. /// /// /// true if users accepting this invite will be removed from the guild when they log off, diff --git a/src/Discord.Net.Rest/Entities/AuditLogs/DataTypes/MemberRoleEditInfo.cs b/src/Discord.Net.Rest/Entities/AuditLogs/DataTypes/MemberRoleEditInfo.cs index 9fc402b0d..b0abf2d95 100644 --- a/src/Discord.Net.Rest/Entities/AuditLogs/DataTypes/MemberRoleEditInfo.cs +++ b/src/Discord.Net.Rest/Entities/AuditLogs/DataTypes/MemberRoleEditInfo.cs @@ -27,7 +27,7 @@ namespace Discord.Rest /// public ulong RoleId { get; } /// - /// Determines whether the role was added to the user. + /// Gets a value that indicates whether the role was added to the user. /// /// /// true if the role was added to the user; otherwise false. diff --git a/src/Discord.Net.Rest/Entities/AuditLogs/DataTypes/RoleEditInfo.cs b/src/Discord.Net.Rest/Entities/AuditLogs/DataTypes/RoleEditInfo.cs index 07bc9abf5..6f3d8d387 100644 --- a/src/Discord.Net.Rest/Entities/AuditLogs/DataTypes/RoleEditInfo.cs +++ b/src/Discord.Net.Rest/Entities/AuditLogs/DataTypes/RoleEditInfo.cs @@ -24,19 +24,20 @@ namespace Discord.Rest /// public Color? Color { get; } /// - /// Determines whether this role is mentionable (i.e. it can be mentioned in a text channel). + /// Gets a value that indicates whether this role is mentionable. /// /// - /// true if other members can mention this role in a text channel; otherwise false. + /// true if other members can mention this role in a text channel; otherwise false; + /// null if this is not mentioned in this entry. /// public bool? Mentionable { get; } /// - /// Determines whether this role is hoisted (i.e its members will appear in a seperate section on the user - /// list). + /// Gets a value that indicates whether this role is hoisted (i.e. its members will appear in a separate + /// section on the user list). /// /// - /// true if this role's members will appear in a seperate section in the user list; otherwise - /// false. + /// true if this role's members will appear in a separate section in the user list; otherwise + /// false; null if this is not mentioned in this entry. /// public bool? Hoist { get; } /// diff --git a/src/Discord.Net.Rest/Entities/Channels/IRestMessageChannel.cs b/src/Discord.Net.Rest/Entities/Channels/IRestMessageChannel.cs index ac2f27bbd..2a89fa4ba 100644 --- a/src/Discord.Net.Rest/Entities/Channels/IRestMessageChannel.cs +++ b/src/Discord.Net.Rest/Entities/Channels/IRestMessageChannel.cs @@ -13,56 +13,67 @@ namespace Discord.Rest /// 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 asynchronous send operation for delievering the message. The task result + /// contains the sent message. /// new 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. + /// 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 asynchronous send operation for delievering the message. The task result + /// contains the sent message. /// new 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. + /// 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 Task containing the message sent to the channel. + /// A task that represents an asynchronous send operation for delievering the message. The task result + /// contains the sent message. /// new 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 with the given id, or null if not found. + /// Gets a message from this message channel. /// - /// The ID of the message. + /// 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. /// - /// The message gotten from either the cache or the download, or null if none is found. + /// A task that represents an asynchronous 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, RequestOptions options = null); /// @@ -104,7 +115,8 @@ namespace Discord.Rest /// /// 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. /// new Task> GetPinnedMessagesAsync(RequestOptions options = null); } diff --git a/src/Discord.Net.Rest/Entities/Channels/RestGuildChannel.cs b/src/Discord.Net.Rest/Entities/Channels/RestGuildChannel.cs index 5895500bd..380a64c8c 100644 --- a/src/Discord.Net.Rest/Entities/Channels/RestGuildChannel.cs +++ b/src/Discord.Net.Rest/Entities/Channels/RestGuildChannel.cs @@ -73,11 +73,11 @@ namespace Discord.Rest => ChannelHelper.DeleteAsync(this, Discord, options); /// - /// Gets the overwrite permissions of the specified . + /// Gets the permission overwrite for a specific user. /// - /// The user that you want to get the overwrite permissions for. + /// The user to get the overwrite from. /// - /// The overwrite permissions for the requested user; otherwise null. + /// An overwrite object for the targeted user; null if none is set. /// public OverwritePermissions? GetPermissionOverwrite(IUser user) { @@ -90,11 +90,11 @@ namespace Discord.Rest } /// - /// Gets the overwrite permissions of the specified . + /// Gets the permission overwrite for a specific role. /// - /// The role that you want to get the overwrite permissions for. + /// The role to get the overwrite from. /// - /// The overwrite permissions for the requested role; otherwise null. + /// An overwrite object for the targeted role; null if none is set. /// public OverwritePermissions? GetPermissionOverwrite(IRole role) { @@ -107,42 +107,41 @@ namespace Discord.Rest } /// - /// Adds an overwrite permission for the specified . + /// Adds or updates the permission overwrite for the given user. /// - /// The user you want the overwrite permission to apply to. - /// The overwrite permission you want to add. + /// The user to add the overwrite to. + /// The overwrite to add to the user. /// The options to be used when sending the request. /// - /// An awaitable . + /// A task representing the asynchronous permission operation for adding the specified permissions to the channel. /// - public async Task AddPermissionOverwriteAsync(IUser user, OverwritePermissions perms, RequestOptions options = null) + public async Task AddPermissionOverwriteAsync(IUser user, OverwritePermissions permissions, RequestOptions options = null) { - await ChannelHelper.AddPermissionOverwriteAsync(this, Discord, user, perms, options).ConfigureAwait(false); - _overwrites = _overwrites.Add(new Overwrite(user.Id, PermissionTarget.User, new OverwritePermissions(perms.AllowValue, perms.DenyValue))); + await ChannelHelper.AddPermissionOverwriteAsync(this, Discord, user, permissions, options).ConfigureAwait(false); + _overwrites = _overwrites.Add(new Overwrite(user.Id, PermissionTarget.User, new OverwritePermissions(permissions.AllowValue, permissions.DenyValue))); } - /// - /// Adds an overwrite permission for the specified . + /// Adds or updates the permission overwrite for the given role. /// - /// The role you want the overwrite permission to apply to. - /// The overwrite permission you want to add. - /// The options to be used when sending the request. + /// The role to add the overwrite to. + /// The overwrite to add to the role. + /// The options to be used when sending the request. /// - /// An awaitable . + /// A task representing the asynchronous permission operation for adding the specified permissions to the channel. /// - public async Task AddPermissionOverwriteAsync(IRole role, OverwritePermissions perms, RequestOptions options = null) + public async Task AddPermissionOverwriteAsync(IRole role, OverwritePermissions permissions, RequestOptions options = null) { - await ChannelHelper.AddPermissionOverwriteAsync(this, Discord, role, perms, options).ConfigureAwait(false); - _overwrites = _overwrites.Add(new Overwrite(role.Id, PermissionTarget.Role, new OverwritePermissions(perms.AllowValue, perms.DenyValue))); + await ChannelHelper.AddPermissionOverwriteAsync(this, Discord, role, permissions, options).ConfigureAwait(false); + _overwrites = _overwrites.Add(new Overwrite(role.Id, PermissionTarget.Role, new OverwritePermissions(permissions.AllowValue, permissions.DenyValue))); } /// - /// Removes an overwrite permission for the specified . + /// Removes the permission overwrite for the given user, if one exists. /// - /// The user you want to remove the overwrite permission from. + /// The user to remove the overwrite from. /// The options to be used when sending the request. /// - /// An awaitable . + /// A task representing the asynchronous operation for removing the specified permissions from the channel. /// public async Task RemovePermissionOverwriteAsync(IUser user, RequestOptions options = null) { @@ -157,14 +156,13 @@ namespace Discord.Rest } } } - /// - /// Removes an overwrite permission for the specified . + /// Removes the permission overwrite for the given role, if one exists. /// - /// The role you want the overwrite permissions to be removed from. + /// The role to remove the overwrite from. /// The options to be used when sending the request. /// - /// An awaitable . + /// A task representing the asynchronous operation for removing the specified permissions from the channel. /// public async Task RemovePermissionOverwriteAsync(IRole role, RequestOptions options = null) { @@ -181,27 +179,27 @@ namespace Discord.Rest } /// - /// Gets the invites for this channel. + /// Gets a collection of all invites to this channel. /// /// The options to be used when sending the request. /// - /// An awaitable containing an . - /// contains information such as, the number of times the invite has - /// been used, who created the invite, and when the invite was created. + /// 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. /// public async Task> GetInvitesAsync(RequestOptions options = null) => await ChannelHelper.GetInvitesAsync(this, Discord, options).ConfigureAwait(false); /// - /// Creates an invite for this channel. + /// Creates a new invite to this channel. /// - /// The number of seconds that you want the invite to be valid for. - /// The number of times this invite can be used before it expires. - /// Whether or not the invite grants temporary membership. - /// Whether to try reuse a similar invite or not. + /// 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 a . + /// A task that represents the asynchronous invite creation operation. The task result contains an invite + /// metadata object containing information for the created invite. /// public async Task CreateInviteAsync(int? maxAge = 86400, int? maxUses = null, bool isTemporary = false, bool isUnique = false, RequestOptions options = null) => await ChannelHelper.CreateInviteAsync(this, Discord, maxAge, maxUses, isTemporary, isUnique, options).ConfigureAwait(false); diff --git a/src/Discord.Net.Rest/Entities/Channels/RestTextChannel.cs b/src/Discord.Net.Rest/Entities/Channels/RestTextChannel.cs index b7409c180..93fb116b1 100644 --- a/src/Discord.Net.Rest/Entities/Channels/RestTextChannel.cs +++ b/src/Discord.Net.Rest/Entities/Channels/RestTextChannel.cs @@ -34,6 +34,7 @@ namespace Discord.Rest entity.Update(model); return entity; } + /// internal override void Update(Model model) { base.Update(model); @@ -50,23 +51,31 @@ namespace Discord.Rest } /// - /// Gets a user that is able to view this channel from the associate . + /// Gets a user in this channel. /// - /// The snowflake identifier of the user you want to get. + /// The snowflake identifier of the user. /// The options to be used when sending the request. + /// + /// Resolving permissions requires the parent guild to be downloaded. + /// /// - /// An awaitable containing a . + /// A task representing the asynchronous get operation. The task result contains a guild user object that + /// represents the user; null if none is found. /// public Task GetUserAsync(ulong id, RequestOptions options = null) => ChannelHelper.GetUserAsync(this, Guild, Discord, id, options); /// - /// Gets the collection of users that can view this channel. + /// Gets a collection of users that are able to view the channel. /// /// The options to be used when sending the request. + /// + /// Resolving permissions requires the parent guild to be downloaded. + /// /// - /// Paged collection of users. Flattening the paginated response into a collection of - /// with is required if you wish to access the users. + /// A paged collection containing a collection of guild users that can access this channel. Flattening the + /// paginated response into a collection of users with + /// is required if you wish to access the users. /// public IAsyncEnumerable> GetUsersAsync(RequestOptions options = null) => ChannelHelper.GetUsersAsync(this, Guild, Discord, null, null, options); @@ -147,27 +156,46 @@ namespace Discord.Rest => ChannelHelper.EnterTypingState(this, Discord, options); /// - /// Creates a webhook for this channel. + /// Creates a webhook in this text channel. /// - /// The name you want to give the webhook. - /// The avatar that you want the webook to have. + /// The name of the webhook. + /// The avatar of the webhook. /// The options to be used when sending the request. /// - /// An awaitable containing a . + /// A task that represents the asynchronous creation operation. The task result contains the newly created + /// webhook. /// public Task CreateWebhookAsync(string name, Stream avatar = null, RequestOptions options = null) => ChannelHelper.CreateWebhookAsync(this, Discord, name, avatar, options); + /// + /// Gets a webhook available in this text channel. + /// + /// The identifier of the webhook. + /// The options to be used when sending the request. + /// + /// 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. + /// public Task GetWebhookAsync(ulong id, RequestOptions options = null) => ChannelHelper.GetWebhookAsync(this, Discord, id, options); + /// + /// Gets the webhooks available in this text channel. + /// + /// 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 webhooks that is available in this channel. + /// public Task> GetWebhooksAsync(RequestOptions options = null) => ChannelHelper.GetWebhooksAsync(this, Discord, options); /// - /// Gets the parent category of this channel. + /// Gets the parent (category) channel of this channel. /// /// The options to be used when sending the request. /// - /// An awaitable containing an . + /// A task that represents the asynchronous get operation. The task result contains the category channel + /// representing the parent of this channel; null if none is set. /// public Task GetCategoryAsync(RequestOptions options = null) => ChannelHelper.GetCategoryAsync(this, Discord, options); diff --git a/src/Discord.Net.Rest/Entities/Channels/RestVoiceChannel.cs b/src/Discord.Net.Rest/Entities/Channels/RestVoiceChannel.cs index 6fd068ed1..7f0295c18 100644 --- a/src/Discord.Net.Rest/Entities/Channels/RestVoiceChannel.cs +++ b/src/Discord.Net.Rest/Entities/Channels/RestVoiceChannel.cs @@ -48,11 +48,12 @@ namespace Discord.Rest } /// - /// Gets the parent category of this channel. + /// Gets the parent (category) channel of this channel. /// /// The options to be used when sending the request. /// - /// An awaitable containing an . + /// A task that represents the asynchronous get operation. The task result contains the category channel + /// representing the parent of this channel; null if none is set. /// public Task GetCategoryAsync(RequestOptions options = null) => ChannelHelper.GetCategoryAsync(this, Discord, options); diff --git a/src/Discord.Net.WebSocket/BaseSocketClient.cs b/src/Discord.Net.WebSocket/BaseSocketClient.cs index 429920a15..22a26ba12 100644 --- a/src/Discord.Net.WebSocket/BaseSocketClient.cs +++ b/src/Discord.Net.WebSocket/BaseSocketClient.cs @@ -16,33 +16,60 @@ namespace Discord.WebSocket /// /// Gets the estimated round-trip latency, in milliseconds, to the gateway server. /// + /// + /// An that represents the round-trip latency to the WebSocket server. Please + /// note that this value does not represent a "true" latency for operations such as sending a message. + /// public abstract int Latency { get; protected set; } /// /// Gets the status for the logged-in user. /// + /// + /// A status object that represents the user's online presence status. + /// public abstract UserStatus Status { get; protected set; } /// /// Gets the activity for the logged-in user. /// + /// + /// An activity object that represents the user's current activity. + /// public abstract IActivity Activity { get; protected set; } internal new DiscordSocketApiClient ApiClient => base.ApiClient as DiscordSocketApiClient; /// - /// Gets the current logged-in user. + /// Gets the current logged-in user. /// public new SocketSelfUser CurrentUser { get => base.CurrentUser as SocketSelfUser; protected set => base.CurrentUser = value; } /// - /// Gets a collection of guilds that the logged-in user is currently in. + /// Gets a collection of guilds that the user is currently in. /// + /// + /// A read-only collection of guilds that the current user is in. + /// public abstract IReadOnlyCollection Guilds { get; } /// - /// Gets a collection of private channels that are currently open for the logged-in user. + /// Gets a collection of private channels opened in this session. /// + /// + /// This method will retrieve all private channels (including direct-message, group channel and such) that + /// are currently opened in this session. + /// + /// This method will not return previously opened private channels outside of the current session! If + /// you have just started the client, this may return an empty collection. + /// + /// + /// + /// A read-only collection of private channels that the user currently partakes in. + /// public abstract IReadOnlyCollection PrivateChannels { get; } /// - /// Gets a collection of available voice regions for the logged-in user. + /// Gets a collection of available voice regions. /// + /// + /// A read-only collection of voice regions that the user has access to. + /// public abstract IReadOnlyCollection VoiceRegions { get; } internal BaseSocketClient(DiscordSocketConfig config, DiscordRestApiClient client) @@ -59,7 +86,8 @@ namespace Discord.WebSocket /// /// The options to be used when sending the request. /// - /// An awaitable containing the application information. + /// A task that represents the asynchronous get operation. The task result contains the application + /// information. /// public abstract Task GetApplicationInfoAsync(RequestOptions options = null); /// @@ -107,7 +135,7 @@ namespace Discord.WebSocket /// /// Gets a channel. /// - /// The channel snowflake identifier. + /// The snowflake identifier of the channel (e.g. `381889909113225237`). /// /// A generic WebSocket-based channel object (voice, text, category, etc.) associated with the identifier; /// null when the channel cannot be found. @@ -125,9 +153,10 @@ namespace Discord.WebSocket /// /// Gets a voice region. /// - /// The unique identifier of the voice region. + /// The identifier of the voice region (e.g. eu-central ). /// - /// A REST-based voice region; null if none can be found. + /// A REST-based voice region associated with the identifier; null if the voice region is not + /// found. /// public abstract RestVoiceRegion GetVoiceRegion(string id); /// @@ -135,21 +164,21 @@ namespace Discord.WebSocket /// public abstract Task StopAsync(); /// - /// Sets the current status of the logged-in user (e.g. Online, Do not Disturb). + /// Sets the current status of the user (e.g. Online, Do not Disturb). /// /// The new status to be set. /// - /// An awaitable . + /// A task that represents the asynchronous set operation. /// public abstract Task SetStatusAsync(UserStatus status); /// - /// Sets the game of the logged-in user. + /// Sets the game of the user. /// /// The name of the game. /// If streaming, the URL of the stream. Must be a valid Twitch URL. /// The type of the game. /// - /// An awaitable . + /// A task that represents the asynchronous set operation. /// public abstract Task SetGameAsync(string name, string streamUrl = null, ActivityType type = ActivityType.Playing); /// @@ -167,7 +196,7 @@ namespace Discord.WebSocket /// /// The activty to be set. /// - /// An awaitable . + /// A task that represents the asynchronous set operation. /// public abstract Task SetActivityAsync(IActivity activity); /// @@ -175,7 +204,7 @@ namespace Discord.WebSocket /// /// The guilds to download the members from. /// - /// An awaitable . + /// A task that represents the asynchronous download operation. /// public abstract Task DownloadUsersAsync(IEnumerable guilds); @@ -193,26 +222,26 @@ namespace Discord.WebSocket /// The icon of the guild. /// The options to be used when sending the request. /// - /// An awaitable containing the newly created guild. + /// A task that represents the asynchronous creation operation. The task result contains the created guild. /// public Task CreateGuildAsync(string name, IVoiceRegion region, Stream jpegIcon = null, RequestOptions options = null) => ClientHelper.CreateGuildAsync(this, name, region, jpegIcon, options ?? RequestOptions.Default); /// - /// Gets the connections that the logged-in user has set up. + /// Gets the connections that the user has set up. /// /// The options to be used when sending the request. /// - /// An awaitable containing a collection of connections. + /// A task that represents the asynchronous get operation. The task result contains a read-only collection of connections. /// public Task> GetConnectionsAsync(RequestOptions options = null) => ClientHelper.GetConnectionsAsync(this, options ?? RequestOptions.Default); /// - /// Gets an invite with the provided invite identifier. + /// Gets an invite. /// /// The invitation identifier. /// The options to be used when sending the request. /// - /// An awaitable containing the invite information. + /// A task that represents the asynchronous get operation. The task result contains the invite information. /// public Task GetInviteAsync(string inviteId, RequestOptions options = null) => ClientHelper.GetInviteAsync(this, inviteId, options ?? RequestOptions.Default); diff --git a/src/Discord.Net.WebSocket/Entities/Channels/ISocketMessageChannel.cs b/src/Discord.Net.WebSocket/Entities/Channels/ISocketMessageChannel.cs index 73fc3c34c..42ac984c4 100644 --- a/src/Discord.Net.WebSocket/Entities/Channels/ISocketMessageChannel.cs +++ b/src/Discord.Net.WebSocket/Entities/Channels/ISocketMessageChannel.cs @@ -14,7 +14,7 @@ namespace Discord.WebSocket /// Gets all messages in this channel's cache. /// /// - /// A collection of WebSocket-based messages. + /// A read-only collection of WebSocket-based messages. /// IReadOnlyCollection CachedMessages { get; } @@ -22,46 +22,55 @@ namespace Discord.WebSocket /// 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 asynchronous send operation for delievering the message. The task result + /// contains the sent message. /// new 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. + /// 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 asynchronous send operation for delievering the message. The task result + /// contains the sent message. /// new 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. + /// 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 Task containing the message sent to the channel. + /// A task that represents an asynchronous send operation for delievering the message. The task result + /// contains the sent message. /// new Task SendFileAsync(Stream stream, string filename, string text = null, bool isTTS = false, Embed embed = null, RequestOptions options = null); @@ -78,7 +87,7 @@ namespace Discord.WebSocket /// /// The number of messages to get. /// - /// A collection of WebSocket-based messages. + /// A read-only collection of WebSocket-based messages. /// IReadOnlyCollection GetCachedMessages(int limit = DiscordConfig.MaxMessagesPerBatch); @@ -89,7 +98,7 @@ namespace Discord.WebSocket /// The direction of which the message should be gotten from. /// The number of messages to get. /// - /// A collection of WebSocket-based messages. + /// A read-only collection of WebSocket-based messages. /// IReadOnlyCollection GetCachedMessages(ulong fromMessageId, Direction dir, int limit = DiscordConfig.MaxMessagesPerBatch); /// @@ -99,7 +108,7 @@ namespace Discord.WebSocket /// The direction of which the message should be gotten from. /// The number of messages to get. /// - /// A collection of WebSocket-based messages. + /// A read-only collection of WebSocket-based messages. /// IReadOnlyCollection GetCachedMessages(IMessage fromMessage, Direction dir, int limit = DiscordConfig.MaxMessagesPerBatch); /// @@ -107,7 +116,8 @@ namespace Discord.WebSocket /// /// The options to be used when sending the request. /// - /// 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. /// new Task> GetPinnedMessagesAsync(RequestOptions options = null); } diff --git a/src/Discord.Net.WebSocket/Entities/Channels/SocketGuildChannel.cs b/src/Discord.Net.WebSocket/Entities/Channels/SocketGuildChannel.cs index d9b4e494c..d86e5ff9b 100644 --- a/src/Discord.Net.WebSocket/Entities/Channels/SocketGuildChannel.cs +++ b/src/Discord.Net.WebSocket/Entities/Channels/SocketGuildChannel.cs @@ -21,7 +21,7 @@ namespace Discord.WebSocket /// Gets the guild associated with this channel. /// /// - /// A guild that this channel belongs to. + /// A guild object that this channel belongs to. /// public SocketGuild Guild { get; } /// @@ -35,7 +35,7 @@ namespace Discord.WebSocket /// Gets a collection of users that are able to view the channel. /// /// - /// A collection of users that can access the channel (i.e. the users seen in the user list). + /// A read-only collection of users that can access the channel (i.e. the users seen in the user list). /// public new virtual IReadOnlyCollection Users => ImmutableArray.Create(); @@ -59,6 +59,7 @@ namespace Discord.WebSocket return new SocketGuildChannel(guild.Discord, model.Id, guild); } } + /// internal override void Update(ClientState state, Model model) { Name = model.Name.Value; @@ -79,11 +80,11 @@ namespace Discord.WebSocket => ChannelHelper.DeleteAsync(this, Discord, options); /// - /// Gets the overwrite permissions of the specified . + /// Gets the permission overwrite for a specific user. /// - /// The user that you want to get the overwrite permissions for. + /// The user to get the overwrite from. /// - /// The overwrite permissions for the requested user; otherwise null. + /// An overwrite object for the targeted user; null if none is set. /// public OverwritePermissions? GetPermissionOverwrite(IUser user) { @@ -94,13 +95,12 @@ namespace Discord.WebSocket } return null; } - /// - /// Gets the overwrite permissions of the specified . + /// Gets the permission overwrite for a specific role. /// - /// The role that you want to get the overwrite permissions for. + /// The role to get the overwrite from. /// - /// The overwrite permissions for the requested role; otherwise null. + /// An overwrite object for the targeted role; null if none is set. /// public OverwritePermissions? GetPermissionOverwrite(IRole role) { @@ -113,41 +113,41 @@ namespace Discord.WebSocket } /// - /// Adds an overwrite permission for the specified . + /// Adds or updates the permission overwrite for the given user. /// - /// The user you want the overwrite permission to apply to. - /// The overwrite permission you want to add. + /// The user to add the overwrite to. + /// The overwrite to add to the user. /// The options to be used when sending the request. /// - /// An awaitable . + /// A task representing the asynchronous permission operation for adding the specified permissions to the channel. /// - public async Task AddPermissionOverwriteAsync(IUser user, OverwritePermissions perms, RequestOptions options = null) + public async Task AddPermissionOverwriteAsync(IUser user, OverwritePermissions permissions, RequestOptions options = null) { - await ChannelHelper.AddPermissionOverwriteAsync(this, Discord, user, perms, options).ConfigureAwait(false); - _overwrites = _overwrites.Add(new Overwrite(user.Id, PermissionTarget.User, new OverwritePermissions(perms.AllowValue, perms.DenyValue))); + await ChannelHelper.AddPermissionOverwriteAsync(this, Discord, user, permissions, options).ConfigureAwait(false); + _overwrites = _overwrites.Add(new Overwrite(user.Id, PermissionTarget.User, new OverwritePermissions(permissions.AllowValue, permissions.DenyValue))); } /// - /// Adds an overwrite permission for the specified . + /// Adds or updates the permission overwrite for the given role. /// - /// The role you want the overwrite permission to apply to. - /// The overwrite permission you want to add. - /// The options to be used when sending the request. + /// The role to add the overwrite to. + /// The overwrite to add to the role. + /// The options to be used when sending the request. /// - /// An awaitable . + /// A task representing the asynchronous permission operation for adding the specified permissions to the channel. /// - public async Task AddPermissionOverwriteAsync(IRole role, OverwritePermissions perms, RequestOptions options = null) + public async Task AddPermissionOverwriteAsync(IRole role, OverwritePermissions permissions, RequestOptions options = null) { - await ChannelHelper.AddPermissionOverwriteAsync(this, Discord, role, perms, options).ConfigureAwait(false); - _overwrites = _overwrites.Add(new Overwrite(role.Id, PermissionTarget.Role, new OverwritePermissions(perms.AllowValue, perms.DenyValue))); + await ChannelHelper.AddPermissionOverwriteAsync(this, Discord, role, permissions, options).ConfigureAwait(false); + _overwrites = _overwrites.Add(new Overwrite(role.Id, PermissionTarget.Role, new OverwritePermissions(permissions.AllowValue, permissions.DenyValue))); } /// - /// Removes an overwrite permission for the specified . + /// Removes the permission overwrite for the given user, if one exists. /// - /// The user you want to remove the overwrite permission from. + /// The user to remove the overwrite from. /// The options to be used when sending the request. /// - /// An awaitable . + /// A task representing the asynchronous operation for removing the specified permissions from the channel. /// public async Task RemovePermissionOverwriteAsync(IUser user, RequestOptions options = null) { @@ -163,12 +163,12 @@ namespace Discord.WebSocket } } /// - /// Removes an overwrite permission for the specified . + /// Removes the permission overwrite for the given role, if one exists. /// - /// The role you want the overwrite permissions to be removed from. + /// The role to remove the overwrite from. /// The options to be used when sending the request. /// - /// An awaitable . + /// A task representing the asynchronous operation for removing the specified permissions from the channel. /// public async Task RemovePermissionOverwriteAsync(IRole role, RequestOptions options = null) { @@ -185,26 +185,26 @@ namespace Discord.WebSocket } /// - /// Gets the invites for this channel. + /// Returns a collection of all invites to this channel. /// /// The options to be used when sending the request. /// - /// An awaitable containing an . - /// contains information such as, the number of times the invite has - /// been used, who created the invite, and when the invite was created. + /// 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. /// public async Task> GetInvitesAsync(RequestOptions options = null) => await ChannelHelper.GetInvitesAsync(this, Discord, options).ConfigureAwait(false); /// - /// Creates an invite for this channel. + /// Creates a new invite to this channel. /// - /// The number of seconds that you want the invite to be valid for. - /// The number of times this invite can be used before it expires. - /// Whether or not the invite grants temporary membership. - /// Whether to try reuse a similar invite or not. + /// 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 a . + /// A task that represents the asynchronous invite creation operation. The task result contains an invite + /// metadata object containing information for the created invite. /// public async Task CreateInviteAsync(int? maxAge = 86400, int? maxUses = null, bool isTemporary = false, bool isUnique = false, RequestOptions options = null) => await ChannelHelper.CreateInviteAsync(this, Discord, maxAge, maxUses, isTemporary, isUnique, options).ConfigureAwait(false); @@ -214,12 +214,18 @@ namespace Discord.WebSocket /// /// Gets the name of the channel. /// + /// + /// A string that resolves to . + /// public override string ToString() => Name; private string DebuggerDisplay => $"{Name} ({Id}, Guild)"; + /// internal new SocketGuildChannel Clone() => MemberwiseClone() as SocketGuildChannel; //SocketChannel + /// internal override IReadOnlyCollection GetUsersInternal() => Users; + /// internal override SocketUser GetUserInternal(ulong id) => GetUser(id); //IGuildChannel diff --git a/src/Discord.Net.WebSocket/Entities/Channels/SocketTextChannel.cs b/src/Discord.Net.WebSocket/Entities/Channels/SocketTextChannel.cs index f77dedb3e..52cc02d50 100644 --- a/src/Discord.Net.WebSocket/Entities/Channels/SocketTextChannel.cs +++ b/src/Discord.Net.WebSocket/Entities/Channels/SocketTextChannel.cs @@ -76,11 +76,11 @@ namespace Discord.WebSocket /// /// Gets a message from this message channel. /// - /// The ID of the message. + /// The snowflake identifier of the message. /// The options to be used when sending the request. /// - /// An awaitable containing the downloaded message; 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. /// public async Task GetMessageAsync(ulong id, RequestOptions options = null) { @@ -202,7 +202,8 @@ namespace Discord.WebSocket /// 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. /// public Task CreateWebhookAsync(string name, Stream avatar = null, RequestOptions options = null) => ChannelHelper.CreateWebhookAsync(this, Discord, name, avatar, options); @@ -212,8 +213,8 @@ namespace Discord.WebSocket /// 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. /// public Task GetWebhookAsync(ulong id, RequestOptions options = null) => ChannelHelper.GetWebhookAsync(this, Discord, id, options); @@ -222,7 +223,8 @@ namespace Discord.WebSocket /// /// 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. /// public Task> GetWebhooksAsync(RequestOptions options = null) => ChannelHelper.GetWebhooksAsync(this, Discord, options); diff --git a/src/Discord.Net.WebSocket/Entities/Channels/SocketVoiceChannel.cs b/src/Discord.Net.WebSocket/Entities/Channels/SocketVoiceChannel.cs index 3d466aff5..9bf79cdd5 100644 --- a/src/Discord.Net.WebSocket/Entities/Channels/SocketVoiceChannel.cs +++ b/src/Discord.Net.WebSocket/Entities/Channels/SocketVoiceChannel.cs @@ -23,10 +23,10 @@ namespace Discord.WebSocket /// public ulong? CategoryId { get; private set; } /// - /// Gets the parent (category) of this channel in the guild's channel list. + /// Gets the parent (category) channel of this channel. /// /// - /// An representing the parent of this channel; null if none is set. + /// A category channel representing the parent of this channel; null if none is set. /// public ICategoryChannel Category => CategoryId.HasValue ? Guild.GetChannel(CategoryId.Value) as ICategoryChannel : null; @@ -45,6 +45,7 @@ namespace Discord.WebSocket entity.Update(state, model); return entity; } + /// internal override void Update(ClientState state, Model model) { base.Update(state, model); @@ -63,12 +64,7 @@ namespace Discord.WebSocket return await Guild.ConnectAudioAsync(Id, selfDeaf, selfMute, external).ConfigureAwait(false); } - /// - /// Disconnects from this voice channel if the client is in an active voice connection. - /// - /// - /// An awaitable . - /// + /// public async Task DisconnectAsync() => await Guild.DisconnectAudioAsync(); diff --git a/src/Discord.Net.WebSocket/Entities/Guilds/SocketGuild.cs b/src/Discord.Net.WebSocket/Entities/Guilds/SocketGuild.cs index c095f0e03..400fbb75c 100644 --- a/src/Discord.Net.WebSocket/Entities/Guilds/SocketGuild.cs +++ b/src/Discord.Net.WebSocket/Entities/Guilds/SocketGuild.cs @@ -738,21 +738,23 @@ namespace Discord.WebSocket //Webhooks /// - /// Returns the webhook with the provided ID. + /// Gets a webhook found within this guild. /// - /// The ID of the webhook. + /// The identifier for the webhook. /// The options to be used when sending the request. /// - /// An awaitable containing the webhook associated with the ID. + /// A task that represents the asynchronous get operation. The task result contains the webhook with the + /// specified ; null if none is found. /// public Task GetWebhookAsync(ulong id, RequestOptions options = null) => GuildHelper.GetWebhookAsync(this, Discord, id, options); /// - /// Gets a collection of webhooks that exist in the guild. + /// Gets a collection of all webhook from this guild. /// /// The options to be used when sending the request. /// - /// An awaitable containing a collection of webhooks. + /// A task that represents the asynchronous get operation. The task result contains a read-only collection + /// of webhooks found within the guild. /// public Task> GetWebhooksAsync(RequestOptions options = null) => GuildHelper.GetWebhooksAsync(this, Discord, options);