Add XML docs & patch return types

+ Starting from this commit, all return types for tasks will use style similar to most documentations featured on docs.microsoft.com

References:
https://docs.microsoft.com/en-us/dotnet/api/microsoft.entityframeworkcore.dbcontext.-ctor?view=efcore-2.1
https://docs.microsoft.com/en-us/dotnet/api/system.io.filestream.readasync?view=netcore-2.1
https://docs.microsoft.com/en-us/dotnet/api/system.io.textwriter.writelineasync?view=netcore-2.1#System_IO_TextWriter_WriteLineAsync_System_Char___
And many more other asynchronous method documentations featured in the latest BCL.

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

@@ -10,8 +10,11 @@ namespace Discord
         ///     Gets or sets the channel to this name.
         /// </summary>
         /// <remarks>
-        ///     When modifying an <see cref="ITextChannel" />, the <see cref="Name" />
-        ///     MUST be alphanumeric with dashes. It must match the following RegEx: [a-z0-9-_]{2,100}
+        ///     This property defines the new name for this channel.
+        ///     <note type="warning">
+        ///         When modifying an <see cref="ITextChannel"/>, the <see cref="Name"/> must be alphanumeric with
+        ///         dashes. It must match the RegEx <c>[a-z0-9-_]{2,100}</c>.
+        ///     </note>
         /// </remarks>
         public Optional<string> Name { get; set; }
         /// <summary>

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

@@ -12,9 +12,21 @@ namespace Discord
         /// <summary>
         ///     Connects to this audio channel.
         /// </summary>
+        /// <param name="selfDeaf">Determines whether the client should deaf itself upon connection.</param>
+        /// <param name="selfMute">Determines whether the client should mute itself upon connection.</param>
+        /// <param name="external">Determines whether the audio client is an external one or not.</param>
+        /// <returns>
+        ///     A task representing the asynchronous connection operation. The task result contains the
+        ///     <see cref="IAudioClient"/> responsible for the connection.
+        /// </returns>
         Task<IAudioClient> ConnectAsync(bool selfDeaf = false, bool selfMute = false, bool external = false);
 
-        /// <summary> Disconnects from this audio channel. </summary>
+        /// <summary>
+        ///     Disconnects from this audio channel.
+        /// </summary>
+        /// <returns>
+        ///     A task representing the asynchronous disconnection operation.
+        /// </returns>
         Task DisconnectAsync();
     }
 }

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

@@ -31,11 +31,12 @@ namespace Discord
         /// <summary>
         ///     Gets a user in this channel.
         /// </summary>
-        /// <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="id">The snowflake identifier of the user (e.g. <c>168693960628371456</c>).</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 user object that represents the user.
+        ///     A task that represents the asynchronous get operation. The task result contains a user object that
+        ///     represents the found user; <c>null</c> if none is found.
         /// </returns>
         Task<IUser> GetUserAsync(ulong id, CacheMode mode = CacheMode.AllowDownload, RequestOptions options = null);
     }

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

@@ -10,12 +10,18 @@ namespace Discord
         /// <summary>
         ///     Gets the recipient of all messages in this channel.
         /// </summary>
+        /// <returns>
+        ///     A user object that represents the other user in this channel.
+        /// </returns>
         IUser Recipient { get; }
 
         /// <summary>
         ///     Closes this private channel, removing it from your channel list.
         /// </summary>
         /// <param name="options">The options to be used when sending the request.</param>
+        /// <returns>
+        ///     A task that represents the asynchronous close operation.
+        /// </returns>
         Task CloseAsync(RequestOptions options = null);
     }
 }

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

@@ -11,6 +11,9 @@ namespace Discord
         ///     Leaves this group.
         /// </summary>
         /// <param name="options">The options to be used when sending the request.</param>
+        /// <returns>
+        ///     A task that represents the asynchronous leave operation.
+        /// </returns>
         Task LeaveAsync(RequestOptions options = null);
     }
 }

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

@@ -16,7 +16,8 @@ namespace Discord
         ///     Gets the position of this channel.
         /// </summary>
         /// <returns>
-        ///     The position of this channel in the guild's channel list, relative to others of the same type.
+        ///     An <see cref="int"/> representing the position of this channel in the guild's channel list relative to
+        ///     others of the same type.
         /// </returns>
         int Position { get; }
 
@@ -24,14 +25,15 @@ namespace Discord
         ///     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>
         IGuild Guild { get; }
         /// <summary>
         ///     Gets the guild ID associated with this channel.
         /// </summary>
         /// <returns>
-        ///     A guild snowflake identifier for the guild that this channel belongs to.
+        ///     An <see cref="ulong"/> representing the guild snowflake identifier for the guild that this channel
+        ///     belongs to.
         /// </returns>
         ulong GuildId { get; }
         /// <summary>
@@ -45,25 +47,14 @@ namespace Discord
         /// <summary>
         ///     Creates a new invite to this channel.
         /// </summary>
-        /// <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>, a 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>
+        /// <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 an invite metadata object containing information for the
-        ///     created invite. 
+        ///     A task that represents the asynchronous invite creation operation. The task result contains an invite
+        ///     metadata object containing information for the created invite.
         /// </returns>
         Task<IInviteMetadata> CreateInviteAsync(int? maxAge = 86400, int? maxUses = default(int?), bool isTemporary = false, bool isUnique = false, RequestOptions options = null);
         /// <summary>
@@ -71,18 +62,18 @@ namespace Discord
         /// </summary>
         /// <param name="options">The options to be used when sending the request.</param>
         /// <returns>
-        ///     An awaitable <see cref="Task"/> containing a read-only collection of invite metadata that are created
-        ///     for this channel.
+        ///     A task that represents the asynchronous get operation. The task result contains a read-only collection
+        ///     of invite metadata that are created for this channel.
         /// </returns>
         Task<IReadOnlyCollection<IInviteMetadata>> GetInvitesAsync(RequestOptions options = null);
 
         /// <summary>
         ///     Modifies this guild channel.
         /// </summary>
-        /// <param name="func">The properties to modify the channel with.</param>
+        /// <param name="func">The delegate containing the properties to modify the channel 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<GuildChannelProperties> func, RequestOptions options = null);
 
@@ -108,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>
-        ///     An awaitable <see cref="Task"/>.
+        ///     A task representing the asynchronous removal operation.
         /// </returns>
         Task RemovePermissionOverwriteAsync(IRole role, RequestOptions options = null);
         /// <summary>
@@ -117,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>
-        ///     An awaitable <see cref="Task"/>.
+        ///     A task representing the asynchronous removal operation.
         /// </returns>
         Task RemovePermissionOverwriteAsync(IUser user, RequestOptions options = null);
 
@@ -128,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>
-        ///     An awaitable <see cref="Task"/>.
+        ///     A task representing the asynchronous permission addition operation.
         /// </returns>
         Task AddPermissionOverwriteAsync(IRole role, OverwritePermissions permissions, RequestOptions options = null);
         /// <summary>
@@ -138,7 +129,7 @@ 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>
-        ///     An awaitable <see cref="Task"/>.
+        ///     A task representing the asynchronous permission addition operation.
         /// </returns>
         Task AddPermissionOverwriteAsync(IUser user, OverwritePermissions permissions, RequestOptions options = null);
 
@@ -159,12 +150,11 @@ namespace Discord
         ///     Gets a user in this channel with the provided ID.
         /// </summary>
         /// <param name="id">The ID of the user.</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 a guild user object that represents the user.
+        ///     A task representing the asynchrnous get operation. The task result contains a guild user object that
+        ///     represents the user; <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

@@ -14,59 +14,67 @@ namespace Discord
         ///     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 asynchrnous 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);
         /// <summary>
         ///     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 asynchrnous 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);
         /// <summary>
         ///     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 <see cref="Task"/> containing the message sent to the channel.
+        ///     A task that represents an asynchrnous send operation for delievering the message. The task result
+        ///     contains the sent message.
         /// </returns>
         Task<IUserMessage> 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.
         /// </summary>
-        /// <param name="id">The ID of the message.</param>
-        /// <param name="mode">The <see cref="CacheMode"/> that determines whether the object should be fetched from
-        /// cache.</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>
-        ///     An awaitable <see cref="Task"/> containing the message gotten from either the cache or the download; 
-        ///     <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>
         Task<IMessage> GetMessageAsync(ulong id, CacheMode mode = CacheMode.AllowDownload, RequestOptions options = null);
 
@@ -116,25 +124,45 @@ namespace Discord
         /// </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>
         Task<IReadOnlyCollection<IMessage>> GetPinnedMessagesAsync(RequestOptions options = null);
 
-        /// <summary> Deletes a message based on the message ID in this channel. </summary>
+        /// <summary>
+        ///     Deletes a message.
+        /// </summary>
+        /// <param name="messageId">The snowflake identifier of the message that would be removed.</param>
+        /// <param name="options">The options to be used when sending the request.</param>
+        /// <returns>
+        ///     A task that represents the asynchronous removal operation.
+        /// </returns>
         Task DeleteMessageAsync(ulong messageId, RequestOptions options = null);
         /// <summary> Deletes a message based on the provided message in this channel. </summary>
+        /// <param name="message">The message that would be removed.</param>
+        /// <param name="options">The options to be used when sending the request.</param>
+        /// <returns>
+        ///     A task that represents the asynchronous removal operation.
+        /// </returns>
         Task DeleteMessageAsync(IMessage message, RequestOptions options = null);
 
         /// <summary>
         ///     Broadcasts the "user is typing" message to all users in this channel, lasting 10 seconds.
         /// </summary>
         /// <param name="options">The options to be used when sending the request.</param>
+        /// <returns>
+        ///     A task that represents the asynchronous operation that triggers the broadcast.
+        /// </returns>
         Task TriggerTypingAsync(RequestOptions options = null);
         /// <summary>
         ///     Continuously broadcasts the "user is typing" message to all users in this channel until the returned
         ///     object is disposed.
         /// </summary>
         /// <param name="options">The options to be used when sending the request.</param>
+        /// <returns>
+        ///     A disposable object that, upon its disposal, will stop the client from broadcasting its typing state in
+        ///     this channel.
+        /// </returns>
         IDisposable EnterTypingState(RequestOptions options = null);
     }
 }

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

@@ -11,7 +11,7 @@ namespace Discord
         ///     Gets the parent (category) ID of this channel in the guild's channel list.
         /// </summary>
         /// <returns>
-        ///     An <see cref="System.UInt64"/> representing the snowflake identifier of the parent of this channel; 
+        ///     A <see cref="ulong"/> representing the snowflake identifier of the parent of this channel; 
         ///     <c>null</c> if none is set.
         /// </returns>
         ulong? CategoryId { get; }
@@ -21,7 +21,8 @@ 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 category channel representing the parent of this channel; <c>null</c> if none is set.
+        ///     A task that represents the asynchrnous get operation. The task result contains the category channel
+        ///     representing the parent of this channel; <c>null</c> if none is set.
         /// </returns>
         Task<ICategoryChannel> GetCategoryAsync(CacheMode mode = CacheMode.AllowDownload, RequestOptions options = null);
     }

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

@@ -11,7 +11,7 @@ namespace Discord
         ///     Gets the users that can access this channel.
         /// </summary>
         /// <returns>
