From 535746fb20f42f803c4739d11fb9a8e78dd958a5 Mon Sep 17 00:00:00 2001
From: Still Hsu <341464@gmail.com>
Date: Sat, 14 Jul 2018 02:55:45 +0800
Subject: [PATCH] Add XML docs
---
src/Discord.Net.Commands/CommandService.cs | 61 ++++---
.../CommandServiceConfig.cs | 4 +-
.../Readers/TypeReader.cs | 2 +-
.../Entities/Channels/IAudioChannel.cs | 2 +-
.../Entities/Channels/IGuildChannel.cs | 26 ++-
.../Entities/Channels/IMessageChannel.cs | 8 +-
.../Entities/Channels/INestedChannel.cs | 2 +-
.../Entities/Channels/ITextChannel.cs | 2 +-
src/Discord.Net.Core/Entities/Emotes/Emoji.cs | 2 +-
.../Entities/Emotes/GuildEmote.cs | 3 +
.../Entities/Guilds/IGuild.cs | 2 +-
.../Entities/Guilds/IVoiceRegion.cs | 30 +++-
.../Entities/Invites/IInviteMetadata.cs | 5 +-
.../Entities/Messages/EmbedBuilder.cs | 2 +-
.../Entities/Messages/EmbedField.cs | 5 +-
.../Entities/Messages/IMessage.cs | 20 ++-
.../Entities/Messages/IUserMessage.cs | 29 +++-
src/Discord.Net.Core/Entities/Roles/IRole.cs | 8 +-
src/Discord.Net.Core/Entities/Users/IUser.cs | 16 +-
.../Extensions/UserExtensions.cs | 15 +-
src/Discord.Net.Core/IDiscordClient.cs | 159 +++++++++++++-----
src/Discord.Net.Core/Utils/Cacheable.cs | 6 +-
src/Discord.Net.Rest/BaseDiscordClient.cs | 4 +-
.../DataTypes/InviteCreateAuditLogData.cs | 3 +-
.../DataTypes/InviteDeleteAuditLogData.cs | 3 +-
.../AuditLogs/DataTypes/InviteInfo.cs | 3 +-
.../AuditLogs/DataTypes/MemberRoleEditInfo.cs | 2 +-
.../AuditLogs/DataTypes/RoleEditInfo.cs | 13 +-
.../Entities/Channels/IRestMessageChannel.cs | 60 ++++---
.../Entities/Channels/RestGuildChannel.cs | 76 ++++-----
.../Entities/Channels/RestTextChannel.cs | 52 ++++--
.../Entities/Channels/RestVoiceChannel.cs | 5 +-
src/Discord.Net.WebSocket/BaseSocketClient.cs | 67 +++++---
.../Channels/ISocketMessageChannel.cs | 60 ++++---
.../Entities/Channels/SocketGuildChannel.cs | 86 +++++-----
.../Entities/Channels/SocketTextChannel.cs | 16 +-
.../Entities/Channels/SocketVoiceChannel.cs | 12 +-
.../Entities/Guilds/SocketGuild.cs | 12 +-
38 files changed, 550 insertions(+), 333 deletions(-)
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);