Add XML docs

src/Discord.Net.Commands/CommandService.cs

@@ -130,33 +130,33 @@ namespace Discord.Commands
         }
 
         /// <summary>
-        ///     Add a command module from a <see cref="Type"/>.
+        ///     Add a command module from a <see cref="Type" /> .
         /// </summary>
         /// <typeparam name="T">The type of module.</typeparam>
-        /// <param name="services">
-        ///     The <see cref="IServiceProvider"/> for your dependency injection solution if using one; otherwise, pass
-        ///     <c>null</c>.
-        /// </param>
+        /// <param name="services">The <see cref="IServiceProvider" /> for your dependency injection solution if using one; otherwise, pass <c>null</c> .</param>
+        /// <exception cref="ArgumentException">This module has already been added.</exception>
+        /// <exception cref="InvalidOperationException">
+        /// The <see cref="ModuleInfo"/> fails to be built; an invalid type may have been provided.
+        /// </exception>
         /// <returns>
-        ///     An awaitable <see cref="Task"/> containing the built module.
+        ///     A task that represents the asynchronous operation for adding the module. The task result contains the
+        ///     built module.
         /// </returns>
-        /// <exception cref="ArgumentException">This module has already been added.</exception>
-        /// <exception cref="InvalidOperationException">The <see cref="ModuleInfo"/> fails to be built; an invalid type may have been provided.</exception>
         public Task<ModuleInfo> AddModuleAsync<T>(IServiceProvider services) => AddModuleAsync(typeof(T), services);
 
         /// <summary>
-        ///     Adds a command module from a <see cref="Type"/>.
+        ///     Adds a command module from a <see cref="Type" /> .
         /// </summary>
         /// <param name="type">The type of module.</param>
-        /// <param name="services">
-        ///     The <see cref="IServiceProvider"/> for your dependency injection solution if using one; otherwise, pass
-        ///     <c>null</c>.
-        /// </param>
+        /// <param name="services">The <see cref="IServiceProvider" /> for your dependency injection solution if using one; otherwise, pass <c>null</c> .</param>
+        /// <exception cref="ArgumentException">This module has already been added.</exception>
+        /// <exception cref="InvalidOperationException">
+        /// The <see cref="ModuleInfo"/> fails to be built; an invalid type may have been provided.
+        /// </exception>
         /// <returns>
-        ///     An awaitable <see cref="Task"/> containing the built module.
+        ///     A task that represents the asynchronous operation for adding the module. The task result contains the
+        ///     built module.
         /// </returns>
-        /// <exception cref="ArgumentException">This module has already been added.</exception>
-        /// <exception cref="InvalidOperationException">The <see cref="ModuleInfo"/> fails to be built; an invalid type may have been provided.</exception>
         public async Task<ModuleInfo> AddModuleAsync(Type type, IServiceProvider services)
         {
             services = services ?? EmptyServiceProvider.Instance;
@@ -186,13 +186,11 @@ namespace Discord.Commands
         /// <summary>
         ///     Add command modules from an <see cref="Assembly"/>.
         /// </summary>
-        /// <param name="assembly">The <see cref="Assembly" /> containing command modules.</param>
-        /// <param name="services">
-        ///     The <see cref="IServiceProvider"/> for your dependency injection solution if using one; otherwise, pass
-        ///     <c>null</c>.
-        /// </param>
+        /// <param name="assembly">The <see cref="Assembly"/> containing command modules.</param>
+        /// <param name="services">The <see cref="IServiceProvider"/> for your dependency injection solution if using one; otherwise, pass <c>null</c>.</param>
         /// <returns>
-        ///     An awaitable <see cref="Task"/> 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.
         /// </returns>
         public async Task<IEnumerable<ModuleInfo>> AddModulesAsync(Assembly assembly, IServiceProvider services)
         {
@@ -234,7 +232,8 @@ namespace Discord.Commands
         /// </summary>
         /// <param name="module">The <see cref="ModuleInfo" /> to be removed from the service.</param>
         /// <returns>
-        ///     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 <paramref name="module"/> is successfully removed.
         /// </returns>
         public async Task<bool> RemoveModuleAsync(ModuleInfo module)
         {
@@ -253,7 +252,8 @@ namespace Discord.Commands
         /// </summary>
         /// <typeparam name="T">The <see cref="Type"/> of the module.</typeparam>
         /// <returns>
-        ///     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.
         /// </returns>
         public Task<bool> RemoveModuleAsync<T>() => RemoveModuleAsync(typeof(T));
         /// <summary>
@@ -261,7 +261,8 @@ namespace Discord.Commands
         /// </summary>
         /// <param name="type">The <see cref="Type"/> of the module.</param>
         /// <returns>
-        ///     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.
         /// </returns>
         public async Task<bool> RemoveModuleAsync(Type type)
         {
@@ -455,7 +456,10 @@ namespace Discord.Commands
         /// <param name="argPos">The position of which the command starts at.</param>
         /// <param name="services">The service to be used in the command's dependency injection.</param>
         /// <param name="multiMatchHandling">The handling mode when multiple command matches are found.</param>
-        /// <returns>The result of the command execution.</returns>
+        /// <returns>
+        ///     A task that represents the asynchronous execution operation. The task result contains the result of the
+        ///     command execution.
+        /// </returns>
         public Task<IResult> ExecuteAsync(ICommandContext context, int argPos, IServiceProvider services, MultiMatchHandling multiMatchHandling = MultiMatchHandling.Exception)
             => ExecuteAsync(context, context.Message.Content.Substring(argPos), services, multiMatchHandling);
         /// <summary>
@@ -465,7 +469,10 @@ namespace Discord.Commands
         /// <param name="input">The command string.</param>
         /// <param name="services">The service to be used in the command's dependency injection.</param>
         /// <param name="multiMatchHandling">The handling mode when multiple command matches are found.</param>
-        /// <returns>The result of the command execution.</returns>
+        /// <returns>
+        ///     A task that represents the asynchronous execution operation. The task result contains the result of the
+        ///     command execution.
+        /// </returns>
         public async Task<IResult> ExecuteAsync(ICommandContext context, string input, IServiceProvider services, MultiMatchHandling multiMatchHandling = MultiMatchHandling.Exception)
         {
             services = services ?? EmptyServiceProvider.Instance;

src/Discord.Net.Commands/CommandServiceConfig.cs

@@ -55,7 +55,9 @@ namespace Discord.Commands
         /// </example>
         public Dictionary<char, char> QuotationMarkAliasMap { get; set; } = QuotationAliasUtils.GetDefaultAliasMap;
 
-        /// <summary> Determines whether extra parameters should be ignored. </summary>
+        /// <summary>
+        ///     Gets or sets a value that indicates whether extra parameters should be ignored.
+        /// </summary>
         public bool IgnoreExtraArgs { get; set; } = false;
     }
 }

src/Discord.Net.Commands/Readers/TypeReader.cs

@@ -15,7 +15,7 @@ namespace Discord.Commands
         /// <param name="input">The raw input of the command.</param>
         /// <param name="services">The service collection used for dependency injection.</param>
         /// <returns>
-        ///     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.
         /// </returns>
         public abstract Task<TypeReaderResult> ReadAsync(ICommandContext context, string input, IServiceProvider services);
     }

src/Discord.Net.Core/Entities/Channels/IAudioChannel.cs

@@ -25,7 +25,7 @@ namespace Discord
         ///     Disconnects from this audio channel.
         /// </summary>
         /// <returns>
-        ///     A task representing the asynchronous disconnection operation.
+        ///     A task representing the asynchronous operation for disconnecting from the audio channel.
         /// </returns>
         Task DisconnectAsync();
     }

src/Discord.Net.Core/Entities/Channels/IGuildChannel.cs

@@ -58,7 +58,7 @@ namespace Discord
         /// </returns>
         Task<IInviteMetadata> CreateInviteAsync(int? maxAge = 86400, int? maxUses = default(int?), bool isTemporary = false, bool isUnique = false, RequestOptions options = null);
         /// <summary>
-        ///     Returns a collection of all invites to this channel.
+        ///     Gets a collection of all invites to this channel.
         /// </summary>
         /// <param name="options">The options to be used when sending the request.</param>
         /// <returns>
@@ -78,7 +78,7 @@ namespace Discord
         Task ModifyAsync(Action<GuildChannelProperties> func, RequestOptions options = null);
 
         /// <summary>
-        ///     Gets the permission overwrite for a specific role, or <c>null</c> if one does not exist.
+        ///     Gets the permission overwrite for a specific role.
         /// </summary>
         /// <param name="role">The role to get the overwrite from.</param>
         /// <returns>
@@ -86,7 +86,7 @@ namespace Discord
         /// </returns>
         OverwritePermissions? GetPermissionOverwrite(IRole role);
         /// <summary>
-        ///     Gets the permission overwrite for a specific user, or <c>null</c> if one does not exist.
+        ///     Gets the permission overwrite for a specific user.
         /// </summary>
         /// <param name="user">The user to get the overwrite from.</param>
         /// <returns>
@@ -99,7 +99,7 @@ namespace Discord
         /// <param name="role">The role to remove the overwrite from.</param>
         /// <param name="options">The options to be used when sending the request.</param>
         /// <returns>
-        ///     A task representing the asynchronous removal operation.
+        ///     A task representing the asynchronous operation for removing the specified permissions from the channel.
         /// </returns>
         Task RemovePermissionOverwriteAsync(IRole role, RequestOptions options = null);
         /// <summary>
@@ -108,7 +108,7 @@ namespace Discord
         /// <param name="user">The user to remove the overwrite from.</param>
         /// <param name="options">The options to be used when sending the request.</param>
         /// <returns>
-        ///     A task representing the asynchronous removal operation.
+        ///     A task representing the asynchronous operation for removing the specified permissions from the channel.
         /// </returns>
         Task RemovePermissionOverwriteAsync(IUser user, RequestOptions options = null);
 
@@ -119,7 +119,7 @@ namespace Discord
         /// <param name="permissions">The overwrite to add to the role.</param>
         /// <param name="options">The options to be used when sending the request.</param>
         /// <returns>
-        ///     A task representing the asynchronous permission addition operation.
+        ///     A task representing the asynchronous permission operation for adding the specified permissions to the channel.
         /// </returns>
         Task AddPermissionOverwriteAsync(IRole role, OverwritePermissions permissions, RequestOptions options = null);
         /// <summary>
@@ -129,16 +129,14 @@ namespace Discord
         /// <param name="permissions">The overwrite to add to the user.</param>
         /// <param name="options">The options to be used when sending the request.</param>
         /// <returns>
-        ///     A task representing the asynchronous permission addition operation.
+        ///     A task representing the asynchronous permission operation for adding the specified permissions to the channel.
         /// </returns>
         Task AddPermissionOverwriteAsync(IUser user, OverwritePermissions permissions, RequestOptions options = null);
 
         /// <summary>
-        ///     Gets a collection of all users in this channel.
+        ///     Gets a collection of users that are able to view the channel.
         /// </summary>
-        /// <param name="mode">
-        /// The <see cref="CacheMode" /> that determines whether the object should be fetched from cache.
-        /// </param>
+        /// <param name="mode">The <see cref="CacheMode" /> that determines whether the object should be fetched from cache.</param>
         /// <param name="options">The options to be used when sending the request.</param>
         /// <returns>
         ///     A paged collection containing a collection of guild users that can access this channel. Flattening the
@@ -147,13 +145,13 @@ namespace Discord
         /// </returns>
         new IAsyncEnumerable<IReadOnlyCollection<IGuildUser>> GetUsersAsync(CacheMode mode = CacheMode.AllowDownload, RequestOptions options = null);
         /// <summary>
-        ///     Gets a user in this channel with the provided ID.
+        ///     Gets a user in this channel.
         /// </summary>
-        /// <param name="id">The ID of the user.</param>
+        /// <param name="id">The snowflake identifier of the user.</param>
         /// <param name="mode">The <see cref="CacheMode"/> that determines whether the object should be fetched from cache.</param>
         /// <param name="options">The options to be used when sending the request.</param>
         /// <returns>
-        ///     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; <c>null</c> if none is found.
         /// </returns>
         new Task<IGuildUser> GetUserAsync(ulong id, CacheMode mode = CacheMode.AllowDownload, RequestOptions options = null);

src/Discord.Net.Core/Entities/Channels/IMessageChannel.cs

@@ -18,7 +18,7 @@ namespace Discord
         /// <param name="embed">The <see cref="Discord.EmbedType.Rich"/> <see cref="Embed"/> to be sent.</param>
         /// <param name="options">The options to be used when sending the request.</param>
         /// <returns>
-        ///     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.
         /// </returns>
         Task<IUserMessage> SendMessageAsync(string text = null, bool isTTS = false, Embed embed = null, RequestOptions options = null);
@@ -39,7 +39,7 @@ namespace Discord
         /// <param name="embed">The <see cref="Discord.EmbedType.Rich" /> <see cref="Embed" /> to be sent.</param>
         /// <param name="options">The options to be used when sending the request.</param>
         /// <returns>
-        ///     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.
         /// </returns>
         Task<IUserMessage> SendFileAsync(string filePath, string text = null, bool isTTS = false, Embed embed = null, RequestOptions options = null);
@@ -61,7 +61,7 @@ namespace Discord
         /// <param name="embed">The <see cref="Discord.EmbedType.Rich"/> <see cref="Embed"/> to be sent.</param>
         /// <param name="options">The options to be used when sending the request.</param>
         /// <returns>
-        ///     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.
         /// </returns>
         Task<IUserMessage> SendFileAsync(Stream stream, string filename, string text = null, bool isTTS = false, Embed embed = null, RequestOptions options = null);
@@ -73,7 +73,7 @@ namespace Discord
         /// <param name="mode">The <see cref="CacheMode"/> that determines whether the object should be fetched from cache.</param>
         /// <param name="options">The options to be used when sending the request.</param>
         /// <returns>
-        ///     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; <c>null</c> if no message is found with the specified identifier.
         /// </returns>
         Task<IMessage> GetMessageAsync(ulong id, CacheMode mode = CacheMode.AllowDownload, RequestOptions options = null);

src/Discord.Net.Core/Entities/Channels/INestedChannel.cs

@@ -21,7 +21,7 @@ namespace Discord
         /// <param name="mode">The <see cref="CacheMode"/> that determines whether the object should be fetched from cache.</param>
         /// <param name="options">The options to be used when sending the request.</param>
         /// <returns>
-        ///     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; <c>null</c> if none is set.
         /// </returns>
         Task<ICategoryChannel> GetCategoryAsync(CacheMode mode = CacheMode.AllowDownload, RequestOptions options = null);

src/Discord.Net.Core/Entities/Channels/ITextChannel.cs

@@ -11,7 +11,7 @@ namespace Discord
     public interface ITextChannel : IMessageChannel, IMentionable, INestedChannel
     {
         /// <summary>
-        ///     Determines whether the channel is NSFW.
+        ///     Gets a value that indicates whether the channel is NSFW.
         /// </summary>
         /// <returns>
         ///     <c>true</c> if the channel has the NSFW flag enabled; otherwise <c>false</c>.

src/Discord.Net.Core/Entities/Emotes/Emoji.cs

@@ -27,7 +27,7 @@ namespace Discord
         }
 
         /// <summary>
-        ///     Determines whether the specified emoji is equal to the current emoji.
+        ///     Determines whether the specified emoji is equal to the current one.
         /// </summary>
         /// <param name="other">The object to compare with the current object.</param>
         public override bool Equals(object other)

src/Discord.Net.Core/Entities/Emotes/GuildEmote.cs

@@ -42,6 +42,9 @@ namespace Discord
         /// <summary>
         ///     Gets the raw representation of the emote.
         /// </summary>
+        /// <returns>
+        ///     A string representing the raw presentation of the emote (e.g. <c>&lt;:thonkang:282745590985523200&gt;</c>).
+        /// </returns>
         public override string ToString() => $"<{(Animated ? "a" : "")}:{Name}:{Id}>";
     }
 }