-        ///     A collection of users that can access this channel.
+        ///     A read-only collection of users that can access this channel.
         /// </returns>
         IReadOnlyCollection<IUser> Recipients { get; }
     }

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

@@ -14,7 +14,7 @@ namespace Discord
         ///     Determines whether the channel is NSFW.
         /// </summary>
         /// <returns>
-        ///     <c>true</c> if the channel has the NSFW flag enabled; otherwise, <c>false</c>.
+        ///     <c>true</c> if the channel has the NSFW flag enabled; otherwise <c>false</c>.
         /// </returns>
         bool IsNsfw { get; }
 
@@ -22,7 +22,7 @@ namespace Discord
         ///     Gets the current topic for this text channel.
         /// </summary>
         /// <returns>
-        ///     The topic set in the channel, or <c>null</c> if none is set.
+        ///     A string representing the topic set in the channel; <c>null</c> if none is set.
         /// </returns>
         string Topic { get; }
 
@@ -30,30 +30,42 @@ namespace Discord
         ///     Bulk-deletes multiple messages.
         /// </summary>
         /// <remarks>
+        ///     This method attempts to remove the messages specified in bulk.
         ///     <note type="important">
-        ///     This method can only remove messages that are posted within 14 days!
+        ///         Due to the limitation set by Discord, this method can only remove messages that are posted within 14 days!
         ///     </note>
         /// </remarks>
         /// <param name="messages">The messages to be bulk-deleted.</param>
         /// <param name="options">The options to be used when sending the request.</param>
+        /// <returns>
+        ///     A task that represents the asynchronous bulk-removal operation.
+        /// </returns>
         Task DeleteMessagesAsync(IEnumerable<IMessage> messages, RequestOptions options = null);
         /// <summary>
         ///     Bulk-deletes multiple messages.
         /// </summary>
         /// <remarks>
+        ///     This method attempts to remove the messages specified in bulk.
         ///     <note type="important">
-        ///     This method can only remove messages that are posted within 14 days!
+        ///         Due to the limitation set by Discord, this method can only remove messages that are posted within 14 days!
         ///     </note>
         /// </remarks>
-        /// <param name="messageIds">The IDs of the messages to be bulk-deleted.</param>
+        /// <param name="messageIds">The snowflake identifier of the messages to be bulk-deleted.</param>
         /// <param name="options">The options to be used when sending the request.</param>
+        /// <returns>
+        ///     A task that represents the asynchronous bulk-removal operation.
+        /// </returns>
         Task DeleteMessagesAsync(IEnumerable<ulong> messageIds, RequestOptions options = null);
 
         /// <summary>
         ///     Modifies this text channel.
         /// </summary>
-        /// <param name="func">The properties to modify the channel with.</param>
+        /// <param name="func">The delegate containing the properties to modify the channel with.</param>
         /// <param name="options">The options to be used when sending the request.</param>
+        /// <returns>
+        ///     A task that represents the asynchronous modification operation.
+        /// </returns>
+        /// <seealso cref="TextChannelProperties"/>
         Task ModifyAsync(Action<TextChannelProperties> func, RequestOptions options = null);
         
         /// <summary>
@@ -63,7 +75,8 @@ namespace Discord
         /// <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>
         Task<IWebhook> CreateWebhookAsync(string name, Stream avatar = null, RequestOptions options = null);
         /// <summary>
@@ -72,8 +85,8 @@ namespace Discord
         /// <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>
         Task<IWebhook> GetWebhookAsync(ulong id, RequestOptions options = null);
         /// <summary>
@@ -81,7 +94,8 @@ namespace Discord
         /// </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>
         Task<IReadOnlyCollection<IWebhook>> GetWebhooksAsync(RequestOptions options = null);
     }

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

@@ -9,13 +9,20 @@ namespace Discord
     public interface IVoiceChannel : INestedChannel, IAudioChannel
     {
         /// <summary>
-        ///     Gets the bitrate, in bits per second, clients in this voice channel are requested to use.
+        ///     Gets the bitrate that the clients in this voice channel are requested to use.
         /// </summary>
+        /// <returns>
+        ///     An <see cref="int"/> representing the bitrate (bps) that this voice channel defines and requests the
+        ///     client(s) to use.
+        /// </returns>
         int Bitrate { get; }
         /// <summary>
-        ///     Gets the max amount of users allowed to be connected to this channel at one time, or
-        ///     <c>null</c> if none is set.
+        ///     Gets the max number of users allowed to be connected to this channel at once.
         /// </summary>
+        /// <returns>
+        ///     An <see cref="int"/> representing the maxmimum number of users that are allowed to be connected to this
+        ///     channel at once; <c>null</c> if a limit is not set.
+        /// </returns>
         int? UserLimit { get; }
 
         /// <summary>
@@ -23,6 +30,10 @@ namespace Discord
         /// </summary>
         /// <param name="func">The properties to modify the channel with.</param>
         /// <param name="options">The options to be used when sending the request.</param>
+        /// <returns>
+        ///     A task that represents the asynchronous modification operation.
+        /// </returns>
+        /// <seealso cref="VoiceChannelProperties"/>
         Task ModifyAsync(Action<VoiceChannelProperties> func, RequestOptions options = null);
     }
 }

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