src/Discord.Net.Core/Entities/Guilds/IGuild.cs

@@ -27,7 +27,7 @@ namespace Discord
         /// </returns>
         int AFKTimeout { get; }
         /// <summary>
-        ///     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).
         /// </summary>
         /// <returns>
         ///     <c>true</c> if this guild can be embedded via widgets; otherwise <c>false</c>.

src/Discord.Net.Core/Entities/Guilds/IVoiceRegion.cs

@@ -8,26 +8,44 @@ namespace Discord
         /// <summary>
         ///     Gets the unique identifier for this voice region.
         /// </summary>
+        /// <returns>
+        ///     A string that represents the identifier for this voice region (e.g. <c>eu-central</c>).
+        /// </returns>
         string Id { get; }
         /// <summary>
         ///     Gets the name of this voice region.
         /// </summary>
+        /// <returns>
+        ///     A string that represents the human-readable name of this voice region (e.g. <c>Central Europe</c>).
+        /// </returns>
         string Name { get; }
         /// <summary>
-        ///     Returns <c>true</c> 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.
         /// </summary>
+        /// <returns>
+        ///     <c>true</c> if this voice region is exclusive to VIP accounts; otherwise <c>false</c>.
+        /// </returns>
         bool IsVip { get; }
         /// <summary>
-        ///     Returns <c>true</c> 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.
         /// </summary>
+        /// <returns>
+        ///     <c>true</c> if this voice region is the closest to your machine; otherwise <c>false</c> .
+        /// </returns>
         bool IsOptimal { get; }
-        /// <summary> 
-        ///     Returns <c>true</c> if this is a deprecated voice region (avoid switching to these).
+        /// <summary>
+        ///     Gets a value that indicates whether this voice region is no longer being maintained.
         /// </summary>
+        /// <returns>
+        ///     <c>true</c> if this is a deprecated voice region; otherwise <c>false</c>.
+        /// </returns>
         bool IsDeprecated { get; }
-        /// <summary> 
-        ///     Returns <c>true</c> if this is a custom voice region (used for events/etc).
+        /// <summary>
+        ///     Gets a value that indicates whether this voice region is custom-made for events.
         /// </summary>
+        /// <returns> 
+        ///     <c>true</c> if this is a custom voice region (used for events/etc); otherwise <c>false</c>/
+        /// </returns>
         bool IsCustom { get; }
     }
 }

src/Discord.Net.Core/Entities/Invites/IInviteMetadata.cs

@@ -15,15 +15,14 @@ namespace Discord
         /// </returns>
         IUser Inviter { get; }
         /// <summary>
-        ///     Determines whether the invite has been revoked.
+        ///     Gets a value that indicates whether the invite has been revoked.
         /// </summary>
         /// <returns>
         ///     <c>true</c> if this invite was revoked; otherwise <c>false</c>.
         /// </returns>
         bool IsRevoked { get; }
         /// <summary>
-        ///     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.
         /// </summary>
         /// <returns>
         ///     <c>true</c> if users accepting this invite will be removed from the guild when they log off; otherwise 

src/Discord.Net.Core/Entities/Messages/EmbedBuilder.cs

@@ -492,7 +492,7 @@ namespace Discord
             }
         }
         /// <summary>
-        ///     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.
         /// </summary>
         public bool IsInline { get; set; }
 

src/Discord.Net.Core/Entities/Messages/EmbedField.cs

@@ -17,7 +17,7 @@ namespace Discord
         /// </summary>
         public string Value { get; internal set; }
         /// <summary>
-        ///     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.
         /// </summary>
         public bool Inline { get; internal set; }
 
@@ -32,6 +32,9 @@ namespace Discord
         /// <summary>
         ///     Gets the name of the field.
         /// </summary>
+        /// <returns>
+        ///     A string that resolves to <see cref="EmbedField.Name"/>.
+        /// </returns>
         public override string ToString() => Name;
     }
 }

src/Discord.Net.Core/Entities/Messages/IMessage.cs

@@ -17,12 +17,18 @@ namespace Discord
         /// </summary>
         MessageSource Source { get; }
         /// <summary>
-        ///     Returns <c>true</c> 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.
         /// </summary>
+        /// <returns>
+        ///     <c>true</c> if this message was sent as a text-to-speech message; otherwise <c>false</c>.
+        /// </returns>
         bool IsTTS { get; }
         /// <summary>
-        ///     Returns <c>true</c> if this message was added to its channel's pinned messages.
+        ///     Gets the value that indicates whether this message is pinned.
         /// </summary>
+        /// <returns>
+        ///     <c>true</c> if this message was added to its channel's pinned messages; otherwise <c>false</c>.
+        /// </returns>
         bool IsPinned { get; }
         /// <summary>
         ///     Returns the content for this message.
@@ -56,14 +62,14 @@ namespace Discord
         ///     Returns all attachments included in this message.
         /// </summary>
         /// <returns>
-        ///     Collection of attachments.
+        ///     A read-only collection of attachments.
         /// </returns>
         IReadOnlyCollection<IAttachment> Attachments { get; }
         /// <summary>
         ///     Returns all embeds included in this message.
         /// </summary>
         /// <returns>
-        ///     Collection of embed objects.
+        ///     A read-only collection of embed objects.
         /// </returns>
         IReadOnlyCollection<IEmbed> Embeds { get; }
         /// <summary>
@@ -74,21 +80,21 @@ namespace Discord
         ///     Returns the IDs of channels mentioned in this message.
         /// </summary>
         /// <returns>
-        ///     Collection of channel IDs.
+        ///     A read-only collection of channel IDs.
         /// </returns>
         IReadOnlyCollection<ulong> MentionedChannelIds { get; }
         /// <summary>
         ///     Returns the IDs of roles mentioned in this message.
         /// </summary>
         /// <returns>
-        ///     Collection of role IDs.
+        ///     A read-only collection of role IDs.
         /// </returns>
         IReadOnlyCollection<ulong> MentionedRoleIds { get; }
         /// <summary>
         ///     Returns the IDs of users mentioned in this message.
         /// </summary>
         /// <returns>
-        ///     Collection of user IDs.
+        ///     A read-only collection of user IDs.
         /// </returns>
         IReadOnlyCollection<ulong> MentionedUserIds { get; }
     }

src/Discord.Net.Core/Entities/Messages/IUserMessage.cs

@@ -20,7 +20,7 @@ namespace Discord
         /// <param name="func">A delegate containing the properties to modify the message with.</param>
         /// <param name="options">The options to be used when sending the request.</param>
         /// <returns>
-        ///     An awaitable <see cref="Task"/>.
+        ///     A task that represents the asynchronous modification operation.
         /// </returns>
         Task ModifyAsync(Action<MessageProperties> func, RequestOptions options = null);
         /// <summary>
@@ -28,7 +28,7 @@ namespace Discord
         /// </summary>
         /// <param name="options">The options to be used when sending the request.</param>
         /// <returns>
-        ///     An awaitable <see cref="Task"/>.
+        ///     A task that represents the asynchronous operation for pinning this message.
         /// </returns>
         Task PinAsync(RequestOptions options = null);
         /// <summary>
@@ -36,7 +36,7 @@ namespace Discord
         /// </summary>
         /// <param name="options">The options to be used when sending the request.</param>
         /// <returns>
-        ///     An awaitable <see cref="Task"/>.
+        ///     A task that represents the asynchronous operation for unpinning this message.
         /// </returns>
         Task UnpinAsync(RequestOptions options = null);
 
@@ -56,8 +56,9 @@ namespace Discord
         /// <param name="emote">The emoji used to react to this message.</param>
         /// <param name="options">The options to be used when sending the request.</param>
         /// <returns>
-        ///     An awaitable <see cref="Task"/>.
+        ///     A task that represents the asynchronous operation for adding a reaction to this message.
         /// </returns>
+        /// <seealso cref="IEmote"/>
         Task AddReactionAsync(IEmote emote, RequestOptions options = null);
         /// <summary>
         ///     Removes a reaction from message.
@@ -71,20 +72,36 @@ namespace Discord
         /// <param name="user">The user that added the emoji.</param>
         /// <param name="options">The options to be used when sending the request.</param>
         /// <returns>
-        ///     An awaitable <see cref="Task"/>.
+        ///     A task that represents the asynchronous operation for removing a reaction to this message.
         /// </returns>
+        /// <seealso cref="IEmote"/>
         Task RemoveReactionAsync(IEmote emote, IUser user, RequestOptions options = null);
         /// <summary>
         ///     Removes all reactions from this message.
         /// </summary>
         /// <param name="options">The options to be used when sending the request.</param>
         /// <returns>
-        ///     An awaitable <see cref="Task"/>.
+        ///     A task that represents the asynchronous removal operation.
         /// </returns>
         Task RemoveAllReactionsAsync(RequestOptions options = null);
+
         /// <summary>
         ///     Gets all users that reacted to a message with a given emote.
         /// </summary>
+        /// <example>
+        ///     <code language="cs">
+        ///     var emoji = new Emoji("\U0001f495");
+        ///     var reactedUsers = await message.GetReactionUsersAsync(emoji, 100).FlattenAsync();
+        ///     </code>
+        /// </example>
+        /// <param name="emoji">The emoji that represents the reaction that you wish to get.</param>
+        /// <param name="limit">The number of users to request.</param>
+        /// <param name="options">The options to be used when sending the request.</param>
+        /// <returns>
+        ///     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 
+        ///     <see cref="AsyncEnumerableExtensions.FlattenAsync{T}"/> is required if you wish to access the users.
+        /// </returns>
         IAsyncEnumerable<IReadOnlyCollection<IUser>> GetReactionUsersAsync(IEmote emoji, int limit, RequestOptions options = null);
 
         /// <summary>

src/Discord.Net.Core/Entities/Roles/IRole.cs

@@ -24,21 +24,21 @@ namespace Discord
         /// </returns>
         Color Color { get; }
         /// <summary>
-        ///     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.
         /// </summary>
         /// <returns>
         ///     <c>true</c> if users of this role are separated in the user list; otherwise <c>false</c>.
         /// </returns>
         bool IsHoisted { get; }
         /// <summary>
-        ///     Determines whether the role is managed by Discord.
+        ///     Gets a value that indicates whether the role is managed by Discord.
         /// </summary>
         /// <returns>
         ///     <c>true</c> if this role is automatically managed by Discord; otherwise <c>false</c>.
         /// </returns>
         bool IsManaged { get; }
         /// <summary>
-        ///     Determines whether the role is mentionable.
+        ///     Gets a value that indicates whether the role is mentionable.
         /// </summary>
         /// <returns>
         ///     <c>true</c> if this role may be mentioned in messages; otherwise <c>false</c>.
@@ -82,7 +82,7 @@ namespace Discord
         /// <param name="func">A delegate containing the properties to modify the role with.</param>
         /// <param name="options">The options to be used when sending the request.</param>
         /// <returns>
-        ///     An awaitable <see cref="Task"/>.
+        ///     A task that represents the asynchronous modification operation.
         /// </returns>
         Task ModifyAsync(Action<RoleProperties> func, RequestOptions options = null);
     }

src/Discord.Net.Core/Entities/Users/IUser.cs

@@ -15,9 +15,7 @@ namespace Discord
         ///     Returns a URL to this user's avatar.
         /// </summary>
         /// <param name="format">The format to return.</param>
-        /// <param name="size">
-        /// The size of the image to return in. This can be any power of two between 16 and 2048.
-        /// </param>
+        /// <param name="size">The size of the image to return in. This can be any power of two between 16 and 2048.</param>
         /// <returns>
         ///     User's avatar URL.
         /// </returns>
@@ -35,12 +33,18 @@ namespace Discord
         /// </summary>
         ushort DiscriminatorValue { get; }
         /// <summary>
-        ///     Gets <c>true</c> if this user is a bot user.
+        ///     Gets a value that indicates whether this user is a bot user.
         /// </summary>
+        /// <returns>
+        ///     <c>true</c> if the user is a bot; otherwise <c>false</c>.
+        /// </returns>
         bool IsBot { get; }
         /// <summary>
-        ///     Gets <c>true</c> if this user is a webhook user.
+        ///     Gets a value that indicates whether this user is a webhook user.
         /// </summary>
+        /// <returns>
+        ///     <c>true</c> if the user is a webhook; otherwise <c>false</c>.
+        /// </returns>
         bool IsWebhook { get; }
         /// <summary>
         ///     Gets the username for this user.
@@ -52,7 +56,7 @@ namespace Discord
         /// </summary>
         /// <param name="options">The options to be used when sending the request.</param>
         /// <returns>
-        ///     An awaitable Task containing the DM channel.
+        ///     A task that represents the asynchronous operation for getting or creating a DM channel.
         /// </returns>
         Task<IDMChannel> GetOrCreateDMChannelAsync(RequestOptions options = null);
     }

src/Discord.Net.Core/Extensions/UserExtensions.cs

@@ -16,7 +16,7 @@ namespace Discord
         /// <param name="embed">The <see cref="EmbedType.Rich"/> <see cref="Embed"/> to be sent.</param>
         /// <param name="options">The options to be used when sending the request.</param>
         /// <returns>