@@ -1,7 +1,7 @@
 namespace Discord
 {
     /// <summary>
-    ///     Properties that are used to reorder an <see cref="IGuildChannel"/>.
+    ///     Provides properties that are used to reorder an <see cref="IGuildChannel"/>.
     /// </summary>
     public class ReorderChannelProperties
     {
@@ -20,7 +20,7 @@ namespace Discord
         /// </returns>
         public int Position { get; }
 
-        /// <summary> Creates a <see cref="ReorderChannelProperties"/> used to reorder a channel. </summary>
+        /// <summary> Initializes a new instance of the <see cref="ReorderChannelProperties"/> class used to reorder a channel. </summary>
         /// <param name="id"> Sets the ID of the channel to apply this position to. </param>
         /// <param name="position"> Sets the new zero-based position of this channel. </param>
         public ReorderChannelProperties(ulong id, int position)

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

@@ -1,11 +1,9 @@
-using System;
-
 namespace Discord
 {
     /// <summary>
-    ///     Properties that are used to modify an <see cref="ITextChannel"/> with the specified changes.
+    ///     Provides properties that are used to modify an <see cref="ITextChannel"/> with the specified changes.
     /// </summary>
-    /// <seealso cref="ITextChannel.ModifyAsync(Action{TextChannelProperties}, RequestOptions)"/>
+    /// <seealso cref="ITextChannel.ModifyAsync(System.Action{TextChannelProperties}, RequestOptions)"/>
     public class TextChannelProperties : GuildChannelProperties
     {
         /// <summary>

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

@@ -1,7 +1,7 @@
 namespace Discord
 {
     /// <summary>
-    ///     Properties that are used to modify an <see cref="IVoiceChannel" /> with the specified changes.
+    ///     Provides properties that are used to modify an <see cref="IVoiceChannel" /> with the specified changes.
     /// </summary>
     public class VoiceChannelProperties : GuildChannelProperties
     {

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

@@ -12,10 +12,13 @@ namespace Discord
         /// <summary>
         ///     Gets the Unicode representation of this emote.
         /// </summary>
+        /// <returns>
+        ///     A string that resolves to <see cref="Emoji.Name"/>.
+        /// </returns>
         public override string ToString() => Name;
 
         /// <summary>
-        ///     Creates a Unicode emoji.
+        ///     Initializes a new <see cref="Emoji"/> class with the provided Unicode.
         /// </summary>
         /// <param name="unicode">The pure UTF-8 encoding of an emoji.</param>
         public Emoji(string unicode)

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

@@ -17,14 +17,18 @@ namespace Discord
         /// <summary>
         ///     Gets whether this emote is animated.
         /// </summary>
+        /// <returns>
+        ///     A boolean that determines whether or not this emote is an animated one.
+        /// </returns>
         public bool Animated { get; }
-        /// <summary>
-        ///     Gets the date when this emote is created.
-        /// </summary>
+        /// <inheritdoc />
         public DateTimeOffset CreatedAt => SnowflakeUtils.FromSnowflake(Id);
         /// <summary>
         ///     Gets the image URL of this emote.
         /// </summary>
+        /// <returns>
+        ///     A string that points to the URL of this emote.
+        /// </returns>
         public string Url => CDN.GetEmojiUrl(Id, Animated);
 
         internal Emote(ulong id, string name, bool animated)
@@ -59,7 +63,7 @@ namespace Discord
         }
 
         /// <summary> Parses an <see cref="Emote"/> from its raw format. </summary>
-        /// <param name="text">The raw encoding of an emote; for example, &lt;:dab:277855270321782784&gt;.</param>
+        /// <param name="text">The raw encoding of an emote (e.g. <c>&lt;:dab:277855270321782784&gt;</c>).</param>
         /// <returns>An emote.</returns>
         /// <exception cref="ArgumentException">Invalid emote format.</exception>
         public static Emote Parse(string text)
@@ -99,6 +103,9 @@ namespace Discord
         /// <summary>
         ///     Returns 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/Emotes/EmoteProperties.cs

@@ -3,7 +3,7 @@ using System.Collections.Generic;
 namespace Discord
 {
     /// <summary>
-    ///     Properties that are used to modify an <see cref="Emote" /> with the specified changes.
+    ///     Provides properties that are used to modify an <see cref="Emote" /> with the specified changes.
     /// </summary>
     /// <seealso cref="IGuild.ModifyEmoteAsync"/>
     public class EmoteProperties

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

@@ -10,16 +10,25 @@ namespace Discord
     public class GuildEmote : Emote
     {
         /// <summary>
-        ///     Gets whether this emoji is managed.
+        ///     Gets whether this emoji is managed by an integration.
         /// </summary>
+        /// <returns>
+        ///     A boolean that determines whether or not this emote is managed by a Twitch integration.
+        /// </returns>
         public bool IsManaged { get; }
         /// <summary>
         ///     Gets whether this emoji must be wrapped in colons.
         /// </summary>
+        /// <returns>
+        ///     A boolean that determines whether or not this emote requires the use of colons in chat to be used.
+        /// </returns>
         public bool RequireColons { get; }
         /// <summary>
-        ///     Gets the roles this emoji is whitelisted to.
+        ///     Gets the roles that are allowed to use this emoji.
         /// </summary>
+        /// <returns>
+        ///     A read-only list containing snowflake identifiers for roles that are allowed to use this emoji.
+        /// </returns>
         public IReadOnlyList<ulong> RoleIds { get; }
 
         internal GuildEmote(ulong id, string name, bool animated, bool isManaged, bool requireColons, IReadOnlyList<ulong> roleIds) : base(id, name, animated)

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

@@ -8,6 +8,9 @@ namespace Discord
         /// <summary>
         ///     Gets the display name or Unicode representation of this emote.
         /// </summary>
+        /// <returns>
+        ///     A string representing the display name or the Unicode representation (e.g. <c>🤔</c>) of this emote.
+        /// </returns>
         string Name { get; }
     }
 }

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

@@ -1,7 +1,7 @@
 namespace Discord
 {
     /// <summary>
-    ///     Properties that are used to modify the widget of an <see cref="IGuild" /> with the specified changes.
+    ///     Provides properties that are used to modify the widget of an <see cref="IGuild" /> with the specified changes.
     /// </summary>
     public class GuildEmbedProperties
     {

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

@@ -1,7 +1,7 @@
 namespace Discord
 {
     /// <summary>
-    ///     Properties used to modify an <see cref="IGuildIntegration" /> with the specified changes.
+    ///     Provides properties used to modify an <see cref="IGuildIntegration" /> with the specified changes.
     /// </summary>
     public class GuildIntegrationProperties
     {

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

@@ -1,7 +1,7 @@
 namespace Discord
 {
     /// <summary>
-    ///     Properties that are used to modify an <see cref="IGuild" /> with the specified changes.
+    ///     Provides properties that are used to modify an <see cref="IGuild" /> with the specified changes.
     /// </summary>
     /// <see cref="IGuild.ModifyAsync"/>
     public class GuildProperties

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

@@ -22,7 +22,7 @@ namespace Discord
         ///     automatically moved to the AFK voice channel.
         /// </summary>
         /// <returns>
-        ///     An <see cref="Int32"/> representing the amount of time in seconds for a user to be marked as inactive
+        ///     An <see cref="int"/> representing the amount of time in seconds for a user to be marked as inactive
         ///     and moved into the AFK voice channel.
         /// </returns>
         int AFKTimeout { get; }
@@ -98,63 +98,88 @@ namespace Discord
         ///     Gets the ID of the AFK voice channel for this guild.
         /// </summary>
         /// <returns>
-        ///     An <see cref="UInt64" /> representing the snowflake identifier of the AFK voice channel; <c>null</c> if
+        ///     A <see cref="ulong"/> representing the snowflake identifier of the AFK voice channel; <c>null</c> if
         ///     none is set.
         /// </returns>
         ulong? AFKChannelId { get; }
         /// <summary>
-        ///     Gets the ID of the the default channel for this guild.
+        ///     Gets the ID of the default channel for this guild.
         /// </summary>
+        /// <remarks>
+        ///     This property retrieves the snowflake identifier of the first viewable text channel for this guild.
+        ///     <note type="warning">
+        ///         This channel does not guarantee the user can send message to it, as it only looks for the first viewable
+        ///         text channel.
+        ///     </note>
+        /// </remarks>
+        /// <returns>
+        ///     A <see cref="ulong"/> representing the snowflake identifier of the default text channel; <c>0</c> if
+        ///     none can be found.
+        /// </returns>
         ulong DefaultChannelId { get; }
         /// <summary>
-        ///     Gets the ID of the embed channel set in the widget settings of this guild, or <c>null</c> if none is set.
+        ///     Gets the ID of the widget embed channel of this guild.
         /// </summary>
+        /// <returns>
+        ///     A <see cref="ulong"/> representing the snowflake identifier of the embedded channel found within the
+        ///     widget settings of this guild; <c>null</c> if none is set.
+        /// </returns>
         ulong? EmbedChannelId { get; }
         /// <summary>
-        ///     Gets the ID of the channel where randomized welcome messages are sent, or <c>null</c> if none is set.
+        ///     Gets the ID of the channel where randomized welcome messages are sent.
         /// </summary>
+        /// <returns>
+        ///     A <see cref="ulong"/> representing the snowflake identifier of the system channel where randomized
+        ///     welcome messages are sent; <c>null</c> if none is set.
+        /// </returns>
         ulong? SystemChannelId { get; }
         /// <summary>
-        ///     Gets the ID of the user that created this guild.
+        ///     Gets the ID of the user that owns this guild.
         /// </summary>
+        /// <returns>
+        ///     A <see cref="ulong"/> representing the snowflake identifier of the user that owns this guild.
+        /// </returns>
         ulong OwnerId { get; }
         /// <summary>
         ///     Gets the ID of the region hosting this guild's voice channels.
         /// </summary>
+        /// <returns>
+        ///     A string containing the identifier for the voice region that this guild uses (e.g. <c>eu-central</c>).
+        /// </returns>
         string VoiceRegionId { get; }
         /// <summary>
-        ///     Gets the <see cref="IAudioClient" /> currently associated with this guild.
+        ///     Gets the <see cref="IAudioClient"/> currently associated with this guild.
         /// </summary>
         /// <returns>
-        ///     <see cref="IAudioClient" /> currently associated with this guild.
+        ///     An <see cref="IAudioClient"/> currently associated with this guild.
         /// </returns>
         IAudioClient AudioClient { get; }
         /// <summary>
         ///     Gets the built-in role containing all users in this guild.
         /// </summary>
         /// <returns>
-        ///     Built-in role that represents an @everyone role in this guild.
+        ///     A role object that represents an <c>@everyone</c> role in this guild.
         /// </returns>
         IRole EveryoneRole { get; }
         /// <summary>
         ///     Gets a collection of all custom emotes for this guild.
         /// </summary>
         /// <returns>
-        ///     A collection of all custom emotes for this guild.
+        ///     A read-only collection of all custom emotes for this guild.
         /// </returns>
         IReadOnlyCollection<GuildEmote> Emotes { get; }
         /// <summary>
         ///     Gets a collection of all extra features added to this guild.
         /// </summary>
         /// <returns>
-        ///     A collection of enabled features in this guild.
+        ///     A read-only collection of enabled features in this guild.
         /// </returns>
         IReadOnlyCollection<string> Features { get; }
         /// <summary>
         ///     Gets a collection of all roles in this guild.
         /// </summary>
         /// <returns>
-        ///     A collection of roles found within this guild.
+        ///     A read-only collection of roles found within this guild.
         /// </returns>
         IReadOnlyCollection<IRole> Roles { get; }
 
@@ -164,7 +189,7 @@ namespace Discord
         /// <param name="func">The delegate containing the properties to modify the guild 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<GuildProperties> func, RequestOptions options = null);
         /// <summary>
@@ -173,7 +198,7 @@ namespace Discord
         /// <param name="func">The delegate containing the properties to modify the guild widget 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 ModifyEmbedAsync(Action<GuildEmbedProperties> func, RequestOptions options = null);
         /// <summary>
@@ -182,7 +207,7 @@ namespace Discord
         /// <param name="args">The properties used to modify the channel positions 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 reorder operation.
         /// </returns>
         Task ReorderChannelsAsync(IEnumerable<ReorderChannelProperties> args, RequestOptions options = null);
         /// <summary>
@@ -191,28 +216,32 @@ namespace Discord
         /// <param name="args">The properties used to modify the role positions 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 reorder operation.
         /// </returns>
         Task ReorderRolesAsync(IEnumerable<ReorderRoleProperties> args, RequestOptions options = null);
         /// <summary>
         ///     Leaves this guild.
         /// </summary>
         /// <remarks>
-        ///     This method will make the currently logged-in user leave the guild. If the user is the owner, use 
-        ///     <see cref="IDeletable.DeleteAsync" /> instead.
+        ///     This method will make the currently logged-in user leave the guild.
+        ///     <note>
+        ///         If the user is the owner of this guild, use <see cref="IDeletable.DeleteAsync"/> instead.
+        ///     </note>
         /// </remarks>
         /// <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 leave operation.
         /// </returns>
         Task LeaveAsync(RequestOptions options = null);
 
         /// <summary>
-        ///     Gets a collection of all users banned on this guild.
+        ///     Gets a collection of all users banned in 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 banned users with reasons.
+        ///     A task that represents the asynchronous get operation. The task result contains a read-only collection of
+        ///     ban objects that this guild currently possesses, with each object containing the user banned and reason
+        ///     behind the ban.
         /// </returns>
         Task<IReadOnlyCollection<IBan>> GetBansAsync(RequestOptions options = null);
         /// <summary>
@@ -221,8 +250,8 @@ namespace Discord
         /// <param name="user">The banned user.</param>
         /// <param name="options">The options to be used when sending the request.</param>
         /// <returns>
-        ///     An awaitable <see cref="Task"/> containing the ban object, which contains the user information and the
-        ///     reason for the ban; <c>null</c> if the ban entry cannot be found.
+        ///     A task that represents the asynchronous get operation. The task result contains a ban object, which
+        ///     contains the user information and the reason for the ban; <c>null</c> if the ban entry cannot be found.
         /// </returns>
         Task<IBan> GetBanAsync(IUser user, RequestOptions options = null);
         /// <summary>
@@ -231,216 +260,197 @@ namespace Discord
         /// <param name="userId">The snowflake identifier for the banned user.</param>
         /// <param name="options">The options to be used when sending the request.</param>
         /// <returns>
-        ///     An awaitable <see cref="Task"/> containing the ban object, which contains the user information and the
-        ///     reason for the ban; <c>null</c> if the ban entry cannot be found.
+        ///     A task that represents the asynchronous get operation. The task result contains a ban object, which
+        ///     contains the user information and the reason for the ban; <c>null</c> if the ban entry cannot be found.
         /// </returns>
         Task<IBan> GetBanAsync(ulong userId, RequestOptions options = null);
         /// <summary>
         ///     Bans the user from this 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 <paramref name="user" /> for - must be between [0, 7].
-        /// </param>
+        /// <param name="pruneDays">The number of days to remove messages from this user for, and this number 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>
+        /// <exception cref="ArgumentException"><paramref name="pruneDays"/> is not between 0 to 7.</exception>
         /// <returns>
-        ///     An awaitable <see cref="Task"/>.
+        ///     A task that represents the asynchronous add operation for the ban.
         /// </returns>
         Task AddBanAsync(IUser user, int pruneDays = 0, string reason = null, RequestOptions options = null);
         /// <summary>
         ///     Bans the user from this guild and optionally prunes their recent messages.
         /// </summary>
         /// <param name="userId">The snowflake ID of 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 user for, and this number 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>
+        /// <exception cref="ArgumentException"><paramref name="pruneDays"/> is not between 0 to 7.</exception>
         /// <returns>
-        ///     An awaitable <see cref="Task"/>.
+        ///     A task that represents the asynchronous add operation for the ban.
         /// </returns>
         Task AddBanAsync(ulong userId, int pruneDays = 0, string reason = null, RequestOptions options = null);
         /// <summary>
-        ///     Unbans the provided user if they are currently banned.
+        ///     Unbans the user if they are currently banned.
         /// </summary>
         /// <param name="user">The user to be unbanned.</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 removal operation for the ban.
         /// </returns>
         Task RemoveBanAsync(IUser user, RequestOptions options = null);
         /// <summary>
-        ///     Unbans the provided user ID if it is currently banned.
+        ///     Unbans the user if they are currently banned.
         /// </summary>
-        /// <param name="userId">The snowflake ID of the user to be unbanned.</param>
+        /// <param name="userId">The snowflake identifier of the user to be unbanned.</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 removal operation for the ban.
         /// </returns>
         Task RemoveBanAsync(ulong userId, RequestOptions options = null);
 
         /// <summary>
         ///     Gets a collection of all channels in this guild.
         /// </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>
-        ///     An awaitable <see cref="Task"/> containing a collection of generic channels found within this guild.
+        ///     A task that represents the asynchronous get operation. The task result contains a read-only collection of
+        ///     generic channels found within this guild.
         /// </returns>
         Task<IReadOnlyCollection<IGuildChannel>> GetChannelsAsync(CacheMode mode = CacheMode.AllowDownload, RequestOptions options = null);
         /// <summary>
-        ///     Gets the channel in this guild with the provided ID.
+        ///     Gets a channel in this guild.
         /// </summary>
-        /// <param name="id">The channel ID.</param>
-        /// <param name="mode">
-        /// The <see cref="CacheMode" /> that determines whether the object should be fetched from cache.
-        /// </param>
+        /// <param name="id">The snowflake identifier for the channel.</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 generic channel with the specified ID, or 
-        ///     <c>null</c> if none is found.
+        ///     A task that represents the asynchronous get operation. The task result contains the generic channel
+        ///     associated with the specified <paramref name="id"/>; <c>null</c> if none is found.
         /// </returns>
         Task<IGuildChannel> GetChannelAsync(ulong id, CacheMode mode = CacheMode.AllowDownload, RequestOptions options = null);
         /// <summary>
         ///     Gets a collection of all text channels in this guild.
         /// </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>
-        ///     An awaitable <see cref="Task"/> containing a collection of text channels found within this guild.
+        ///     A task that represents the asynchronous get operation. The task result contains a read-only collection of
+        ///     message channels found within this guild.
         /// </returns>
         Task<IReadOnlyCollection<ITextChannel>> GetTextChannelsAsync(CacheMode mode = CacheMode.AllowDownload, RequestOptions options = null);
         /// <summary>
-        ///     Gets a text channel in this guild with the provided ID, or <c>null</c> if not found.
+        ///     Gets a text channel in this guild.
         /// </summary>
-        /// <param name="id">The text channel ID.</param>
-        /// <param name="mode">
-        /// The <see cref="CacheMode" /> that determines whether the object should be fetched from cache.
-        /// </param>
+        /// <param name="id">The snowflake identifier for the text channel.</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 text channel with the specified ID, or 
-        ///     <c>null</c> if none is found.
+        ///     A task that represents the asynchronous get operation. The task result contains the text channel
+        ///     associated with the specified <paramref name="id"/>; <c>null</c> if none is found.
         /// </returns>
         Task<ITextChannel> GetTextChannelAsync(ulong id, CacheMode mode = CacheMode.AllowDownload, RequestOptions options = null);
         /// <summary>
         ///     Gets a collection of all voice channels in this guild.
         /// </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>
-        ///     An awaitable <see cref="Task"/> containing a collection of voice channels found within this guild.
+        ///     A task that represents the asynchronous get operation. The task result contains a read-only collection of
+        ///     voice channels found within this guild.
         /// </returns>
         Task<IReadOnlyCollection<IVoiceChannel>> GetVoiceChannelsAsync(CacheMode mode = CacheMode.AllowDownload, RequestOptions options = null);
         /// <summary>
         ///     Gets a collection of all category channels in this guild.
         /// </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>
-        ///     An awaitable <see cref="Task"/> containing a collection of category channels found within this guild.
+        ///     A task that represents the asynchronous get operation. The task result contains a read-only collection of
+        ///     category channels found within this guild.
         /// </returns>
         Task<IReadOnlyCollection<ICategoryChannel>> GetCategoriesAsync(CacheMode mode = CacheMode.AllowDownload, RequestOptions options = null);
         /// <summary>
-        ///     Gets the voice channel in this guild with the provided ID.
+        ///     Gets a voice channel in this guild.
         /// </summary>
-        /// <param name="id">The text channel ID.</param>
-        /// <param name="mode">
-        /// The <see cref="CacheMode" /> that determines whether the object should be fetched from cache.
-        /// </param>
+        /// <param name="id">The snowflake identifier for the voice channel.</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 voice channel with the specified ID, or 
-        ///     <c>null</c> if none is found.
+        ///     A task that represents the asynchronous get operation. The task result contains the voice channel associated
+        ///     with the specified <paramref name="id"/>; <c>null</c> if none is found.
         /// </returns>
         Task<IVoiceChannel> GetVoiceChannelAsync(ulong id, CacheMode mode = CacheMode.AllowDownload, RequestOptions options = null);
         /// <summary>
         ///     Gets the AFK voice channel in this guild.
         /// </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>
-        ///     An awaitable <see cref="Task"/> containing the AFK voice channel set within this guild, or 
-        ///     <c>null</c> if none is set.
+        ///     A task that represents the asynchronous get operation. The task result contains the voice channel that the
+        ///     AFK users will be moved to after they have idled for too long; <c>null</c> if none is set.
         /// </returns>
         Task<IVoiceChannel> GetAFKChannelAsync(CacheMode mode = CacheMode.AllowDownload, RequestOptions options = null);
         /// <summary>
-        ///     Gets the default system text channel in this guild with the provided ID.
+        ///     Gets the system channel where randomized welcome messages are sent in this guild.
         /// </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>
-        ///     An awaitable <see cref="Task"/> containing the system channel within this guild, or 
-        ///     <c>null</c> if none is set.
+        ///     A task that represents the asynchronous get operation. The task result contains the text channel where
+        ///     randomized welcome messages will be sent to; <c>null</c> if none is set.
         /// </returns>
         Task<ITextChannel> GetSystemChannelAsync(CacheMode mode = CacheMode.AllowDownload, RequestOptions options = null);
         /// <summary>
-        ///     Gets the top viewable text channel in this guild with the provided ID.
+        ///     Gets the first viewable text channel in this guild.
         /// </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>
-        ///     An awaitable <see cref="Task"/> containing the first viewable text channel in this guild, or 
-        ///     <c>null</c> if none is found.
+        ///     A task that represents the asynchronous get operation. The task result contains the first viewable text
+        ///     channel in this guild; <c>null</c> if none is found.
         /// </returns>
         Task<ITextChannel> GetDefaultChannelAsync(CacheMode mode = CacheMode.AllowDownload, RequestOptions options = null);
         /// <summary>
         ///     Gets the embed channel (i.e. the channel set in the guild's widget settings) in this guild.
         /// </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>
-        ///     An awaitable <see cref="Task"/> containing the embed channel set within the server's widget settings, or
-        ///     <c>null</c> if none is set.
+        ///     A task that represents the asynchronous get operation. The task result contains the embed channel set
+        ///     within the server's widget settings; <c>null</c> if none is set.
         /// </returns>
         Task<IGuildChannel> GetEmbedChannelAsync(CacheMode mode = CacheMode.AllowDownload, RequestOptions options = null);
 
         /// <summary>
-        ///     Creates a new text channel.
+        ///     Creates a new text channel in this guild.
         /// </summary>
         /// <param name="name">The new name for the text channel.</param>
         /// <param name="func">The delegate containing the properties to be applied to the channel upon its creation.</param>
         /// <param name="options">The options to be used when sending the request.</param>
         /// <returns>
-        ///     An awaitable <see cref="Task"/> containing the newly created text channel.
+        ///     A task that represents the asynchronous creation operation. The task result contains the newly created
+        ///     text channel.
         /// </returns>
         Task<ITextChannel> CreateTextChannelAsync(string name, Action<TextChannelProperties> func = null, RequestOptions options = null);
         /// <summary>
-        ///     Creates a new voice channel.
+        ///     Creates a new voice channel in this guild.
         /// </summary>
         /// <param name="name">The new name for the voice channel.</param>
         /// <param name="func">The delegate containing the properties to be applied to the channel upon its creation.</param>
         /// <param name="options">The options to be used when sending the request.</param>
         /// <returns>
-        ///     An awaitable <see cref="Task"/> containing the newly created voice channel.
+        ///     A task that represents the asynchronous creation operation. The task result contains the newly created
+        ///     voice channel.
         /// </returns>
         Task<IVoiceChannel> CreateVoiceChannelAsync(string name, Action<VoiceChannelProperties> func = null, RequestOptions options = null);
         /// <summary>
-        ///     Creates a new channel category.
+        ///     Creates a new channel category in this guild.
         /// </summary>
         /// <param name="name">The new name for the category.</param>
         /// <param name="options">The options to be used when sending the request.</param>
         /// <returns>
-        ///     An awaitable <see cref="Task"/> containing the newly created category channel.
+        ///     A task that represents the asynchronous creation operation. The task result contains the newly created
+        ///     category channel.
         /// </returns>
         Task<ICategoryChannel> CreateCategoryAsync(string name, RequestOptions options = null);
 
@@ -448,11 +458,12 @@ namespace Discord
         Task<IGuildIntegration> CreateIntegrationAsync(ulong id, string type, RequestOptions options = null);
 
         /// <summary>
-        ///     Gets a collection of all invites to this guild.
+        ///     Gets a collection of all invites in 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 invites found within this guild.
+        ///     A task that represents the asynchronous get operation. The task result contains a read-only collection of
+        ///     invite metadata, each representing information for an invite found within this guild.
         /// </returns>
         Task<IReadOnlyCollection<IInviteMetadata>> GetInvitesAsync(RequestOptions options = null);
         /// <summary>
@@ -460,17 +471,17 @@ namespace Discord
         /// </summary>
         /// <param name="options">The options to be used when sending the request.</param>
         /// <returns>
-        ///     An awaitable <see cref="Task"/> containing the partial metadata of the vanity invite found within
-        ///     this guild.
+        ///     A task that represents the asynchronous get operation. The task result contains the partial metadata of
+        ///     the vanity invite found within this guild; <c>null</c> if none is found.
         /// </returns>
         Task<IInviteMetadata> GetVanityInviteAsync(RequestOptions options = null);
 
         /// <summary>
         ///     Gets a role in this guild.
         /// </summary>
-        /// <param name="id">The role ID.</param>
+        /// <param name="id">The snowflake identifier for the role.</param>
         /// <returns>
-        ///     A role that matches the provided snowflake identifier; <c>null</c> if none is found.
+        ///     A role that is associated with the specified <paramref name="id"/>; <c>null</c> if none is found.
         /// </returns>
         IRole GetRole(ulong id);
         /// <summary>
@@ -482,7 +493,8 @@ namespace Discord
         /// <param name="isHoisted">Whether the role is separated from others on the sidebar.</param>
         /// <param name="options">The options to be used when sending the request.</param>
         /// <returns>
-        ///     An awaitable <see cref="Task"/> containing the newly crated role.
+        ///     A task that represents the asynchronous creation operation. The task result contains the newly created
+        ///     role.
         /// </returns>
         Task<IRole> CreateRoleAsync(string name, GuildPermissions? permissions = null, Color? color = null, bool isHoisted = false, RequestOptions options = null);
 
@@ -492,27 +504,33 @@ namespace Discord
         /// <remarks>
         ///     This method retrieves all users found within this guild.
         ///     <note>
-        ///         This may return an incomplete list on the WebSocket implementation.
+        ///         This may return an incomplete collection in the WebSocket implementation due to how Discord does not
+        ///         send a complete user list for large guilds.
         ///     </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 users found within this guild.
+        ///     A task that represents the asynchronous get operation. The task result contains a collection of guild
+        ///     users found within this guild.
         /// </returns>
         Task<IReadOnlyCollection<IGuildUser>> GetUsersAsync(CacheMode mode = CacheMode.AllowDownload, RequestOptions options = null);
         /// <summary>
-        ///     Gets a user found in this guild.
+        ///     Gets a user from this guild.
         /// </summary>
-        /// <param name="id">The user ID to search for.</param>
-        /// <param name="mode">The <see cref="CacheMode"/> that determines whether the object should be fetched from
-        /// cache.</param>
+        /// <remarks>
+        ///     This method retrieves a user found within this guild.
+        ///     <note>
+        ///         This may return <c>null</c> in the WebSocket implementation due to incomplete user collection in
+        ///         large guilds.
+        ///     </note>
+        /// </remarks>
+        /// <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>
-        ///     An awaitable <see cref="Task"/> containing the guild user with the specified ID; <c>null</c> if none is
-        ///     found.
+        ///     A task that represents the asynchronous get operation. The task result contains the guild user
+        ///     associated with the specified <paramref name="id"/>; <c>null</c> if none is found.
         /// </returns>
         Task<IGuildUser> GetUserAsync(ulong id, CacheMode mode = CacheMode.AllowDownload, RequestOptions options = null);
         /// <summary>
@@ -521,7 +539,8 @@ 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>
-        ///     An awaitable <see cref="Task"/> containing the currently logged-in user within this guild.
+        ///     A task that represents the asynchronous get operation. The task result contains the currently logged-in
+        ///     user within this guild.
         /// </returns>
         Task<IGuildUser> GetCurrentUserAsync(CacheMode mode = CacheMode.AllowDownload, RequestOptions options = null);
         /// <summary>
@@ -530,29 +549,34 @@ 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>
-        ///     An awaitable <see cref="Task"/> containing the owner of this guild.
+        ///     A task that represents the asynchronous get operation. The task result contains the owner of this guild.
         /// </returns>
         Task<IGuildUser> GetOwnerAsync(CacheMode mode = CacheMode.AllowDownload, RequestOptions options = null);
         /// <summary>
         ///     Downloads all users for this guild if the current list is incomplete.
         /// </summary>
         /// <returns>
-        ///     An awaitable <see cref="Task"/>.
+        ///     A task that represents the asynchronous download operation.
         /// </returns>
         Task DownloadUsersAsync();
         /// <summary>
         ///     Prunes inactive users.
         /// </summary>
         /// <remarks>
-        ///     This method removes all users that have not logged on in the provided number of days or, if 
-        ///     <paramref name="simulate"/> is <c>true</c>, returns the number of users that would be removed.
+        ///     <para>
+        ///         This method removes all users that have not logged on in the provided number of <paramref name="days"/>.
+        ///     </para>
+        ///     <para>
+        ///         If <paramref name="simulate" /> is <c>true</c>, this method will only return the number of users that
+        ///         would be removed without kicking the users.
+        ///     </para>
         /// </remarks>
         /// <param name="days">The number of days required for the users to be kicked.</param>
         /// <param name="simulate">Whether this prune action is a simulation.</param>
         /// <param name="options">The options to be used when sending the request.</param>
         /// <returns>
-        ///     An awaitable <see cref="Task" /> containing the number of users to be or has been removed from this
-        ///     guild.
+        ///     A task that represents the asynchronous prune operation. The task result contains the number of users to
+        ///     be or has been removed from this guild.
         /// </returns>
         Task<int> PruneUsersAsync(int days = 30, bool simulate = false, RequestOptions options = null);
 
@@ -560,12 +584,11 @@ namespace Discord
         ///     Gets the specified number of audit log entries for this guild.
         /// </summary>
         /// <param name="limit">The number of audit log entries to fetch.</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 a collection of requested audit log entries.
+        ///     A task that represents the asynchronous get operation. The task result contains a read-only collection
+        ///     of the requested audit log entries.
         /// </returns>
         Task<IReadOnlyCollection<IAuditLogEntry>> GetAuditLogAsync(int limit = DiscordConfig.MaxAuditLogEntriesPerBatch,
             CacheMode mode = CacheMode.AllowDownload, RequestOptions options = null);
@@ -573,11 +596,11 @@ namespace Discord
         /// <summary>
         ///     Gets a webhook found within this guild.
         /// </summary>
-        /// <param name="id">The webhook ID.</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 with the specified ID; <c>null</c> if none is
-        ///     found.
+        ///     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>
         Task<IWebhook> GetWebhookAsync(ulong id, RequestOptions options = null);
         /// <summary>
@@ -585,18 +608,19 @@ namespace Discord
         /// </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 found within the guild.
+        ///     A task that represents the asynchronous get operation. The task result contains a read-only collection
+        ///     of webhooks found within the guild.
         /// </returns>
         Task<IReadOnlyCollection<IWebhook>> GetWebhooksAsync(RequestOptions options = null);
 
         /// <summary>
         ///     Gets a specific emote from this guild.
         /// </summary>
-        /// <param name="id">The guild emote ID.</param>
+        /// <param name="id">The snowflake identifier for the guild emote.</param>
         /// <param name="options">The options to be used when sending the request.</param>
         /// <returns>
-        ///     An awaitable <see cref="Task"/> containing the emote found with the specified ID; <c>null</c> if none is
-        ///     found.
+        ///     A task that represents the asynchronous get operation. The task result contains the emote found with the
+        ///     specified <paramref name="id"/>; <c>null</c> if none is found.
         /// </returns>
         Task<GuildEmote> GetEmoteAsync(ulong id, RequestOptions options = null);
         /// <summary>
@@ -607,7 +631,7 @@ namespace Discord
         /// <param name="roles">The roles to limit the emote usage to.</param>
         /// <param name="options">The options to be used when sending the request.</param>
         /// <returns>
-        ///     An awaitable <see cref="Task"/> containing the created emote.
+        ///     A task that represents the asynchronous creation operation. The task result contains the created emote.
         /// </returns>
         Task<GuildEmote> CreateEmoteAsync(string name, Image image, Optional<IEnumerable<IRole>> roles = default(Optional<IEnumerable<IRole>>), RequestOptions options = null);
 
@@ -618,7 +642,8 @@ namespace Discord
         /// <param name="func">The delegate containing the properties to modify the emote with.</param>
         /// <param name="options">The options to be used when sending the request.</param>
         /// <returns>
-        ///     An awaitable <see cref="Task"/> containing the newly modified emote.
+        ///     A task that represents the asynchronous modification operation. The task result contains the modified
+        ///     emote.
         /// </returns>
         Task<GuildEmote> ModifyEmoteAsync(GuildEmote emote, Action<EmoteProperties> func, RequestOptions options = null);
         /// <summary>
@@ -627,7 +652,7 @@ namespace Discord
         /// <param name="emote">The emote to delete.</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 removal operation.
         /// </returns>
         Task DeleteEmoteAsync(GuildEmote emote, RequestOptions options = null);
     }

src/Discord.Net.Core/Entities/Permissions/GuildPermissions.cs

@@ -148,7 +148,7 @@ namespace Discord
             RawValue = value;
         }
 
-        /// <summary> Creates a new <see cref="GuildPermissions"/> with the provided permissions. </summary>
+        /// <summary> Creates a new <see cref="GuildPermissions"/> structure with the provided permissions. </summary>
         public GuildPermissions(
             bool createInstantInvite = false,
             bool kickMembers = false,

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

@@ -18,61 +18,60 @@ namespace Discord
         /// <returns> A color class with the hex value of <see href="http://www.color-hex.com/color/1ABC9C">1ABC9C</see>.</returns>
         public static readonly Color Teal = new Color(0x1ABC9C);
         /// <summary> Gets the dark teal color value. </summary>
-        /// <returns> A color class with the hex value of <see href="http://www.color-hex.com/color/11806A">11806A</see>.</returns>
         public static readonly Color DarkTeal = new Color(0x11806A);
         /// <summary> Gets the green color value. </summary>
-        /// <returns> A color class with the hex value of <see href="http://www.color-hex.com/color/2ECC71">2ECC71</see>.</returns>
+        /// <returns> A color class with the hex value of <see href="http://www.color-hex.com/color/11806A">11806A</see>.</returns>
         public static readonly Color Green = new Color(0x2ECC71);
         /// <summary> Gets the dark green color value. </summary>
-        /// <returns> A color class with the hex value of <see href="http://www.color-hex.com/color/1F8B4C">1F8B4C</see>.</returns>
+        /// <returns> A color class with the hex value of <see href="http://www.color-hex.com/color/2ECC71">2ECC71</see>.</returns>
         public static readonly Color DarkGreen = new Color(0x1F8B4C);
         /// <summary> Gets the blue color value. </summary>
-        /// <returns> A color class with the hex value of <see href="http://www.color-hex.com/color/3498DB">3498DB</see>.</returns>
+        /// <returns> A color class with the hex value of <see href="http://www.color-hex.com/color/1F8B4C">1F8B4C</see>.</returns>
         public static readonly Color Blue = new Color(0x3498DB);
         /// <summary> Gets the dark blue color value. </summary>
-        /// <returns> A color class with the hex value of <see href="http://www.color-hex.com/color/206694">206694</see>.</returns>
+        /// <returns> A color class with the hex value of <see href="http://www.color-hex.com/color/3498DB">3498DB</see>.</returns>
         public static readonly Color DarkBlue = new Color(0x206694);
         /// <summary> Gets the purple color value. </summary>
-        /// <returns> A color class with the hex value of <see href="http://www.color-hex.com/color/9B59B6">9B59B6</see>.</returns>
+        /// <returns> A color class with the hex value of <see href="http://www.color-hex.com/color/206694">206694</see>.</returns>
         public static readonly Color Purple = new Color(0x9B59B6);
         /// <summary> Gets the dark purple color value. </summary>
-        /// <returns> A color class with the hex value of <see href="http://www.color-hex.com/color/71368A">71368A</see>.</returns>
+        /// <returns> A color class with the hex value of <see href="http://www.color-hex.com/color/9B59B6">9B59B6</see>.</returns>
         public static readonly Color DarkPurple = new Color(0x71368A);
         /// <summary> Gets the magenta color value. </summary>
-        /// <returns> A color class with the hex value of <see href="http://www.color-hex.com/color/E91E63">E91E63</see>.</returns>
+        /// <returns> A color class with the hex value of <see href="http://www.color-hex.com/color/71368A">71368A</see>.</returns>
         public static readonly Color Magenta = new Color(0xE91E63);
         /// <summary> Gets the dark magenta color value. </summary>
-        /// <returns> A color class with the hex value of <see href="http://www.color-hex.com/color/AD1457">AD1457</see>.</returns>
+        /// <returns> A color class with the hex value of <see href="http://www.color-hex.com/color/E91E63">E91E63</see>.</returns>
         public static readonly Color DarkMagenta = new Color(0xAD1457);
         /// <summary> Gets the gold color value. </summary>
-        /// <returns> A color class with the hex value of <see href="http://www.color-hex.com/color/F1C40F">F1C40F</see>.</returns>
+        /// <returns> A color class with the hex value of <see href="http://www.color-hex.com/color/AD1457">AD1457</see>.</returns>
         public static readonly Color Gold = new Color(0xF1C40F);
         /// <summary> Gets the light orange color value. </summary>
-        /// <returns> A color class with the hex value of <see href="http://www.color-hex.com/color/C27C0E">C27C0E</see>.</returns>
+        /// <returns> A color class with the hex value of <see href="http://www.color-hex.com/color/F1C40F">F1C40F</see>.</returns>
         public static readonly Color LightOrange = new Color(0xC27C0E);
         /// <summary> Gets the orange color value. </summary>
-        /// <returns> A color class with the hex value of <see href="http://www.color-hex.com/color/E67E22">E67E22</see>.</returns>
+        /// <returns> A color class with the hex value of <see href="http://www.color-hex.com/color/C27C0E">C27C0E</see>.</returns>
         public static readonly Color Orange = new Color(0xE67E22);
         /// <summary> Gets the dark orange color value. </summary>
-        /// <returns> A color class with the hex value of <see href="http://www.color-hex.com/color/A84300">A84300</see>.</returns>
+        /// <returns> A color class with the hex value of <see href="http://www.color-hex.com/color/E67E22">E67E22</see>.</returns>
         public static readonly Color DarkOrange = new Color(0xA84300);
         /// <summary> Gets the red color value. </summary>
-        /// <returns> A color class with the hex value of <see href="http://www.color-hex.com/color/E74C3C">E74C3C</see>.</returns>
+        /// <returns> A color class with the hex value of <see href="http://www.color-hex.com/color/A84300">A84300</see>.</returns>
         public static readonly Color Red = new Color(0xE74C3C);
         /// <summary> Gets the dark red color value. </summary>
-        /// <returns> A color class with the hex value of <see href="http://www.color-hex.com/color/992D22">992D22</see>.</returns>
-        public static readonly Color DarkRed = new Color(0x992D22);
+        /// <returns> A color class with the hex value of <see href="http://www.color-hex.com/color/E74C3C">E74C3C</see>.</returns>
+        public static readonly Color DarkRed = new Color(0x992D22); 
         /// <summary> Gets the light grey color value. </summary>
-        /// <returns> A color class with the hex value of <see href="http://www.color-hex.com/color/979C9F">979C9F</see>.</returns>
+        /// <returns> A color class with the hex value of <see href="http://www.color-hex.com/color/992D22">992D22</see>.</returns>
         public static readonly Color LightGrey = new Color(0x979C9F);
         /// <summary> Gets the lighter grey color value. </summary>
-        /// <returns> A color class with the hex value of <see href="http://www.color-hex.com/color/95A5A6">95A5A6</see>.</returns>
+        /// <returns> A color class with the hex value of <see href="http://www.color-hex.com/color/979C9F">979C9F</see>.</returns>
         public static readonly Color LighterGrey = new Color(0x95A5A6);
         /// <summary> Gets the dark grey color value. </summary>
-        /// <returns> A color class with the hex value of <see href="http://www.color-hex.com/color/607D8B">607D8B</see>.</returns>
+        /// <returns> A color class with the hex value of <see href="http://www.color-hex.com/color/95A5A6">95A5A6</see>.</returns>
         public static readonly Color DarkGrey = new Color(0x607D8B);
         /// <summary> Gets the darker grey color value. </summary>
-        /// <returns> A color class with the hex value of <see href="http://www.color-hex.com/color/546E7A">546E7A</see>.</returns>
+        /// <returns> A color class with the hex value of <see href="http://www.color-hex.com/color/607D8B">607D8B</see>.</returns>
         public static readonly Color DarkerGrey = new Color(0x546E7A);
 
         /// <summary> Gets the encoded value for this color. </summary>

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

@@ -16,7 +16,7 @@ namespace Discord
         ///     Gets the new zero-based position of the role.
         /// </summary>
         /// <returns>
-        ///     A <see cref="int"/> representing the new zero-based position of the role.
+        ///     An <see cref="int"/> representing the new zero-based position of the role.
         /// </returns>
         public int Position { get; }
 

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

@@ -10,36 +10,60 @@ namespace Discord
     public interface IGuildUser : IUser, IVoiceState
     {
         /// <summary>
-        ///     Gets when this user joined this guild.
+        ///     Gets when this user joined the guild.
         /// </summary>
+        /// <returns>
+        ///     A <see cref="DateTimeOffset"/> representing the time of which the user has joined the guild; 
+        ///     <c>null</c> when it cannot be obtained.
+        /// </returns>
         DateTimeOffset? JoinedAt { get; }
         /// <summary>
         ///     Gets the nickname for this user.
         /// </summary>
+        /// <returns>
+        ///     A string representing the nickname of the user; <c>null</c> if none is set.
+        /// </returns>
         string Nickname { get; }
         /// <summary>
         ///     Gets the guild-level permissions for this user.
         /// </summary>
+        /// <returns>
+        ///     A <see cref="Discord.GuildPermissions"/> structure for this user, representing what
+        ///     permissions this user has in the guild.
+        /// </returns>
         GuildPermissions GuildPermissions { get; }
 
         /// <summary>
         ///     Gets the guild for this user.
         /// </summary>
+        /// <returns>
+        ///     A guild object that this user belongs to.
+        /// </returns>
         IGuild Guild { get; }
         /// <summary>
         ///     Gets the ID of the guild for this user.
         /// </summary>
+        /// <returns>
+        ///     An <see cref="ulong"/> representing the snowflake identifier of the guild that this user belongs to.
+        /// </returns>
         ulong GuildId { get; }
         /// <summary>
-        ///     Returns a collection of the ids of the roles this user is a member of in this guild, including the
-        ///     guild's @everyone role.
+        ///     Gets a collection of IDs for the roles that this user currently possesses in the guild.
         /// </summary>
+        /// <returns>
+        ///     A read-only collection of <see cref="ulong"/>, each representing a snowflake identifier for a role that
+        ///     this user posesses.
+        /// </returns>
         IReadOnlyCollection<ulong> RoleIds { get; }
 
         /// <summary>
         ///     Gets the level permissions granted to this user to a given channel.
         /// </summary>
         /// <param name="channel">The channel to get the permission from.</param>
+        /// <returns>
+        ///     A <see cref="Discord.ChannelPermissions"/> structure representing the permissions that a user has in the
+        ///     specified channel.
+        /// </returns>
         ChannelPermissions GetPermissions(IGuildChannel channel);
 
         /// <summary>
@@ -47,37 +71,56 @@ namespace Discord
         /// </summary>
         /// <param name="reason">The reason for the kick which will be recorded in the audit log.</param>
         /// <param name="options">The options to be used when sending the request.</param>
+        /// <returns>
+        ///     A task that represents the asynchronous kick operation.
+        /// </returns>
         Task KickAsync(string reason = null, RequestOptions options = null);
         /// <summary>
         ///     Modifies this user's properties in this guild.
         /// </summary>
-        /// <param name="func">The properties to modify the user with.</param>
+        /// <param name="func">The delegate containing the properties to modify the user with.</param>
         /// <param name="options">The options to be used when sending the request.</param>
+        /// <returns>
+        ///     A task that represents the asynchronous modification operation.
+        /// </returns>
+        /// <seealso cref="Discord.GuildUserProperties"/>
         Task ModifyAsync(Action<GuildUserProperties> func, RequestOptions options = null);
 
         /// <summary>
-        ///     Adds a <paramref name="role"/> to this user in this guild.
+        ///     Adds the specified <paramref name="role"/> to this user in this guild.
         /// </summary>
         /// <param name="role">The role to be added to the user.</param>
         /// <param name="options">The options to be used when sending the request.</param>
+        /// <returns>
+        ///     A task that represents the asynchronous role addition operation.
+        /// </returns>
         Task AddRoleAsync(IRole role, RequestOptions options = null);
         /// <summary>
-        ///     Adds <paramref name="roles"/> to this user in this guild.
+        ///     Adds the specified <paramref name="roles"/> to this user in this guild.
         /// </summary>
         /// <param name="roles">The roles to be added to the user.</param>
         /// <param name="options">The options to be used when sending the request.</param>
+        /// <returns>
+        ///     A task that represents the asynchronous role addition operation.
+        /// </returns>
         Task AddRolesAsync(IEnumerable<IRole> roles, RequestOptions options = null);
         /// <summary>
-        ///     Removes a <paramref name="role"/> from this user in this guild.
+        ///     Removes the specified <paramref name="role"/> from this user in this guild.
         /// </summary>
         /// <param name="role">The role to be removed from the user.</param>
         /// <param name="options">The options to be used when sending the request.</param>
+        /// <returns>
+        ///     A task that represents the asynchronous role removal operation.
+        /// </returns>
         Task RemoveRoleAsync(IRole role, RequestOptions options = null);
         /// <summary>
-        ///     Removes <paramref name="roles"/> from this user in this guild.
+        ///     Removes the specified <paramref name="roles"/> from this user in this guild.
         /// </summary>
         /// <param name="roles">The roles to be removed from the user.</param>
         /// <param name="options">The options to be used when sending the request.</param>
+        /// <returns>
+        ///     A task that represents the asynchronous role removal operation.
+        /// </returns>
         Task RemoveRolesAsync(IEnumerable<IRole> roles, RequestOptions options = null);
     }
 }

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

@@ -13,12 +13,18 @@ namespace Discord
         /// </summary>
         string Email { get; }
         /// <summary>
-        ///     Returns <c>true</c> if this user's email has been verified.
+        ///     Indicates whether or not this user has their email verified.
         /// </summary>
+        /// <returns>
+        ///     <c>true</c> if this user's email has been verified; <c>false</c> if not.
+        /// </returns>
         bool IsVerified { get; }
         /// <summary>
-        ///     Returns <c>true</c> if this user has enabled MFA on their account.
+        ///     Indicates whether or not this user has MFA enabled on their account.
         /// </summary>
+        /// <returns>
+        ///     <c>true</c> if this user has enabled multi-factor authentication on their account; <c>false</c> if not.
+        /// </returns>
         bool IsMfaEnabled { get; }
 
         /// <summary>

src/Discord.Net.Core/Net/RateLimitedException.cs

@@ -3,7 +3,7 @@ using System;
 namespace Discord.Net
 {
     /// <summary>
-    ///     Describes an exception that indicates the user is being rate limited by Discord.
+    ///     The exception that is thrown when the user is being rate limited by Discord.
     /// </summary>
     public class RateLimitedException : TimeoutException
     {

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

@@ -16,14 +16,13 @@ namespace Discord.Rest
     {
         /// <inheritdoc />
         public string Topic { get; private set; }
+        /// <inheritdoc />
         public ulong? CategoryId { get; private set; }
 
         /// <inheritdoc />
         public string Mention => MentionUtils.MentionChannel(Id);
-
-        private bool _nsfw;
         /// <inheritdoc />
-        public bool IsNsfw => _nsfw;
+        public bool IsNsfw { get; private set; }
 
         internal RestTextChannel(BaseDiscordClient discord, IGuild guild, ulong id)
             : base(discord, guild, id)
@@ -40,7 +39,7 @@ namespace Discord.Rest
             base.Update(model);
             CategoryId = model.CategoryId;
             Topic = model.Topic.Value;
-            _nsfw = model.Nsfw.GetValueOrDefault();
+            IsNsfw = model.Nsfw.GetValueOrDefault();
         }
 
         /// <inheritdoc />
@@ -239,6 +238,7 @@ namespace Discord.Rest
         }
 
         // INestedChannel
+        /// <inheritdoc />
         async Task<ICategoryChannel> INestedChannel.GetCategoryAsync(CacheMode mode, RequestOptions options)
         {
             if (CategoryId.HasValue && mode == CacheMode.AllowDownload)

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

@@ -18,6 +18,7 @@ namespace Discord.Rest
         public int Bitrate { get; private set; }
         /// <inheritdoc />
         public int? UserLimit { get; private set; }
+        /// <inheritdoc />
         public ulong? CategoryId { get; private set; }
 
         internal RestVoiceChannel(BaseDiscordClient discord, IGuild guild, ulong id)

src/Discord.Net.Rest/Entities/Messages/RestSystemMessage.cs

@@ -1,4 +1,4 @@
-using System.Diagnostics;
+using System.Diagnostics;
 using Model = Discord.API.Message;
 
 namespace Discord.Rest
@@ -6,6 +6,7 @@ namespace Discord.Rest
     [DebuggerDisplay(@"{DebuggerDisplay,nq}")]
     public class RestSystemMessage : RestMessage, ISystemMessage
     {
+        /// <inheritdoc />
         public MessageType Type { get; private set; }
 
         internal RestSystemMessage(BaseDiscordClient discord, ulong id, IMessageChannel channel, IUser author)

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

@@ -54,8 +54,14 @@ namespace Discord.WebSocket
         ///     Gets the number of members.
         /// </summary>
         /// <remarks>
-        ///     This property retrieves the number of members returned by Discord and is the most accurate. You may see
-        ///     discrepancy between the <see cref="Users"/> collection and this property.
+        ///     This property retrieves the number of members returned by Discord.
+        ///     <note type="tip">
+        ///         Due to how this property is returned by Discord instead of relying on the WebSocket cache, the
+        ///         number here is the most accurate in terms of counting the number of users within this guild. Use
+        ///         this instead of enumerating the count of the <see cref="Discord.WebSocket.SocketGuild.Users" />
+        ///         collection, as you may see discrepancy between the count of
+        ///         <see cref="Discord.WebSocket.SocketGuild.Users" />collection and this property.
+        ///     </note>
         /// </remarks>
         public int MemberCount { get; internal set; }
         /// <summary> Gets the number of members downloaded to the local guild cache. </summary>
@@ -95,12 +101,18 @@ namespace Discord.WebSocket
         /// </summary>
         public IAudioClient AudioClient => _audioClient;
         /// <summary>
-        ///     Gets the first viewable text channel.
+        ///     Gets the default channel in this guild.
         /// </summary>
         /// <remarks>
-        ///     This method gets the first viewable text channel for the logged-in user. This property does not
-        ///     guarantee the user can send message to it.
+        ///     This property retrieves the first viewable text channel for this guild.
+        ///     <note type="warning">
+        ///         This channel does not guarantee the user can send message to it, as it only looks for the first viewable
+        ///         text channel.
+        ///     </note>
         /// </remarks>
+        /// <returns>
+        ///     A <see cref="SocketTextChannel"/> representing the first viewable channel that the user has access to.
+        /// </returns>
         public SocketTextChannel DefaultChannel => TextChannels
             .Where(c => CurrentUser.GetPermissions(c).ViewChannel)
             .OrderBy(c => c.Position)
@@ -109,7 +121,8 @@ namespace Discord.WebSocket
         ///     Gets the AFK voice channel in this guild.
         /// </summary>
         /// <returns>
-        ///     A voice channel set within this guild that AFK users get moved to; otherwise <c>null</c> if none is set.
+        ///     A <see cref="SocketVoiceChannel" /> that the AFK users will be moved to after they have idled for too
+        ///     long; <c>null</c> if none is set.
         /// </returns>
         public SocketVoiceChannel AFKChannel
         {
@@ -120,10 +133,10 @@ namespace Discord.WebSocket
             }
         }
         /// <summary>
-        ///     Gets the embed channel set in the widget settings of this guild.
+        ///     Gets the embed channel (i.e. the channel set in the guild's widget settings) in this guild.
         /// </summary>
         /// <returns>
-        ///     A channel set in the widget settings of this guild; otherwise <c>null</c> if none is set.
+        ///     A channel set within the server's widget settings; <c>null</c> if none is set.
         /// </returns>
         public SocketGuildChannel EmbedChannel
         {
@@ -134,11 +147,10 @@ namespace Discord.WebSocket
             }
         }
         /// <summary>
-        ///     Gets the channel where randomized welcome messages are sent.
+        ///     Gets the system channel where randomized welcome messages are sent in this guild.
         /// </summary>
         /// <returns>
-        ///     A channel where randomized welcome messages are sent in this guild; otherwise <c>null</c> if none is
-        ///     set.
+        ///     A text channel where randomized welcome messages will be sent to; <c>null</c> if none is set.
         /// </returns>
         public SocketTextChannel SystemChannel
         {
@@ -149,21 +161,27 @@ namespace Discord.WebSocket
             }
         }
         /// <summary>
-        ///     Gets a collection of text channels present in this guild.
+        ///     Gets a collection of all text channels in this guild.
         /// </summary>
         /// <returns>
-        ///     A collection of text channels in this guild.
+        ///     A read-only collection of message channels found within this guild.
         /// </returns>
         public IReadOnlyCollection<SocketTextChannel> TextChannels
             => Channels.Select(x => x as SocketTextChannel).Where(x => x != null).ToImmutableArray();
         /// <summary>
-        ///     Gets a collection of voice channels present in this guild.
+        ///     Gets a collection of all voice channels in this guild.
         /// </summary>
+        /// <returns>
+        ///     A read-only collection of voice channels found within this guild.
+        /// </returns>
         public IReadOnlyCollection<SocketVoiceChannel> VoiceChannels
             => Channels.Select(x => x as SocketVoiceChannel).Where(x => x != null).ToImmutableArray();
         /// <summary>
-        ///     Gets a collection of category channels present in this guild.
+        ///     Gets a collection of all category channels in this guild.
         /// </summary>
+        /// <returns>
+        ///     A read-only collection of category channels found within this guild.
+        /// </returns>
         public IReadOnlyCollection<SocketCategoryChannel> CategoryChannels
             => Channels.Select(x => x as SocketCategoryChannel).Where(x => x != null).ToImmutableArray();
         /// <summary>
@@ -171,14 +189,17 @@ namespace Discord.WebSocket
         /// </summary>
         public SocketGuildUser CurrentUser => _members.TryGetValue(Discord.CurrentUser.Id, out SocketGuildUser member) ? member : null;
         /// <summary>
-        ///     Gets the @everyone role in this guild.
+        ///     Gets the built-in role containing all users in this guild.
         /// </summary>
+        /// <returns>
+        ///     A role object that represents an <c>@everyone</c> role in this guild.
+        /// </returns>
         public SocketRole EveryoneRole => GetRole(Id);
         /// <summary>
-        ///     Gets a collection of channels present in this guild.
+        ///     Gets a collection of all channels in this guild.
         /// </summary>
         /// <returns>
-        ///     Collection of channels.
+        ///     A read-only collection of generic channels found within this guild.
         /// </returns>
         public IReadOnlyCollection<SocketGuildChannel> Channels
         {
@@ -189,37 +210,31 @@ namespace Discord.WebSocket
                 return channels.Select(x => state.GetChannel(x) as SocketGuildChannel).Where(x => x != null).ToReadOnlyCollection(channels);
             }
         }
-        /// <summary>
-        ///     Gets a collection of emotes created in this guild.
-        /// </summary>
-        /// <returns>
-        ///     Collection of emotes.
-        /// </returns>
+        /// <inheritdoc />
         public IReadOnlyCollection<GuildEmote> Emotes => _emotes;
-        /// <summary>
-        ///     Gets a collection of features enabled in this guild.
-        /// </summary>
-        /// <returns>
-        ///     Collection of features in string.
-        /// </returns>
+        /// <inheritdoc />
         public IReadOnlyCollection<string> Features => _features;
         /// <summary>
         ///     Gets a collection of users in this guild.
         /// </summary>
         /// <remarks>
-        /// This property may not always return all the members for large guilds (i.e. guilds containing 100+ users).
-        /// You may need to enable <see cref="DiscordSocketConfig.AlwaysDownloadUsers"/> to fetch the full user list
-        /// upon startup, or use <see cref="DownloadUsersAsync"/> to manually download the users.
+        ///     This property retrieves all users found within this guild.
+        ///     <note type="warning">
+        ///         This property may not always return all the members for large guilds (i.e. guilds containing 100+ users).
+        ///         If you are simply looking to get the number of users present in this guild, consider <see cref="MemberCount"/> instead.
+        ///         Otherwise, you may need to enable <see cref="DiscordSocketConfig.AlwaysDownloadUsers"/> to fetch the full user list
+        ///         upon startup, or use <see cref="DownloadUsersAsync"/> to manually download the users.
+        ///     </note>
         /// </remarks>
         /// <returns>
-        ///     Collection of users.
+        ///     A collection of guild users found within this guild.
         /// </returns>
         public IReadOnlyCollection<SocketGuildUser> Users => _members.ToReadOnlyCollection();
         /// <summary>
-        ///     Gets a collection of roles in this guild.
+        ///     Gets a collection of all roles in this guild.
         /// </summary>
         /// <returns>
-        ///     Collection of roles.
+        ///     A read-only collection of roles found within this guild.
         /// </returns>
         public IReadOnlyCollection<SocketRole> Roles => _roles.ToReadOnlyCollection();
 
@@ -407,11 +422,13 @@ namespace Discord.WebSocket
 
         //Bans
         /// <summary>
-        ///     Returns a collection of the banned users in this guild.
+        ///     Gets a collection of all users banned in this guild.
         /// </summary>
         /// <param name="options">The options to be used when sending the request.</param>
         /// <returns>
-        ///     A collection of bans.
+        ///     A task that represents the asynchronous get operation. The task result contains a read-only collection of
+        ///     ban objects that this guild currently possesses, with each object containing the user banned and reason
+        ///     behind the ban.
         /// </returns>
         public Task<IReadOnlyCollection<RestBan>> GetBansAsync(RequestOptions options = null)
             => GuildHelper.GetBansAsync(this, Discord, options);
@@ -421,8 +438,8 @@ namespace Discord.WebSocket
         /// <param name="user">The banned user.</param>
         /// <param name="options">The options to be used when sending the request.</param>
         /// <returns>
-        ///     An awaitable <see cref="Task"/> containing a REST-based ban object, which contains the user information
-        ///     and the reason for the ban; <c>null</c> if the ban entry cannot be found.
+        ///     A task that represents the asynchronous get operation. The task result contains a ban object, which
+        ///     contains the user information and the reason for the ban; <c>null</c> if the ban entry cannot be found.
         /// </returns>
         public Task<RestBan> GetBanAsync(IUser user, RequestOptions options = null)
             => GuildHelper.GetBanAsync(this, Discord, user.Id, options);
@@ -432,8 +449,8 @@ namespace Discord.WebSocket
         /// <param name="userId">The snowflake identifier for the banned user.</param>
         /// <param name="options">The options to be used when sending the request.</param>
         /// <returns>
-        ///     An awaitable <see cref="Task"/> containing a REST-based ban object, which contains the user information
-        ///     and the reason for the ban; <c>null</c> if the ban entry cannot be found.
+        ///     A task that represents the asynchronous get operation. The task result contains a ban object, which
+        ///     contains the user information and the reason for the ban; <c>null</c> if the ban entry cannot be found.
         /// </returns>
         public Task<RestBan> GetBanAsync(ulong userId, RequestOptions options = null)
             => GuildHelper.GetBanAsync(this, Discord, userId, options);
@@ -454,11 +471,11 @@ namespace Discord.WebSocket
 
         //Channels
         /// <summary>
-        ///     Returns a guild channel with the provided ID.
+        ///     Gets a channel in this guild.
         /// </summary>
-        /// <param name="id">The channel ID.</param>
+        /// <param name="id">The snowflake identifier for the channel.</param>
         /// <returns>
-        ///     The guild channel associated with the ID.
+        ///     A generic channel associated with the specified <paramref name="id" />; <c>null</c> if none is found.
         /// </returns>
         public SocketGuildChannel GetChannel(ulong id)
         {
@@ -468,56 +485,59 @@ namespace Discord.WebSocket
             return null;
         }
         /// <summary>
-        ///     Returns a text channel with the provided ID.
+        ///     Gets a text channel in this guild.
         /// </summary>
-        /// <param name="id">The channel ID.</param>
+        /// <param name="id">The snowflake identifier for the text channel.</param>
         /// <returns>
-        ///     The text channel associated with the ID.
+        ///     A text channel associated with the specified <paramref name="id" />; <c>null</c> if none is found.
         /// </returns>
         public SocketTextChannel GetTextChannel(ulong id)
             => GetChannel(id) as SocketTextChannel;
         /// <summary>
-        ///     Returns a voice channel with the provided ID.
+        ///     Gets a voice channel in this guild.
         /// </summary>
-        /// <param name="id">The channel ID.</param>
+        /// <param name="id">The snowflake identifier for the voice channel.</param>
         /// <returns>
-        ///     The voice channel associated with the ID.
+        ///     A voice channel associated with the specified <paramref name="id" />; <c>null</c> if none is found.
         /// </returns>
         public SocketVoiceChannel GetVoiceChannel(ulong id)
             => GetChannel(id) as SocketVoiceChannel;
 
         /// <summary>
-        ///     Creates a text channel with the provided name.
+        ///     Creates a new text channel in this guild.
         /// </summary>
-        /// <param name="name">The name of the new channel.</param>
-        /// <param name="options">The options to be used when sending the request.</param>
+        /// <param name="name">The new name for the text channel.</param>
         /// <param name="func">The delegate containing the properties to be applied to the channel upon its creation.</param>
-        /// <exception cref="ArgumentNullException"><paramref name="name" /> is <c>null</c>.</exception>
+        /// <param name="options">The options to be used when sending the request.</param>
+        /// <exception cref="ArgumentNullException"><paramref name="name"/> is <c>null</c>.</exception>
         /// <returns>
-        ///     The created text channel.
+        ///     A task that represents the asynchronous creation operation. The task result contains the newly created
+        ///     text channel.
         /// </returns>
         public Task<RestTextChannel> CreateTextChannelAsync(string name, Action<TextChannelProperties> func = null, RequestOptions options = null)
             => GuildHelper.CreateTextChannelAsync(this, Discord, name, options, func);
         /// <summary>
-        ///     Creates a voice channel with the provided name.
+        ///     Creates a new voice channel in this guild.
         /// </summary>
-        /// <param name="name">The name of the new channel.</param>
+        /// <param name="name">The new name for the voice channel.</param>
         /// <param name="func">The delegate containing the properties to be applied to the channel upon its creation.</param>
         /// <param name="options">The options to be used when sending the request.</param>
-        /// <exception cref="ArgumentNullException"><paramref name="name" /> is <c>null</c>.</exception>
+        /// <exception cref="ArgumentNullException"><paramref name="name"/> is <c>null</c>.</exception>
         /// <returns>
-        ///     The created voice channel.
+        ///     A task that represents the asynchronous creation operation. The task result contains the newly created
+        ///     voice channel.
         /// </returns>
         public Task<RestVoiceChannel> CreateVoiceChannelAsync(string name, Action<VoiceChannelProperties> func = null, RequestOptions options = null)
             => GuildHelper.CreateVoiceChannelAsync(this, Discord, name, options, func);
         /// <summary>
-        ///     Creates a category channel with the provided name.
+        ///     Creates a new channel category in this guild.
         /// </summary>
-        /// <param name="name">The name of the new channel.</param>
+        /// <param name="name">The new name for the category.</param>
         /// <param name="options">The options to be used when sending the request.</param>
-        /// <exception cref="ArgumentNullException"><paramref name="name" /> is <c>null</c>.</exception>
+        /// <exception cref="ArgumentNullException"><paramref name="name"/> is <c>null</c>.</exception>
         /// <returns>
-        ///     The created category channel.
+        ///     A task that represents the asynchronous creation operation. The task result contains the newly created
+        ///     category channel.
         /// </returns>
         public Task<RestCategoryChannel> CreateCategoryChannelAsync(string name, RequestOptions options = null)
             => GuildHelper.CreateCategoryChannelAsync(this, Discord, name, options);
@@ -544,11 +564,12 @@ namespace Discord.WebSocket
 
         //Invites
         /// <summary>
-        ///     Returns a collection of invites associated with this channel.
+        ///     Gets a collection of all invites in 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 invites.
+        ///     A task that represents the asynchronous get operation. The task result contains a read-only collection of
+        ///     invite metadata, each representing information for an invite found within this guild.
         /// </returns>
         public Task<IReadOnlyCollection<RestInviteMetadata>> GetInvitesAsync(RequestOptions options = null)
             => GuildHelper.GetInvitesAsync(this, Discord, options);
@@ -557,18 +578,19 @@ namespace Discord.WebSocket
         /// </summary>
         /// <param name="options">The options to be used when sending the request.</param>
         /// <returns>
-        ///     A partial metadata of the vanity invite found within this guild.
+        ///     A task that represents the asynchronous get operation. The task result contains the partial metadata of
+        ///     the vanity invite found within this guild; <c>null</c> if none is found.
         /// </returns>
         public Task<RestInviteMetadata> GetVanityInviteAsync(RequestOptions options = null)
             => GuildHelper.GetVanityInviteAsync(this, Discord, options);
 
         //Roles
         /// <summary>
-        ///     Gets a role.
+        ///     Gets a role in this guild.
         /// </summary>
-        /// <param name="id">The snowflake identifier of the role.</param>
+        /// <param name="id">The snowflake identifier for the role.</param>
         /// <returns>
-        ///     The role associated with the snowflake identifier.
+        ///     A role that is associated with the specified <paramref name="id"/>; <c>null</c> if none is found.
         /// </returns>
         public SocketRole GetRole(ulong id)
         {
@@ -578,18 +600,17 @@ namespace Discord.WebSocket
         }
 
         /// <summary>
-        ///     Creates a role.
+        ///     Creates a new role with the provided name.
         /// </summary>
-        /// <param name="name">The name of the new role.</param>
-        /// <param name="permissions">
-        /// The permissions that the new role possesses. Set to <c>null</c> to use the default permissions.
-        /// </param>
-        /// <param name="color">The color of the role. Set to <c>null</c> to use the default color.</param>
-        /// <param name="isHoisted">Used to determine if users of this role are separated in the user list.</param>
+        /// <param name="name">The new name for the role.</param>
+        /// <param name="permissions">The guild permission that the role should possess.</param>
+        /// <param name="color">The color of the role.</param>
+        /// <param name="isHoisted">Whether the role is separated from others on the sidebar.</param>
         /// <param name="options">The options to be used when sending the request.</param>
-        /// <exception cref="ArgumentNullException"><paramref name="name" /> is <c>null</c>.</exception>
+        /// <exception cref="ArgumentNullException"><paramref name="name"/> is <c>null</c>.</exception>
         /// <returns>
-        ///     The created role.
+        ///     A task that represents the asynchronous creation operation. The task result contains the newly created
+        ///     role.
         /// </returns>
         public Task<RestRole> CreateRoleAsync(string name, GuildPermissions? permissions = default(GuildPermissions?), Color? color = default(Color?),
             bool isHoisted = false, RequestOptions options = null)
@@ -611,9 +632,16 @@ namespace Discord.WebSocket
         /// <summary>
         ///     Gets a user from this guild.
         /// </summary>
-        /// <param name="id">The snowflake identifier of the user (e.g. `168693960628371456`).</param>
+        /// <remarks>
+        ///     This method retrieves a user found within this guild.
+        ///     <note>
+        ///         This may return <c>null</c> in the WebSocket implementation due to incomplete user collection in
+        ///         large guilds.
+        ///     </note>
+        /// </remarks>
+        /// <param name="id">The snowflake identifier of the user.</param>
         /// <returns>
-        ///     A WebSocket-based guild user associated with the snowflake identifier.
+        ///     A guild user associated with the specified <paramref name="id"/>; <c>null</c> if none is found.
         /// </returns>
         public SocketGuildUser GetUser(ulong id)
         {
@@ -675,9 +703,7 @@ namespace Discord.WebSocket
             return null;
         }
 
-        /// <summary>
-        ///     Downloads the users of this guild to the WebSocket cache.
-        /// </summary>
+        /// <inheritdoc />
         public async Task DownloadUsersAsync()
         {
             await Discord.DownloadUsersAsync(new[] { this }).ConfigureAwait(false);
@@ -688,6 +714,15 @@ namespace Discord.WebSocket
         }
 
         //Audit logs
+        /// <summary>
+        ///     Gets the specified number of audit log entries for this guild.
+        /// </summary>
+        /// <param name="limit">The number of audit log entries to fetch.</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 the requested audit log entries.
+        /// </returns>
         public IAsyncEnumerable<IReadOnlyCollection<RestAuditLogEntry>> GetAuditLogsAsync(int limit, RequestOptions options = null)
             => GuildHelper.GetAuditLogsAsync(this, Discord, null, limit, options);
 
@@ -914,7 +949,7 @@ namespace Discord.WebSocket
         ///     Gets the name of the guild.
         /// </summary>
         /// <returns>
-        ///     A string that resolves to the <see cref="Discord.WebSocket.SocketGuild.Name" /> of this guild.
+        ///     A string that resolves to <see cref="Discord.WebSocket.SocketGuild.Name"/>.
         /// </returns>
         public override string ToString() => Name;
         private string DebuggerDisplay => $"{Name} ({Id})";
@@ -1025,6 +1060,7 @@ namespace Discord.WebSocket
         Task<IGuildUser> IGuild.GetOwnerAsync(CacheMode mode, RequestOptions options)
             => Task.FromResult<IGuildUser>(Owner);
 
+        /// <inheritdoc />
         async Task<IReadOnlyCollection<IAuditLogEntry>> IGuild.GetAuditLogAsync(int limit, CacheMode cacheMode, RequestOptions options)
         {
             if (cacheMode == CacheMode.AllowDownload)