-        ///     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.
         /// </returns>
         public static async Task<IUserMessage> SendMessageAsync(this IUser user,
             string text = null,
@@ -43,7 +43,7 @@ namespace Discord
         ///     <see cref="Discord.EmbedBuilder.ImageUrl"/>.
         /// </remarks>
         /// <returns>
-        ///     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.
         /// </returns>
         public static async Task<IUserMessage> SendFileAsync(this IUser user,
             Stream stream,
@@ -72,7 +72,7 @@ namespace Discord
         ///     <see cref="Discord.EmbedBuilder.ImageUrl"/>.
         /// </remarks>
         /// <returns>
-        ///     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.
         /// </returns>
         public static async Task<IUserMessage> SendFileAsync(this IUser user,
             string filePath,
@@ -85,15 +85,16 @@ namespace Discord
         }
 
         /// <summary>
-        ///     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.
         /// </summary>
         /// <param name="user">The user to ban.</param>
-        /// <param name="pruneDays">
-        /// The number of days to remove messages from this user for - must be between [0, 7]
-        /// </param>
+        /// <param name="pruneDays">The number of days to remove messages from this <paramref name="user"/> for - must be between [0, 7]</param>
         /// <param name="reason">The reason of the ban to be written in the audit log.</param>
         /// <param name="options">The options to be used when sending the request.</param>
         /// <exception cref="ArgumentException"><paramref name="pruneDays" /> is not between 0 to 7.</exception>
+        /// <returns>
+        ///     A task that represents the asynchrnous operation for banning a user.
+        /// </returns>
         public static Task BanAsync(this IGuildUser user, int pruneDays = 0, string reason = null, RequestOptions options = null)
             => user.Guild.AddBanAsync(user, pruneDays, reason, options);
     }

src/Discord.Net.Core/IDiscordClient.cs

@@ -34,14 +34,14 @@ namespace Discord
         ///     </note>
         /// </remarks>
         /// <returns>
-        ///     An awaitable <see cref="Task"/>.
+        ///     A task that represents the asynchronous start operation.
         /// </returns>
         Task StartAsync();
         /// <summary>
         ///     Stops the connection between Discord and the client.
         /// </summary>
         /// <returns>
-        ///     An awaitable <see cref="Task"/>.
+        ///     A task that represents the asynchronous stop operation.
         /// </returns>
         Task StopAsync();
 
@@ -54,37 +54,35 @@ namespace Discord
         /// </remarks>
         /// <param name="options">The options to be used when sending the request.</param>
         /// <returns>
-        ///     An awaitable <see cref="Task"/> containing the application information.
+        ///     A task that represents the asynchronous get operation. The task result contains the application
+        ///     information.
         /// </returns>
         Task<IApplication> GetApplicationInfoAsync(RequestOptions options = null);
 
         /// <summary>
-        ///     Gets a generic channel via the snowflake identifier.
+        ///     Gets a generic channel.
         /// </summary>
         /// <example>
-        ///     <code language="cs" title="Example method">
+        ///     <code lang="cs" title="Example method">
         ///     var channel = await _client.GetChannelAsync(381889909113225237);
         ///     if (channel != null &amp;&amp; channel is IMessageChannel msgChannel)
         ///     {
         ///         await msgChannel.SendMessageAsync($"{msgChannel} is created at {msgChannel.CreatedAt}");
         ///     }
-        ///    </code>
+        ///     </code>
         /// </example>
         /// <param name="id">The snowflake identifier of the channel (e.g. `381889909113225237`).</param>
-        /// <param name="mode">
-        /// The <see cref="CacheMode"/> that determines whether the object should be fetched from cache.
-        /// </param>
+        /// <param name="mode">The <see cref="CacheMode"/> that determines whether the object should be fetched from cache.</param>
         /// <param name="options">The options to be used when sending the request.</param>
         /// <returns>
-        ///     An awaitable <see cref="Task"/> 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; <c>null</c> when the channel cannot be found.
         /// </returns>
         Task<IChannel> GetChannelAsync(ulong id, CacheMode mode = CacheMode.AllowDownload, RequestOptions options = null);
         /// <summary>
         ///     Gets a collection of private channels opened in this session.
         /// </summary>
-        /// <param name="mode">
-        /// The <see cref="CacheMode" /> that determines whether the object should be fetched from cache.
-        /// </param>
+        /// <param name="mode">The <see cref="CacheMode"/> that determines whether the object should be fetched from cache.</param>
         /// <param name="options">The options to be used when sending the request.</param>
         /// <remarks>
         ///     This method will retrieve all private channels (including direct-message, group channel and such) that
@@ -95,8 +93,8 @@ namespace Discord
         ///     </note>
         /// </remarks>
         /// <returns>
-        ///     An awaitable <see cref="Task" /> 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.
         /// </returns>
         Task<IReadOnlyCollection<IPrivateChannel>> GetPrivateChannelsAsync(CacheMode mode = CacheMode.AllowDownload, RequestOptions options = null);
         /// <summary>
@@ -109,13 +107,11 @@ namespace Discord
         ///         have just started the client, this may return an empty collection.
         ///     </note>
         /// </remarks>
-        /// <param name="mode">
-        /// The <see cref="CacheMode" /> that determines whether the object should be fetched from cache.
-        /// </param>
+        /// <param name="mode">The <see cref="CacheMode"/> that determines whether the object should be fetched from cache.</param>
         /// <param name="options">The options to be used when sending the request.</param>
         /// <returns>
-        ///     An awaitable <see cref="Task" /> 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.
         /// </returns>
         Task<IReadOnlyCollection<IDMChannel>> GetDMChannelsAsync(CacheMode mode = CacheMode.AllowDownload, RequestOptions options = null);
         /// <summary>
@@ -128,64 +124,145 @@ namespace Discord
         ///         have just started the client, this may return an empty collection.
         ///     </note>
         /// </remarks>
-        /// <param name="mode">
-        /// The <see cref="CacheMode" /> that determines whether the object should be fetched from cache.
-        /// </param>
+        /// <param name="mode">The <see cref="CacheMode"/> that determines whether the object should be fetched from cache.</param>
         /// <param name="options">The options to be used when sending the request.</param>
         /// <returns>
-        ///     An awaitable <see cref="Task" /> 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.
         /// </returns>
         Task<IReadOnlyCollection<IGroupChannel>> GetGroupChannelsAsync(CacheMode mode = CacheMode.AllowDownload, RequestOptions options = null);
 
+        /// <summary>
+        ///     Gets the connections that the user has set up.
+        /// </summary>
+        /// <param name="options">The options to be used when sending the request.</param>
+        /// <returns>
+        ///     A task that represents the asynchronous get operation. The task result contains a read-only collection of connections.
+        /// </returns>
         Task<IReadOnlyCollection<IConnection>> GetConnectionsAsync(RequestOptions options = null);
 
+        /// <summary>
+        ///     Gets a guild.
+        /// </summary>
+        /// <param name="id">The guild snowflake identifier.</param>
+        /// <param name="mode">The <see cref="CacheMode"/> that determines whether the object should be fetched from cache.</param>
+        /// <param name="options">The options to be used when sending the request.</param>
+        /// <returns>
+        ///     A task that represents the asynchronous get operation. The task result contains the guild associated
+        ///     with the snowflake identifier; <c>null</c> when the guild cannot be found.
+        /// </returns>
         Task<IGuild> GetGuildAsync(ulong id, CacheMode mode = CacheMode.AllowDownload, RequestOptions options = null);
+        /// <summary>
+        ///     Gets a collection of guilds that the user is currently in.
+        /// </summary>
+        /// <param name="mode">The <see cref="CacheMode"/> that determines whether the object should be fetched from cache.</param>
+        /// <param name="options">The options to be used when sending the request.</param>
+        /// <returns>
+        ///     A task that represents the asynchronous get operation. The task result contains a read-only collection
+        ///     of guilds that the current user is in.
+        /// </returns>
         Task<IReadOnlyCollection<IGuild>> GetGuildsAsync(CacheMode mode = CacheMode.AllowDownload, RequestOptions options = null);
+        /// <summary>
+        ///     Creates a guild for the logged-in user who is in less than 10 active guilds.
+        /// </summary>
+        /// <remarks>
+        ///     This method creates a new guild on behalf of the logged-in user.
+        ///     <note type="warning">
+        ///         Due to Discord's limitation, this method will only work for users that are in less than 10 guilds.
+        ///     </note>
+        /// </remarks>
+        /// <param name="name">The name of the new guild.</param>
+        /// <param name="region">The voice region to create the guild with.</param>
+        /// <param name="jpegIcon">The icon of the guild.</param>
+        /// <param name="options">The options to be used when sending the request.</param>
+        /// <returns>
+        ///     A task that represents the asynchronous creation operation. The task result contains the created guild.
+        /// </returns>
         Task<IGuild> CreateGuildAsync(string name, IVoiceRegion region, Stream jpegIcon = null, RequestOptions options = null);
-        
+
+        /// <summary>
+        ///     Gets an invite.
+        /// </summary>
+        /// <param name="inviteId">The invitation identifier.</param>
+        /// <param name="options">The options to be used when sending the request.</param>
+        /// <returns>
+        ///     A task that represents the asynchronous get operation. The task result contains the invite information.
+        /// </returns>
         Task<IInvite> GetInviteAsync(string inviteId, RequestOptions options = null);
 
         /// <summary>
-        ///     Gets a user via the snowflake identifier.
+        ///     Gets a user.
         /// </summary>
         /// <example>
-        ///     <code language="cs" title="Example method">
+        ///     <code lang="cs" title="Example method">
         ///     var user = await _client.GetUserAsync(168693960628371456);
         ///     if (user != null)
         ///         Console.WriteLine($"{user} is created at {user.CreatedAt}.";
         ///     </code>
         /// </example>
         /// <param name="id">The snowflake identifier of the user (e.g. `168693960628371456`).</param>
-        /// <param name="mode">
-        /// The <see cref="CacheMode"/> that determines whether the object should be fetched from cache.
-        /// </param>
+        /// <param name="mode">The <see cref="CacheMode"/> that determines whether the object should be fetched from cache.</param>
         /// <param name="options">The options to be used when sending the request.</param>
         /// <returns>
-        ///     An awaitable <see cref="Task"/> containing the fetched user; <c>null</c> if none is found.
+        ///     A task that represents the asynchronous get operation. The task result contains the user associated with
+        ///     the snowflake identifier; <c>null</c> if the user is not found.
         /// </returns>
         Task<IUser> GetUserAsync(ulong id, CacheMode mode = CacheMode.AllowDownload, RequestOptions options = null);
         /// <summary>
-        ///     Gets a user via the username and discriminator combo.
+        ///     Gets a user.
         /// </summary>
         /// <example>
-        ///     <code language="cs" title="Example method">
-        ///     var user = await _client.GetUserAsync("Still", "2876");
-        ///     if (user != null)
-        ///         Console.WriteLine($"{user} is created at {user.CreatedAt}.";
-        ///     </code>
+        ///     <code lang="cs" title="Example method">
+        ///    var user = await _client.GetUserAsync("Still", "2876");
+        ///    if (user != null)
+        ///        Console.WriteLine($"{user} is created at {user.CreatedAt}.";
+        ///    </code>
         /// </example>
         /// <param name="username">The name of the user (e.g. `Still`).</param>
         /// <param name="discriminator">The discriminator value of the user (e.g. `2876`).</param>
         /// <param name="options">The options to be used when sending the request.</param>
         /// <returns>
-        ///     An awaitable <see cref="Task" /> containing the fetched user; <c>null</c> 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; <c>null</c> if the user is not found.
         /// </returns>
         Task<IUser> GetUserAsync(string username, string discriminator, RequestOptions options = null);
 
+        /// <summary>
+        ///     Gets a collection of the available voice regions.
+        /// </summary>
+        /// <example>
+        ///     The following example gets the most optimal voice region from the collection.
+        ///     <code lang="cs">
+        ///         var regions = await client.GetVoiceRegionsAsync();
+        ///         var optimalRegion = regions.FirstOrDefault(x =&gt; x.IsOptimal);
+        ///     </code>
+        /// </example>
+        /// <param name="options">The options to be used when sending the request.</param>
+        /// <returns>
+        ///     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.
+        /// </returns>
         Task<IReadOnlyCollection<IVoiceRegion>> GetVoiceRegionsAsync(RequestOptions options = null);
+        /// <summary>
+        ///     Gets a voice region.
+        /// </summary>
+        /// <param name="id">The identifier of the voice region (e.g. <c>eu-central</c> ).</param>
+        /// <param name="options">The options to be used when sending the request.</param>
+        /// <returns>
+        ///     A task that represents the asynchronous get operation. The task result contains the voice region
+        ///     associated with the identifier; <c>null</c> if the voice region is not found.
+        /// </returns>
         Task<IVoiceRegion> GetVoiceRegionAsync(string id, RequestOptions options = null);
 
+        /// <summary>
+        ///     Gets a webhook available.
+        /// </summary>
+        /// <param name="id">The identifier of the webhook.</param>
+        /// <param name="options">The options to be used when sending the request.</param>
+        /// <returns>
+        ///     A task that represents the asynchronous get operation. The task result contains a webhook associated
+        ///     with the identifier; <c>null</c> if the webhook is not found.
+        /// </returns>
         Task<IWebhook> GetWebhookAsync(ulong id, RequestOptions options = null);
 
         /// <summary>
@@ -193,8 +270,8 @@ namespace Discord
         /// </summary>
         /// <param name="options">The options to be used when sending the request.</param>
         /// <returns>
-        ///     An awaitable <see cref="Task"/> containing an <see cref="int"/> 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 <see cref="Int32"/>
+        ///     that represents the number of shards that should be used with this account.
         /// </returns>
         Task<int> GetRecommendedShardCountAsync(RequestOptions options = null);
     }

src/Discord.Net.Core/Utils/Cacheable.cs

@@ -44,7 +44,8 @@ namespace Discord
         /// <exception cref="Discord.Net.HttpException">Thrown when used from a user account.</exception>
         /// <exception cref="NullReferenceException">Thrown when the message is deleted.</exception>
         /// <returns>
-        ///     An awaitable <see cref="Task"/> containing the downloaded entity.
+        ///     A task that represents the asynchronous download operation. The task result contains the downloaded
+        ///     entity.
         /// </returns>
         public async Task<TEntity> DownloadAsync()
         {
@@ -57,7 +58,8 @@ namespace Discord
         /// <exception cref="Discord.Net.HttpException">Thrown when used from a user account.</exception>
         /// <exception cref="NullReferenceException">Thrown when the message is deleted and is not in cache.</exception>
         /// <returns>
-        ///     An awaitable <see cref="Task"/> 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.
         /// </returns>
         public async Task<TEntity> GetOrDownloadAsync() => HasValue ? Value : await DownloadAsync().ConfigureAwait(false);
     }

src/Discord.Net.Rest/BaseDiscordClient.cs

@@ -32,9 +32,7 @@ namespace Discord.Rest
         ///     Gets the logged-in user.
         /// </summary>
         public ISelfUser CurrentUser { get; protected set; }
-        /// <summary>
-        ///     Gets the type of the authentication token.
-        /// </summary>
+        /// <inheritdoc />
         public TokenType TokenType => ApiClient.AuthTokenType;
         
         /// <summary> Creates a new REST-only Discord client. </summary>

src/Discord.Net.Rest/Entities/AuditLogs/DataTypes/InviteCreateAuditLogData.cs

@@ -62,8 +62,7 @@ namespace Discord.Rest
         /// </returns>
         public string Code { get; }
         /// <summary>
-        ///     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.
         /// </summary>
         /// <returns>
         ///     <c>true</c> if users accepting this invite will be removed from the guild when they log off; otherwise

src/Discord.Net.Rest/Entities/AuditLogs/DataTypes/InviteDeleteAuditLogData.cs

@@ -62,8 +62,7 @@ namespace Discord.Rest
         /// </returns>
         public string Code { get; }
         /// <summary>
-        ///     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.
         /// </summary>
         /// <returns>
         ///     <c>true</c> if users accepting this invite will be removed from the guild when they log off; otherwise

src/Discord.Net.Rest/Entities/AuditLogs/DataTypes/InviteInfo.cs

@@ -30,8 +30,7 @@ namespace Discord.Rest
         /// </returns>
         public string Code { get; }
         /// <summary>
-        ///     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.
         /// </summary>
         /// <returns>
         ///     <c>true</c> if users accepting this invite will be removed from the guild when they log off, 

src/Discord.Net.Rest/Entities/AuditLogs/DataTypes/MemberRoleEditInfo.cs

@@ -27,7 +27,7 @@ namespace Discord.Rest
         /// </returns>
         public ulong RoleId { get; }
         /// <summary>
-        ///     Determines whether the role was added to the user.
+        ///     Gets a value that indicates whether the role was added to the user.
         /// </summary>
         /// <returns>
         ///     <c>true</c> if the role was added to the user; otherwise <c>false</c>.

src/Discord.Net.Rest/Entities/AuditLogs/DataTypes/RoleEditInfo.cs

@@ -24,19 +24,20 @@ namespace Discord.Rest
         /// </returns>
         public Color? Color { get; }
         /// <summary>
-        ///     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.
         /// </summary>
         /// <returns>
-        ///     <c>true</c> if other members can mention this role in a text channel; otherwise <c>false</c>.
+        ///     <c>true</c> if other members can mention this role in a text channel; otherwise <c>false</c>; 
+        ///     <c>null</c> if this is not mentioned in this entry.
         /// </returns>
         public bool? Mentionable { get; }
         /// <summary>
-        ///     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).
         /// </summary>
         /// <returns>
-        ///     <c>true</c> if this role's members will appear in a seperate section in the user list; otherwise
-        ///     <c>false</c>.
+        ///     <c>true</c> if this role's members will appear in a separate section in the user list; otherwise 
+        ///     <c>false</c>; <c>null</c> if this is not mentioned in this entry.
         /// </returns>
         public bool? Hoist { get; }
         /// <summary>

src/Discord.Net.Rest/Entities/Channels/IRestMessageChannel.cs

@@ -13,56 +13,67 @@ namespace Discord.Rest
         ///     Sends a message to this message channel.
         /// </summary>
         /// <param name="text">The message to be sent.</param>
-        /// <param name="isTTS">Whether the message should be read aloud by Discord or not.</param>
-        /// <param name="embed">The <see cref="EmbedType.Rich"/> <see cref="Embed"/> to be sent.</param>
+        /// <param name="isTTS">Determines whether the message should be read aloud by Discord or not.</param>
+        /// <param name="embed">The <see cref="Discord.EmbedType.Rich"/> <see cref="Embed"/> to be sent.</param>
         /// <param name="options">The options to be used when sending the request.</param>
         /// <returns>
-        ///     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.
         /// </returns>
         new Task<RestUserMessage> SendMessageAsync(string text = null, bool isTTS = false, Embed embed = null, RequestOptions options = null);
         /// <summary>
-        ///     Sends a file to this message channel, with an optional caption.
+        ///     Sends a file to this message channel with an optional caption.
         /// </summary>
+        /// <remarks>
+        ///     This method sends a file as if you are uploading an attachment directly from your Discord client.
+        ///     <note>
+        ///         If you wish to upload an image and have it embedded in a <see cref="Discord.EmbedType.Rich"/>embed,
+        ///         you may upload the file and refer to the file with "attachment://filename.ext" in the
+        ///         <see cref="Discord.EmbedBuilder.ImageUrl"/>.
+        ///     </note>
+        /// </remarks>
         /// <param name="filePath">The file path of the file.</param>
         /// <param name="text">The message to be sent.</param>
         /// <param name="isTTS">Whether the message should be read aloud by Discord or not.</param>
-        /// <param name="embed">The <see cref="EmbedType.Rich"/> <see cref="Embed"/> to be sent.</param>
+        /// <param name="embed">The <see cref="Discord.EmbedType.Rich" /> <see cref="Embed" /> to be sent.</param>
         /// <param name="options">The options to be used when sending the request.</param>
-        /// <remarks>
-        ///     If you wish to upload an image and have it embedded in a <see cref="EmbedType.Rich"/> embed, you may
-        ///     upload the file and refer to the file with "attachment://filename.ext" in the 
-        ///     <see cref="Discord.EmbedBuilder.ImageUrl"/>.
-        /// </remarks>
         /// <returns>
-        ///     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.
         /// </returns>
         new Task<RestUserMessage> SendFileAsync(string filePath, string text = null, bool isTTS = false, Embed embed = null, RequestOptions options = null);
         /// <summary>
-        ///     Sends a file to this message channel, with an optional caption.
+        ///     Sends a file to this message channel with an optional caption.
         /// </summary>
-        /// <param name="stream">The <see cref="Stream"/> of the file to be sent.</param>
+        /// <remarks>
+        ///     This method sends a file as if you are uploading an attachment directly from your Discord client.
+        ///     <note>
+        ///         If you wish to upload an image and have it embedded in a <see cref="Discord.EmbedType.Rich"/>embed,
+        ///         you may upload the file and refer to the file with "attachment://filename.ext" in the
+        ///         <see cref="Discord.EmbedBuilder.ImageUrl"/>.
+        ///     </note>
+        /// </remarks>
+        /// <param name="stream">The <see cref="Stream" /> of the file to be sent.</param>
         /// <param name="filename">The name of the attachment.</param>
         /// <param name="text">The message to be sent.</param>
         /// <param name="isTTS">Whether the message should be read aloud by Discord or not.</param>
-        /// <param name="embed">The <see cref="EmbedType.Rich"/> <see cref="Embed"/> to be sent.</param>
+        /// <param name="embed">The <see cref="Discord.EmbedType.Rich"/> <see cref="Embed"/> to be sent.</param>
         /// <param name="options">The options to be used when sending the request.</param>
-        /// <remarks>
-        ///     If you wish to upload an image and have it embedded in a <see cref="EmbedType.Rich"/> embed, you may
-        ///     upload the file and refer to the file with "attachment://filename.ext" in the 
-        ///     <see cref="Discord.EmbedBuilder.ImageUrl"/>.
-        /// </remarks>
         /// <returns>
-        ///     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.
         /// </returns>
         new Task<RestUserMessage> SendFileAsync(Stream stream, string filename, string text = null, bool isTTS = false, Embed embed = null, RequestOptions options = null);
 
         /// <summary>
-        ///     Gets a message from this message channel with the given id, or <c>null</c> if not found.
+        ///     Gets a message from this message channel.
         /// </summary>
-        /// <param name="id">The ID of the message.</param>
+        /// <param name="id">The snowflake identifier of the message.</param>
+        /// <param name="mode">The <see cref="CacheMode"/> that determines whether the object should be fetched from cache.</param>
         /// <param name="options">The options to be used when sending the request.</param>
         /// <returns>
-        ///     The message gotten from either the cache or the download, or <c>null</c> if none is found.
+        ///     A task that represents an asynchronous get operation for retrieving the message. The task result contains
+        ///     the retrieved message; <c>null</c> if no message is found with the specified identifier.
         /// </returns>
         Task<RestMessage> GetMessageAsync(ulong id, RequestOptions options = null);
         /// <summary>
@@ -104,7 +115,8 @@ namespace Discord.Rest
         /// </summary>
         /// <param name="options">The options to be used when sending the request.</param>
         /// <returns>
-        ///     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.
         /// </returns>
         new Task<IReadOnlyCollection<RestMessage>> GetPinnedMessagesAsync(RequestOptions options = null);
     }

src/Discord.Net.Rest/Entities/Channels/RestGuildChannel.cs

@@ -73,11 +73,11 @@ namespace Discord.Rest
             => ChannelHelper.DeleteAsync(this, Discord, options);
 
         /// <summary>
-        ///     Gets the overwrite permissions of the specified <paramref name="user"/>.
+        ///     Gets the permission overwrite for a specific user.
         /// </summary>
-        /// <param name="user">The user that you want to get the overwrite permissions for.</param>
+        /// <param name="user">The user to get the overwrite from.</param>
         /// <returns>
-        ///     The overwrite permissions for the requested user; otherwise <c>null</c>.
+        ///     An overwrite object for the targeted user; <c>null</c> if none is set.
         /// </returns>
         public OverwritePermissions? GetPermissionOverwrite(IUser user)
         {
@@ -90,11 +90,11 @@ namespace Discord.Rest
         }
 
         /// <summary>
-        ///     Gets the overwrite permissions of the specified <paramref name="role"/>.
+        ///     Gets the permission overwrite for a specific role.
         /// </summary>
-        /// <param name="role">The role that you want to get the overwrite permissions for.</param>
+        /// <param name="role">The role to get the overwrite from.</param>
         /// <returns>
-        ///     The overwrite permissions for the requested role; otherwise <c>null</c>.
+        ///     An overwrite object for the targeted role; <c>null</c> if none is set.
         /// </returns>
         public OverwritePermissions? GetPermissionOverwrite(IRole role)
         {
@@ -107,42 +107,41 @@ namespace Discord.Rest
         }
 
         /// <summary>
-        ///     Adds an overwrite permission for the specified <paramref name="user"/>.
+        ///     Adds or updates the permission overwrite for the given user.
         /// </summary>
-        /// <param name="user">The user you want the overwrite permission to apply to.</param>
-        /// <param name="perms">The overwrite permission you want to add.</param>
+        /// <param name="user">The user to add the overwrite to.</param>
+        /// <param name="permissions">The overwrite to add to the user.</param>
         /// <param name="options">The options to be used when sending the request.</param>
         /// <returns>
-        ///     An awaitable <see cref="Task"/>.
+        ///     A task representing the asynchronous permission operation for adding the specified permissions to the channel.
         /// </returns>
-        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)));
         }
-
         /// <summary>
-        ///     Adds an overwrite permission for the specified <paramref name="role"/>.
+        ///     Adds or updates the permission overwrite for the given role.
         /// </summary>
-        /// <param name="role">The role you want the overwrite permission to apply to.</param>
-        /// <param name="perms">The overwrite permission you want to add.</param>
-        /// <param name="options">The options to be used when sending the request. </param>
+        /// <param name="role">The role to add the overwrite to.</param>
+        /// <param name="permissions">The overwrite to add to the role.</param>
+        /// <param name="options">The options to be used when sending the request.</param>
         /// <returns>
-        ///     An awaitable <see cref="Task"/>.
+        ///     A task representing the asynchronous permission operation for adding the specified permissions to the channel.
         /// </returns>
-        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)));
         }
 
         /// <summary>
-        ///     Removes an overwrite permission for the specified <paramref name="user"/>.
+        ///     Removes the permission overwrite for the given user, if one exists.
         /// </summary>
-        /// <param name="user">The user you want to remove the overwrite permission from.</param>
+        /// <param name="user">The user to remove the overwrite from.</param>
         /// <param name="options">The options to be used when sending the request.</param>
         /// <returns>
-        ///     An awaitable <see cref="Task"/>.
+        ///     A task representing the asynchronous operation for removing the specified permissions from the channel.
         /// </returns>
         public async Task RemovePermissionOverwriteAsync(IUser user, RequestOptions options = null)
         {
@@ -157,14 +156,13 @@ namespace Discord.Rest
                 }
             }
         }
-
         /// <summary>
-        ///     Removes an overwrite permission for the specified <paramref name="role"/>.
+        ///     Removes the permission overwrite for the given role, if one exists.
         /// </summary>
-        /// <param name="role">The role you want the overwrite permissions to be removed from.</param>
+        /// <param name="role">The role to remove the overwrite from.</param>
         /// <param name="options">The options to be used when sending the request.</param>
         /// <returns>
-        ///     An awaitable <see cref="Task"/>.
+        ///     A task representing the asynchronous operation for removing the specified permissions from the channel.
         /// </returns>
         public async Task RemovePermissionOverwriteAsync(IRole role, RequestOptions options = null)
         {
@@ -181,27 +179,27 @@ namespace Discord.Rest
         }
 
         /// <summary>
-        ///     Gets the invites for this channel.
+        ///     Gets a collection of all invites to this channel.
         /// </summary>
         /// <param name="options">The options to be used when sending the request.</param>
         /// <returns>
-        ///     An awaitable <see cref="Task"/> containing an <see cref="IReadOnlyCollection{RestInviteMetaData}"/>.
-        ///     <see cref="RestInviteMetadata"/> 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.
         /// </returns>
         public async Task<IReadOnlyCollection<RestInviteMetadata>> GetInvitesAsync(RequestOptions options = null)
             => await ChannelHelper.GetInvitesAsync(this, Discord, options).ConfigureAwait(false);
 
         /// <summary>
-        ///     Creates an invite for this channel.
+        ///     Creates a new invite to this channel.
         /// </summary>
-        /// <param name="maxAge">The number of seconds that you want the invite to be valid for.</param>
-        /// <param name="maxUses">The number of times this invite can be used before it expires.</param>
-        /// <param name="isTemporary">Whether or not the invite grants temporary membership.</param>
-        /// <param name="isUnique">Whether to try reuse a similar invite or not.</param>
+        /// <param name="maxAge">The time (in seconds) until the invite expires. Set to <c>null</c> to never expire.</param>
+        /// <param name="maxUses">The max amount of times this invite may be used. Set to <c>null</c> to have unlimited uses.</param>
+        /// <param name="isTemporary">If <c>true</c>, the user accepting this invite will be kicked from the guild after closing their client.</param>
+        /// <param name="isUnique">If <c>true</c>, don't try to reuse a similar invite (useful for creating many unique one time use invites).</param>
         /// <param name="options">The options to be used when sending the request.</param>
         /// <returns>
-        ///     An awaitable <see cref="Task"/> containing a <see cref="RestInviteMetadata"/>.
+        ///     A task that represents the asynchronous invite creation operation. The task result contains an invite
+        ///     metadata object containing information for the created invite.
         /// </returns>
         public async Task<RestInviteMetadata> 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);

src/Discord.Net.Rest/Entities/Channels/RestTextChannel.cs

@@ -34,6 +34,7 @@ namespace Discord.Rest
             entity.Update(model);
             return entity;
         }
+        /// <inheritdoc />
         internal override void Update(Model model)
         {
             base.Update(model);
@@ -50,23 +51,31 @@ namespace Discord.Rest
         }
 
         /// <summary>
-        ///     Gets a user that is able to view this channel from the associate <paramref name="id"/>.
+        ///     Gets a user in this channel.
         /// </summary>
-        /// <param name="id">The snowflake identifier of the user you want to get.</param>
+        /// <param name="id">The snowflake identifier of the user.</param>
         /// <param name="options">The options to be used when sending the request.</param>
+        /// <exception cref="InvalidOperationException">
+        /// Resolving permissions requires the parent guild to be downloaded.
+        /// </exception>
         /// <returns>
-        ///     An awaitable <see cref="Task"/> containing a <see cref="RestGuildUser"/>.
+        ///     A task representing the asynchronous get operation. The task result contains a guild user object that
+        ///     represents the user; <c>null</c> if none is found.
         /// </returns>
         public Task<RestGuildUser> GetUserAsync(ulong id, RequestOptions options = null)
             => ChannelHelper.GetUserAsync(this, Guild, Discord, id, options);
 
         /// <summary>
-        ///     Gets the collection of users that can view this channel.
+        ///     Gets a collection of users that are able to view the channel.
         /// </summary>
         /// <param name="options">The options to be used when sending the request.</param>
+        /// <exception cref="InvalidOperationException">
+        /// Resolving permissions requires the parent guild to be downloaded.
+        /// </exception>
         /// <returns>
-        ///     Paged collection of users. Flattening the paginated response into a collection of <see cref="RestGuildUser"/>
-        ///     with <see cref="AsyncEnumerableExtensions.FlattenAsync{T}"/> 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 
+        ///     <see cref="AsyncEnumerableExtensions.FlattenAsync{T}"/> is required if you wish to access the users.
         /// </returns>
         public IAsyncEnumerable<IReadOnlyCollection<RestGuildUser>> GetUsersAsync(RequestOptions options = null)
             => ChannelHelper.GetUsersAsync(this, Guild, Discord, null, null, options);
@@ -147,27 +156,46 @@ namespace Discord.Rest
             => ChannelHelper.EnterTypingState(this, Discord, options);
 
         /// <summary>
-        ///     Creates a webhook for this channel.
+        ///     Creates a webhook in this text channel.
         /// </summary>
-        /// <param name="name">The name you want to give the webhook.</param>
-        /// <param name="avatar">The avatar that you want the webook to have.</param>
+        /// <param name="name">The name of the webhook.</param>
+        /// <param name="avatar">The avatar of the webhook.</param>
         /// <param name="options">The options to be used when sending the request.</param>
         /// <returns>
-        ///     An awaitable <see cref="Task"/> containing a <see cref="RestWebhook"/>.
+        ///     A task that represents the asynchronous creation operation. The task result contains the newly created
+        ///     webhook.
         /// </returns>
         public Task<RestWebhook> CreateWebhookAsync(string name, Stream avatar = null, RequestOptions options = null)
             => ChannelHelper.CreateWebhookAsync(this, Discord, name, avatar, options);
+        /// <summary>
+        ///     Gets a webhook available in this text channel.
+        /// </summary>
+        /// <param name="id">The identifier of the webhook.</param>
+        /// <param name="options">The options to be used when sending the request.</param>
+        /// <returns>
+        ///     A task that represents the asynchronous get operation. The task result contains a webhook associated
+        ///     with the identifier; <c>null</c> if the webhook is not found.
+        /// </returns>
         public Task<RestWebhook> GetWebhookAsync(ulong id, RequestOptions options = null)
             => ChannelHelper.GetWebhookAsync(this, Discord, id, options);
+        /// <summary>
+        ///     Gets the webhooks available in this text channel.
+        /// </summary>
+        /// <param name="options">The options to be used when sending the request.</param>
+        /// <returns>
+        ///     A task that represents the asynchronous get operation. The task result contains a read-only collection
+        ///     of webhooks that is available in this channel.
+        /// </returns>
         public Task<IReadOnlyCollection<RestWebhook>> GetWebhooksAsync(RequestOptions options = null)
             => ChannelHelper.GetWebhooksAsync(this, Discord, options);
 
         /// <summary>
-        ///     Gets the parent category of this channel.
+        ///     Gets the parent (category) channel of this channel.
         /// </summary>
         /// <param name="options">The options to be used when sending the request.</param>
         /// <returns>
-        ///     An awaitable <see cref="Task"/> containing an <see cref="ICategoryChannel"/>.
+        ///     A task that represents the asynchronous get operation. The task result contains the category channel
+        ///     representing the parent of this channel; <c>null</c> if none is set.
         /// </returns>
         public Task<ICategoryChannel> GetCategoryAsync(RequestOptions options = null)
             => ChannelHelper.GetCategoryAsync(this, Discord, options);

src/Discord.Net.Rest/Entities/Channels/RestVoiceChannel.cs

@@ -48,11 +48,12 @@ namespace Discord.Rest
         }
 
         /// <summary>
-        ///     Gets the parent category of this channel.
+        ///     Gets the parent (category) channel of this channel.
         /// </summary>
         /// <param name="options">The options to be used when sending the request.</param>
         /// <returns>
-        ///     An awaitable <see cref="Task"/> containing an <see cref="ICategoryChannel"/>.
+        ///     A task that represents the asynchronous get operation. The task result contains the category channel
+        ///     representing the parent of this channel; <c>null</c> if none is set.
         /// </returns>
         public Task<ICategoryChannel> GetCategoryAsync(RequestOptions options = null)
             => ChannelHelper.GetCategoryAsync(this, Discord, options);

src/Discord.Net.WebSocket/BaseSocketClient.cs

@@ -16,33 +16,60 @@ namespace Discord.WebSocket
         /// <summary>
         ///     Gets the estimated round-trip latency, in milliseconds, to the gateway server.
         /// </summary>
+        /// <returns>
+        ///     An <see cref="int"/> 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.
+        /// </returns>
         public abstract int Latency { get; protected set; }
         /// <summary>
         ///     Gets the status for the logged-in user.
         /// </summary>
+        /// <returns>
+        ///     A status object that represents the user's online presence status.
+        /// </returns>
         public abstract UserStatus Status { get; protected set; }
         /// <summary>
         ///     Gets the activity for the logged-in user.
         /// </summary>
+        /// <returns>
+        ///     An activity object that represents the user's current activity.
+        /// </returns>
         public abstract IActivity Activity { get; protected set; }
 
         internal new DiscordSocketApiClient ApiClient => base.ApiClient as DiscordSocketApiClient;
 
         /// <summary>
-        /// Gets the current logged-in user.
+        ///     Gets the current logged-in user.
         /// </summary>
         public new SocketSelfUser CurrentUser { get => base.CurrentUser as SocketSelfUser; protected set => base.CurrentUser = value; }
         /// <summary>
-        ///     Gets a collection of guilds that the logged-in user is currently in.
+        ///     Gets a collection of guilds that the user is currently in.
         /// </summary>
+        /// <returns>
+        ///     A read-only collection of guilds that the current user is in.
+        /// </returns>
         public abstract IReadOnlyCollection<SocketGuild> Guilds { get; }
         /// <summary>
-        ///     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.
         /// </summary>
+        /// <remarks>
+        ///     This method will retrieve all private channels (including direct-message, group channel and such) that
+        ///     are currently opened in this session.
+        ///     <note type="warning">
+        ///         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.
+        ///     </note>
+        /// </remarks>
+        /// <returns>
+        ///     A read-only collection of private channels that the user currently partakes in.
+        /// </returns>
         public abstract IReadOnlyCollection<ISocketPrivateChannel> PrivateChannels { get; }
         /// <summary>
-        ///     Gets a collection of available voice regions for the logged-in user.
+        ///     Gets a collection of available voice regions.
         /// </summary>
+        /// <returns>
+        ///     A read-only collection of voice regions that the user has access to.
+        /// </returns>
         public abstract IReadOnlyCollection<RestVoiceRegion> VoiceRegions { get; }
 
         internal BaseSocketClient(DiscordSocketConfig config, DiscordRestApiClient client)
@@ -59,7 +86,8 @@ namespace Discord.WebSocket
         /// </remarks>
         /// <param name="options">The options to be used when sending the request.</param>
         /// <returns>
-        ///     An awaitable <see cref="Task"/> containing the application information.
+        ///     A task that represents the asynchronous get operation. The task result contains the application
+        ///     information.
         /// </returns>
         public abstract Task<RestApplication> GetApplicationInfoAsync(RequestOptions options = null);
         /// <summary>
@@ -107,7 +135,7 @@ namespace Discord.WebSocket
         /// <summary>
         ///     Gets a channel.
         /// </summary>
-        /// <param name="id">The channel snowflake identifier.</param>
+        /// <param name="id">The snowflake identifier of the channel (e.g. `381889909113225237`).</param>
         /// <returns>
         ///     A generic WebSocket-based channel object (voice, text, category, etc.) associated with the identifier;
         ///     <c>null</c> when the channel cannot be found.
@@ -125,9 +153,10 @@ namespace Discord.WebSocket
         /// <summary>
         ///     Gets a voice region.
         /// </summary>
-        /// <param name="id">The unique identifier of the voice region.</param>
+        /// <param name="id">The identifier of the voice region (e.g. <c>eu-central</c> ).</param>
         /// <returns>
-        ///     A REST-based voice region; <c>null</c> if none can be found.
+        ///     A REST-based voice region associated with the identifier; <c>null</c> if the voice region is not
+        ///     found.
         /// </returns>
         public abstract RestVoiceRegion GetVoiceRegion(string id);
         /// <inheritdoc />
@@ -135,21 +164,21 @@ namespace Discord.WebSocket
         /// <inheritdoc />
         public abstract Task StopAsync();
         /// <summary>
-        ///     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).
         /// </summary>
         /// <param name="status">The new status to be set.</param>
         /// <returns>
-        ///     An awaitable <see cref="Task"/>.
+        ///     A task that represents the asynchronous set operation.
         /// </returns>
         public abstract Task SetStatusAsync(UserStatus status);
         /// <summary>
-        ///     Sets the game of the logged-in user.
+        ///     Sets the game of the user.
         /// </summary>
         /// <param name="name">The name of the game.</param>
         /// <param name="streamUrl">If streaming, the URL of the stream. Must be a valid Twitch URL.</param>
         /// <param name="type">The type of the game.</param>
         /// <returns>
-        ///     An awaitable <see cref="Task"/>.
+        ///     A task that represents the asynchronous set operation.
         /// </returns>
         public abstract Task SetGameAsync(string name, string streamUrl = null, ActivityType type = ActivityType.Playing);
         /// <summary>
@@ -167,7 +196,7 @@ namespace Discord.WebSocket
         /// </remarks>
         /// <param name="activity">The activty to be set.</param>
         /// <returns>
-        ///     An awaitable <see cref="Task"/>.
+        ///     A task that represents the asynchronous set operation.
         /// </returns>
         public abstract Task SetActivityAsync(IActivity activity);
         /// <summary>
@@ -175,7 +204,7 @@ namespace Discord.WebSocket
         /// </summary>
         /// <param name="guilds">The guilds to download the members from.</param>
         /// <returns>
-        ///     An awaitable <see cref="Task"/>.
+        ///     A task that represents the asynchronous download operation.
         /// </returns>
         public abstract Task DownloadUsersAsync(IEnumerable<IGuild> guilds);
 
@@ -193,26 +222,26 @@ namespace Discord.WebSocket
         /// <param name="jpegIcon">The icon of the guild.</param>
         /// <param name="options">The options to be used when sending the request.</param>
         /// <returns>
-        ///     An awaitable <see cref="Task"/> containing the newly created guild.
+        ///     A task that represents the asynchronous creation operation. The task result contains the created guild.
         /// </returns>
         public Task<RestGuild> CreateGuildAsync(string name, IVoiceRegion region, Stream jpegIcon = null, RequestOptions options = null)
             => ClientHelper.CreateGuildAsync(this, name, region, jpegIcon, options ?? RequestOptions.Default);
         /// <summary>
-        ///     Gets the connections that the logged-in user has set up.
+        ///     Gets the connections that the user has set up.
         /// </summary>
         /// <param name="options">The options to be used when sending the request.</param>
         /// <returns>
-        ///     An awaitable <see cref="Task"/> containing a collection of connections.
+        ///     A task that represents the asynchronous get operation. The task result contains a read-only collection of connections.
         /// </returns>
         public Task<IReadOnlyCollection<RestConnection>> GetConnectionsAsync(RequestOptions options = null)
             => ClientHelper.GetConnectionsAsync(this, options ?? RequestOptions.Default);
         /// <summary>
-        ///     Gets an invite with the provided invite identifier.
+        ///     Gets an invite.
         /// </summary>
         /// <param name="inviteId">The invitation identifier.</param>
         /// <param name="options">The options to be used when sending the request.</param>
         /// <returns>
-        ///     An awaitable <see cref="Task"/> containing the invite information.
+        ///     A task that represents the asynchronous get operation. The task result contains the invite information.
         /// </returns>
         public Task<RestInviteMetadata> GetInviteAsync(string inviteId, RequestOptions options = null)
             => ClientHelper.GetInviteAsync(this, inviteId, options ?? RequestOptions.Default);

src/Discord.Net.WebSocket/Entities/Channels/ISocketMessageChannel.cs

@@ -14,7 +14,7 @@ namespace Discord.WebSocket
         ///     Gets all messages in this channel's cache.
         /// </summary>
         /// <returns>
-        ///     A collection of WebSocket-based messages.
+        ///     A read-only collection of WebSocket-based messages.
         /// </returns>
         IReadOnlyCollection<SocketMessage> CachedMessages { get; }
 
@@ -22,46 +22,55 @@ namespace Discord.WebSocket
         ///     Sends a message to this message channel.
         /// </summary>
         /// <param name="text">The message to be sent.</param>
-        /// <param name="isTTS">Whether the message should be read aloud by Discord or not.</param>
-        /// <param name="embed">The <see cref="EmbedType.Rich"/> <see cref="Embed"/> to be sent.</param>
+        /// <param name="isTTS">Determines whether the message should be read aloud by Discord or not.</param>
+        /// <param name="embed">The <see cref="Discord.EmbedType.Rich"/> <see cref="Embed"/> to be sent.</param>
         /// <param name="options">The options to be used when sending the request.</param>
         /// <returns>
-        ///     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.
         /// </returns>
         new Task<RestUserMessage> SendMessageAsync(string text = null, bool isTTS = false, Embed embed = null, RequestOptions options = null);
         /// <summary>
-        ///     Sends a file to this message channel, with an optional caption.
+        ///     Sends a file to this message channel with an optional caption.
         /// </summary>
+        /// <remarks>
+        ///     This method sends a file as if you are uploading an attachment directly from your Discord client.
+        ///     <note>
+        ///         If you wish to upload an image and have it embedded in a <see cref="Discord.EmbedType.Rich"/>embed,
+        ///         you may upload the file and refer to the file with "attachment://filename.ext" in the
+        ///         <see cref="Discord.EmbedBuilder.ImageUrl"/>.
+        ///     </note>
+        /// </remarks>
         /// <param name="filePath">The file path of the file.</param>
         /// <param name="text">The message to be sent.</param>
         /// <param name="isTTS">Whether the message should be read aloud by Discord or not.</param>
-        /// <param name="embed">The <see cref="EmbedType.Rich"/> <see cref="Embed"/> to be sent.</param>
+        /// <param name="embed">The <see cref="Discord.EmbedType.Rich" /> <see cref="Embed" /> to be sent.</param>
         /// <param name="options">The options to be used when sending the request.</param>
-        /// <remarks>
-        ///     If you wish to upload an image and have it embedded in a <see cref="EmbedType.Rich"/> embed, you may
-        ///     upload the file and refer to the file with "attachment://filename.ext" in the 
-        ///     <see cref="Discord.EmbedBuilder.ImageUrl"/>.
-        /// </remarks>
         /// <returns>
-        ///     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.
         /// </returns>
         new Task<RestUserMessage> SendFileAsync(string filePath, string text = null, bool isTTS = false, Embed embed = null, RequestOptions options = null);
         /// <summary>
-        ///     Sends a file to this message channel, with an optional caption.
+        ///     Sends a file to this message channel with an optional caption.
         /// </summary>
-        /// <param name="stream">The <see cref="Stream"/> of the file to be sent.</param>
+        /// <remarks>
+        ///     This method sends a file as if you are uploading an attachment directly from your Discord client.
+        ///     <note>
+        ///         If you wish to upload an image and have it embedded in a <see cref="Discord.EmbedType.Rich"/>embed,
+        ///         you may upload the file and refer to the file with "attachment://filename.ext" in the
+        ///         <see cref="Discord.EmbedBuilder.ImageUrl"/>.
+        ///     </note>
+        /// </remarks>
+        /// <param name="stream">The <see cref="Stream" /> of the file to be sent.</param>
         /// <param name="filename">The name of the attachment.</param>
         /// <param name="text">The message to be sent.</param>
         /// <param name="isTTS">Whether the message should be read aloud by Discord or not.</param>
-        /// <param name="embed">The <see cref="EmbedType.Rich"/> <see cref="Embed"/> to be sent.</param>
+        /// <param name="embed">The <see cref="Discord.EmbedType.Rich"/> <see cref="Embed"/> to be sent.</param>
         /// <param name="options">The options to be used when sending the request.</param>
-        /// <remarks>
-        ///     If you wish to upload an image and have it embedded in a <see cref="EmbedType.Rich"/> embed, you may
-        ///     upload the file and refer to the file with "attachment://filename.ext" in the 
-        ///     <see cref="Discord.EmbedBuilder.ImageUrl"/>.
-        /// </remarks>
         /// <returns>
-        ///     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.
         /// </returns>
         new Task<RestUserMessage> SendFileAsync(Stream stream, string filename, string text = null, bool isTTS = false, Embed embed = null, RequestOptions options = null);
 
@@ -78,7 +87,7 @@ namespace Discord.WebSocket
         /// </summary>
         /// <param name="limit">The number of messages to get.</param>
         /// <returns>
-        ///     A collection of WebSocket-based messages.
+        ///     A read-only collection of WebSocket-based messages.
         /// </returns>
         IReadOnlyCollection<SocketMessage> GetCachedMessages(int limit = DiscordConfig.MaxMessagesPerBatch);
 
@@ -89,7 +98,7 @@ namespace Discord.WebSocket
         /// <param name="dir">The direction of which the message should be gotten from.</param>
         /// <param name="limit">The number of messages to get.</param>
         /// <returns>
-        ///     A collection of WebSocket-based messages.
+        ///     A read-only collection of WebSocket-based messages.
         /// </returns>
         IReadOnlyCollection<SocketMessage> GetCachedMessages(ulong fromMessageId, Direction dir, int limit = DiscordConfig.MaxMessagesPerBatch);
         /// <summary>
@@ -99,7 +108,7 @@ namespace Discord.WebSocket
         /// <param name="dir">The direction of which the message should be gotten from.</param>
         /// <param name="limit">The number of messages to get.</param>
         /// <returns>
-        ///     A collection of WebSocket-based messages.
+        ///     A read-only collection of WebSocket-based messages.
         /// </returns>
         IReadOnlyCollection<SocketMessage> GetCachedMessages(IMessage fromMessage, Direction dir, int limit = DiscordConfig.MaxMessagesPerBatch);
         /// <summary>
@@ -107,7 +116,8 @@ namespace Discord.WebSocket
         /// </summary>
         /// <param name="options">The options to be used when sending the request.</param>
         /// <returns>
-        ///     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.
         /// </returns>
         new Task<IReadOnlyCollection<RestMessage>> GetPinnedMessagesAsync(RequestOptions options = null);
     }

src/Discord.Net.WebSocket/Entities/Channels/SocketGuildChannel.cs

@@ -21,7 +21,7 @@ namespace Discord.WebSocket
         ///     Gets the guild associated with this channel.
         /// </summary>
         /// <returns>
-        ///     A guild that this channel belongs to.
+        ///     A guild object that this channel belongs to.
         /// </returns>
         public SocketGuild Guild { get; }
         /// <inheritdoc />
@@ -35,7 +35,7 @@ namespace Discord.WebSocket
         ///     Gets a collection of users that are able to view the channel.
         /// </summary>
         /// <returns>
-        ///     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).
         /// </returns>
         public new virtual IReadOnlyCollection<SocketGuildUser> Users => ImmutableArray.Create<SocketGuildUser>();
 
@@ -59,6 +59,7 @@ namespace Discord.WebSocket
                     return new SocketGuildChannel(guild.Discord, model.Id, guild);
             }
         }
+        /// <inheritdoc />
         internal override void Update(ClientState state, Model model)
         {
             Name = model.Name.Value;
@@ -79,11 +80,11 @@ namespace Discord.WebSocket
             => ChannelHelper.DeleteAsync(this, Discord, options);
 
         /// <summary>
-        ///     Gets the overwrite permissions of the specified <paramref name="user"/>.
+        ///     Gets the permission overwrite for a specific user.
         /// </summary>
-        /// <param name="user">The user that you want to get the overwrite permissions for.</param>
+        /// <param name="user">The user to get the overwrite from.</param>
         /// <returns>
-        ///     The overwrite permissions for the requested user; otherwise <c>null</c>.
+        ///     An overwrite object for the targeted user; <c>null</c> if none is set.
         /// </returns>
         public OverwritePermissions? GetPermissionOverwrite(IUser user)
         {
@@ -94,13 +95,12 @@ namespace Discord.WebSocket
             }
             return null;
         }
-
         /// <summary>
-        ///     Gets the overwrite permissions of the specified <paramref name="role"/>.
+        ///     Gets the permission overwrite for a specific role.
         /// </summary>
-        /// <param name="role">The role that you want to get the overwrite permissions for.</param>
+        /// <param name="role">The role to get the overwrite from.</param>
         /// <returns>
-        ///     The overwrite permissions for the requested role; otherwise <c>null</c>.
+        ///     An overwrite object for the targeted role; <c>null</c> if none is set.
         /// </returns>
         public OverwritePermissions? GetPermissionOverwrite(IRole role)
         {
@@ -113,41 +113,41 @@ namespace Discord.WebSocket
         }
 
         /// <summary>
-        ///     Adds an overwrite permission for the specified <paramref name="user"/>.
+        ///     Adds or updates the permission overwrite for the given user.
         /// </summary>
-        /// <param name="user">The user you want the overwrite permission to apply to.</param>
-        /// <param name="perms">The overwrite permission you want to add.</param>
+        /// <param name="user">The user to add the overwrite to.</param>
+        /// <param name="permissions">The overwrite to add to the user.</param>
         /// <param name="options">The options to be used when sending the request.</param>
         /// <returns>
-        ///     An awaitable <see cref="Task"/>.
+        ///     A task representing the asynchronous permission operation for adding the specified permissions to the channel.
         /// </returns>
-        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)));
         }
 
         /// <summary>
-        ///     Adds an overwrite permission for the specified <paramref name="role"/>.
+        ///     Adds or updates the permission overwrite for the given role.
         /// </summary>
-        /// <param name="role">The role you want the overwrite permission to apply to.</param>
-        /// <param name="perms">The overwrite permission you want to add.</param>
-        /// <param name="options">The options to be used when sending the request. </param>
+        /// <param name="role">The role to add the overwrite to.</param>
+        /// <param name="permissions">The overwrite to add to the role.</param>
+        /// <param name="options">The options to be used when sending the request.</param>
         /// <returns>
-        ///     An awaitable <see cref="Task"/>.
+        ///     A task representing the asynchronous permission operation for adding the specified permissions to the channel.
         /// </returns>
-        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)));
         }
         /// <summary>
-        ///     Removes an overwrite permission for the specified <paramref name="user"/>.
+        ///     Removes the permission overwrite for the given user, if one exists.
         /// </summary>
-        /// <param name="user">The user you want to remove the overwrite permission from.</param>
+        /// <param name="user">The user to remove the overwrite from.</param>
         /// <param name="options">The options to be used when sending the request.</param>
         /// <returns>
-        ///     An awaitable <see cref="Task"/>.
+        ///     A task representing the asynchronous operation for removing the specified permissions from the channel.
         /// </returns>
         public async Task RemovePermissionOverwriteAsync(IUser user, RequestOptions options = null)
         {
@@ -163,12 +163,12 @@ namespace Discord.WebSocket
             }
         }
         /// <summary>
-        ///     Removes an overwrite permission for the specified <paramref name="role"/>.
+        ///     Removes the permission overwrite for the given role, if one exists.
         /// </summary>
-        /// <param name="role">The role you want the overwrite permissions to be removed from.</param>
+        /// <param name="role">The role to remove the overwrite from.</param>
         /// <param name="options">The options to be used when sending the request.</param>
         /// <returns>
-        ///     An awaitable <see cref="Task"/>.
+        ///     A task representing the asynchronous operation for removing the specified permissions from the channel.
         /// </returns>
         public async Task RemovePermissionOverwriteAsync(IRole role, RequestOptions options = null)
         {
@@ -185,26 +185,26 @@ namespace Discord.WebSocket
         }
 
         /// <summary>
-        ///     Gets the invites for this channel.
+        ///     Returns a collection of all invites to this channel.
         /// </summary>
         /// <param name="options">The options to be used when sending the request.</param>
         /// <returns>
-        ///     An awaitable <see cref="Task"/> containing an <see cref="IReadOnlyCollection{RestInviteMetaData}"/>.
-        ///     <see cref="RestInviteMetadata"/> 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.
         /// </returns>
         public async Task<IReadOnlyCollection<RestInviteMetadata>> GetInvitesAsync(RequestOptions options = null)
             => await ChannelHelper.GetInvitesAsync(this, Discord, options).ConfigureAwait(false);
         /// <summary>
-        ///     Creates an invite for this channel.
+        ///     Creates a new invite to this channel.
         /// </summary>
-        /// <param name="maxAge">The number of seconds that you want the invite to be valid for.</param>
-        /// <param name="maxUses">The number of times this invite can be used before it expires.</param>
-        /// <param name="isTemporary">Whether or not the invite grants temporary membership.</param>
-        /// <param name="isUnique">Whether to try reuse a similar invite or not.</param>
+        /// <param name="maxAge">The time (in seconds) until the invite expires. Set to <c>null</c> to never expire.</param>
+        /// <param name="maxUses">The max amount of times this invite may be used. Set to <c>null</c> to have unlimited uses.</param>
+        /// <param name="isTemporary">If <c>true</c>, the user accepting this invite will be kicked from the guild after closing their client.</param>
+        /// <param name="isUnique">If <c>true</c>, don't try to reuse a similar invite (useful for creating many unique one time use invites).</param>
         /// <param name="options">The options to be used when sending the request.</param>
         /// <returns>
-        ///     An awaitable <see cref="Task"/> containing a <see cref="RestInviteMetadata"/>.
+        ///     A task that represents the asynchronous invite creation operation. The task result contains an invite
+        ///     metadata object containing information for the created invite.
         /// </returns>
         public async Task<RestInviteMetadata> 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
         /// <summary>
         ///     Gets the name of the channel.
         /// </summary>
+        /// <returns>
+        ///     A string that resolves to <see cref="SocketGuildChannel.Name"/>.
+        /// </returns>
         public override string ToString() => Name;
         private string DebuggerDisplay => $"{Name} ({Id}, Guild)";
+        /// <inheritdoc />
         internal new SocketGuildChannel Clone() => MemberwiseClone() as SocketGuildChannel;
 
         //SocketChannel
+        /// <inheritdoc />
         internal override IReadOnlyCollection<SocketUser> GetUsersInternal() => Users;
+        /// <inheritdoc />
         internal override SocketUser GetUserInternal(ulong id) => GetUser(id);
 
         //IGuildChannel

src/Discord.Net.WebSocket/Entities/Channels/SocketTextChannel.cs

@@ -76,11 +76,11 @@ namespace Discord.WebSocket
         /// <summary>
         ///     Gets a message from this message channel.
         /// </summary>
-        /// <param name="id">The ID of the message.</param>
+        /// <param name="id">The snowflake identifier of the message.</param>
         /// <param name="options">The options to be used when sending the request.</param>
         /// <returns>
-        ///     An awaitable <see cref="Task"/> containing the downloaded message; <c>null</c> 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; <c>null</c> if no message is found with the specified identifier.
         /// </returns>
         public async Task<IMessage> GetMessageAsync(ulong id, RequestOptions options = null)
         {
@@ -202,7 +202,8 @@ namespace Discord.WebSocket
         /// <param name="avatar">The avatar of the webhook.</param>
         /// <param name="options">The options to be used when sending the request.</param>
         /// <returns>
-        ///     An awaitable <see cref="Task"/> containing the created webhook.
+        ///     A task that represents the asynchronous creation operation. The task result contains the newly created
+        ///     webhook.
         /// </returns>
         public Task<RestWebhook> CreateWebhookAsync(string name, Stream avatar = null, RequestOptions options = null)
             => ChannelHelper.CreateWebhookAsync(this, Discord, name, avatar, options);
@@ -212,8 +213,8 @@ namespace Discord.WebSocket
         /// <param name="id">The identifier of the webhook.</param>
         /// <param name="options">The options to be used when sending the request.</param>
         /// <returns>
-        ///     An awaitable <see cref="Task"/> containing a webhook associated with the identifier; <c>null</c> if not
-        ///     found.
+        ///     A task that represents the asynchronous get operation. The task result contains a webhook associated
+        ///     with the identifier; <c>null</c> if the webhook is not found.
         /// </returns>
         public Task<RestWebhook> GetWebhookAsync(ulong id, RequestOptions options = null)
             => ChannelHelper.GetWebhookAsync(this, Discord, id, options);
@@ -222,7 +223,8 @@ namespace Discord.WebSocket
         /// </summary>
         /// <param name="options">The options to be used when sending the request.</param>
         /// <returns>
-        ///     An awaitable <see cref="Task"/> 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.
         /// </returns>
         public Task<IReadOnlyCollection<RestWebhook>> GetWebhooksAsync(RequestOptions options = null)
             => ChannelHelper.GetWebhooksAsync(this, Discord, options);

src/Discord.Net.WebSocket/Entities/Channels/SocketVoiceChannel.cs

@@ -23,10 +23,10 @@ namespace Discord.WebSocket
         /// <inheritdoc />
         public ulong? CategoryId { get; private set; }
         /// <summary>
-        ///     Gets the parent (category) of this channel in the guild's channel list.
+        ///     Gets the parent (category) channel of this channel.
         /// </summary>
         /// <returns>
-        ///     An <see cref="ICategoryChannel"/> representing the parent of this channel; <c>null</c> if none is set.
+        ///     A category channel representing the parent of this channel; <c>null</c> if none is set.
         /// </returns>
         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;
         }
+        /// <inheritdoc />
         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);
         }
 
-        /// <summary>
-        ///     Disconnects from this voice channel if the client is in an active voice connection.
-        /// </summary>
-        /// <returns>
-        ///     An awaitable <see cref="Task" /> .
-        /// </returns>
+        /// <inheritdoc />
         public async Task DisconnectAsync()
             => await Guild.DisconnectAudioAsync();
 

src/Discord.Net.WebSocket/Entities/Guilds/SocketGuild.cs

@@ -738,21 +738,23 @@ namespace Discord.WebSocket
 
         //Webhooks
         /// <summary>
-        ///     Returns the webhook with the provided ID.
+        ///     Gets a webhook found within this guild.
         /// </summary>
-        /// <param name="id">The ID of the webhook.</param>
+        /// <param name="id">The identifier for the webhook.</param>
         /// <param name="options">The options to be used when sending the request.</param>
         /// <returns>
-        ///     An awaitable <see cref="Task"/> containing the webhook associated with the ID.
+        ///     A task that represents the asynchronous get operation. The task result contains the webhook with the
+        ///     specified <paramref name="id"/>; <c>null</c> if none is found.
         /// </returns>
         public Task<RestWebhook> GetWebhookAsync(ulong id, RequestOptions options = null)
             => GuildHelper.GetWebhookAsync(this, Discord, id, options);
         /// <summary>
-        ///     Gets a collection of webhooks that exist in the guild.
+        ///     Gets a collection of all webhook from this guild.
         /// </summary>
         /// <param name="options">The options to be used when sending the request.</param>
         /// <returns>
-        ///     An awaitable <see cref="Task"/> 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.
         /// </returns>
         public Task<IReadOnlyCollection<RestWebhook>> GetWebhooksAsync(RequestOptions options = null)
             => GuildHelper.GetWebhooksAsync(this, Discord, options);