Add XML docs

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

@@ -53,18 +53,20 @@ namespace Discord
         ///     <see cref="Discord.EmbedBuilder.ImageUrl"/>.
         /// </remarks>
         /// <returns>
-        ///     An awaitable Task containing the message sent to the channel.
+        ///     An awaitable <see cref="Task"/> containing the message sent to the channel.
         /// </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 with the given id, or <c>null</c> if not found.
+        ///     Gets a message from this message channel.
         /// </summary>
         /// <param name="id">The ID of the message.</param>
-        /// <param name="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>
-        ///     The message gotten from either the cache or the download, or <c>null</c> if none is found.
+        ///     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.
         /// </returns>
         Task<IMessage> GetMessageAsync(ulong id, CacheMode mode = CacheMode.AllowDownload, RequestOptions options = null);
 
@@ -94,7 +96,6 @@ namespace Discord
         /// </returns>
         IAsyncEnumerable<IReadOnlyCollection<IMessage>> GetMessagesAsync(ulong fromMessageId, Direction dir, int limit = DiscordConfig.MaxMessagesPerBatch, 
             CacheMode mode = CacheMode.AllowDownload, RequestOptions options = null);
-
         /// <summary>
         ///     Gets a collection of messages in this channel.
         /// </summary>

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

@@ -55,7 +55,7 @@ namespace Discord
         /// <param name="func">The properties to modify the channel with.</param>
         /// <param name="options">The options to be used when sending the request.</param>
         Task ModifyAsync(Action<TextChannelProperties> func, RequestOptions options = null);
-
+        
         /// <summary>
         ///     Creates a webhook in this text channel.
         /// </summary>
@@ -63,24 +63,25 @@ 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>
-        ///     The created webhook.
+        ///     An awaitable <see cref="Task"/> containing the created webhook.
         /// </returns>
         Task<IWebhook> CreateWebhookAsync(string name, Stream avatar = null, RequestOptions options = null);
         /// <summary>
-        ///     Gets the webhook in this text channel with the provided ID.
+        ///     Gets a webhook available in this text channel.
         /// </summary>
-        /// <param name="id">The ID of the webhook.</param>
+        /// <param name="id">The identifier of the webhook.</param>
         /// <param name="options">The options to be used when sending the request.</param>
         /// <returns>
-        ///     A webhook associated with the <paramref name="id"/>, or <c>null</c> if not found.
+        ///     An awaitable <see cref="Task"/> containing a webhook associated with the identifier; <c>null</c> if not
+        ///     found.
         /// </returns>
         Task<IWebhook> GetWebhookAsync(ulong id, RequestOptions options = null);
         /// <summary>
-        ///     Gets the webhooks for this text channel.
+        ///     Gets the webhooks available in this text channel.
         /// </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.
+        ///     An awaitable <see cref="Task"/> containing a collection of found webhooks.
         /// </returns>
         Task<IReadOnlyCollection<IWebhook>> GetWebhooksAsync(RequestOptions options = null);
     }

src/Discord.Net.Core/Entities/IApplication.cs

@@ -19,7 +19,7 @@ namespace Discord
         string[] RPCOrigins { get; }
         ulong Flags { get; }
         /// <summary>
-        /// Gets the icon URL of the application.
+        ///     Gets the icon URL of the application.
         /// </summary>
         string IconUrl  { get; }
 

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

@@ -6,12 +6,27 @@ namespace Discord
     [DebuggerDisplay("{DebuggerDisplay,nq}")]
     public struct EmbedFooter
     {
-        /// <summary> Gets the text of the footer.</summary>
-        public string Text { get; internal set; }
-        /// <summary> Gets the icon URL of the footer.</summary>
-        public string IconUrl { get; internal set; }
-        /// <summary> Gets the proxified icon URL of the footer.</summary>
-        public string ProxyUrl { get; internal set; }
+        /// <summary>
+        ///     Gets the text of the footer field.
+        /// </summary>
+        /// <returns>
+        ///     A string containing the text of the footer field.
+        /// </returns>
+        public string Text { get; }
+        /// <summary>
+        ///     Gets the URL of the footer icon.
+        /// </summary>
+        /// <returns>
+        ///     A string containing the URL of the footer icon.
+        /// </returns>
+        public string IconUrl { get; }
+        /// <summary>
+        ///     Gets the proxied URL of the footer icon link.
+        /// </summary>
+        /// <returns>
+        ///     A string containing the proxied URL of the footer icon.
+        /// </returns>
+        public string ProxyUrl { get; }
 
         internal EmbedFooter(string text, string iconUrl, string proxyUrl)
         {
@@ -21,6 +36,12 @@ namespace Discord
         }
 
         private string DebuggerDisplay => $"{Text} ({IconUrl})";
+        /// <summary>
+        ///     Gets the text of the footer field.
+        /// </summary>
+        /// <returns>
+        ///     A string that resolves to <see cref="Discord.EmbedFooter.Text"/>.
+        /// </returns>
         public override string ToString() => Text;
     }
 }

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

@@ -6,13 +6,35 @@ namespace Discord
     [DebuggerDisplay("{DebuggerDisplay,nq}")]
     public struct EmbedImage
     {
-        /// <summary> Gets the URL of the image.</summary>
+        /// <summary>
+        ///     Gets the URL of the image.
+        /// </summary>
+        /// <returns>
+        ///     A string containing the URL of the image.
+        /// </returns>
         public string Url { get; }
-        /// <summary> Gets the proxified URL of the image.</summary>
+        /// <summary>
+        ///     Gets a proxied URL of this image.
+        /// </summary>
+        /// <returns>
+        ///     A string containing the proxied URL of this image.
+        /// </returns>
         public string ProxyUrl { get; }
-        /// <summary> Gets the height of the image if any is set. </summary>
+        /// <summary>
+        ///     Gets the height of this image.
+        /// </summary>
+        /// <returns>
+        ///     A <see cref="int"/> representing the height of this image if it can be retrieved; otherwise 
+        ///     <c>null</c>.
+        /// </returns>
         public int? Height { get; }
-        /// <summary> Gets the width of the image if any is set. </summary>
+        /// <summary>
+        ///     Gets the width of this image.
+        /// </summary>
+        /// <returns>
+        ///     A <see cref="int"/> representing the width of this image if it can be retrieved; otherwise 
+        ///     <c>null</c>.
+        /// </returns>
         public int? Width { get; }
 
         internal EmbedImage(string url, string proxyUrl, int? height, int? width)
@@ -24,6 +46,12 @@ namespace Discord
         }
 
         private string DebuggerDisplay => $"{Url} ({(Width != null && Height != null ? $"{Width}x{Height}" : "0x0")})";
-        public override string ToString() => Url.ToString();
+        /// <summary>
+        ///     Gets the URL of the thumbnail.
+        /// </summary>
+        /// <returns>
+        ///     A string that resolves to <see cref="Discord.EmbedImage.Url"/> .
+        /// </returns>
+        public override string ToString() => Url;
     }
 }

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

@@ -6,9 +6,19 @@ namespace Discord
     [DebuggerDisplay("{DebuggerDisplay,nq}")]
     public struct EmbedProvider
     {
-        /// <summary> Gets the name of the provider.</summary>
+        /// <summary>
+        ///     Gets the name of the provider.
+        /// </summary>
+        /// <returns>
+        ///     A string representing the name of the provider.
+        /// </returns>
         public string Name { get; }
-        /// <summary> Gets the URL of the provider.</summary>
+        /// <summary>
+        ///     Gets the URL of the provider.
+        /// </summary>
+        /// <returns>
+        ///     A string representing the link to the provider.
+        /// </returns>
         public string Url { get; }
 
         internal EmbedProvider(string name, string url)
@@ -18,6 +28,12 @@ namespace Discord
         }
 
         private string DebuggerDisplay => $"{Name} ({Url})";
+        /// <summary>
+        ///     Gets the name of the provider.
+        /// </summary>
+        /// <returns>
+        ///     A string that resolves to <see cref="Discord.EmbedProvider.Name" />.
+        /// </returns>
         public override string ToString() => Name;
     }
 }

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

@@ -6,13 +6,35 @@ namespace Discord
     [DebuggerDisplay("{DebuggerDisplay,nq}")]
     public struct EmbedThumbnail
     {
-        /// <summary> Gets the URL of the thumbnail.</summary>
+        /// <summary>
+        ///     Gets the URL of the thumbnail.
+        /// </summary>
+        /// <returns>
+        ///     A string containing the URL of the thumbnail.
+        /// </returns>
         public string Url { get; }
-        /// <summary> Gets the proxified URL of the thumbnail.</summary>
+        /// <summary>
+        ///     Gets a proxied URL of this thumbnail.
+        /// </summary>
+        /// <returns>
+        ///     A string containing the proxied URL of this thumbnail.
+        /// </returns>
         public string ProxyUrl { get; }
-        /// <summary> Gets the height of the thumbnail if any is set. </summary>
+        /// <summary>
+        ///     Gets the height of this thumbnail.
+        /// </summary>
+        /// <returns>
+        ///     A <see cref="int"/> representing the height of this thumbnail if it can be retrieved; otherwise 
+        ///     <c>null</c>.
+        /// </returns>
         public int? Height { get; }
-        /// <summary> Gets the width of the thumbnail if any is set. </summary>
+        /// <summary>
+        ///     Gets the width of this thumbnail.
+        /// </summary>
+        /// <returns>
+        ///     A <see cref="int"/> representing the width of this thumbnail if it can be retrieved; otherwise 
+        ///     <c>null</c>.
+        /// </returns>
         public int? Width { get; }
 
         internal EmbedThumbnail(string url, string proxyUrl, int? height, int? width)
@@ -24,6 +46,12 @@ namespace Discord
         }
 
         private string DebuggerDisplay => $"{Url} ({(Width != null && Height != null ? $"{Width}x{Height}" : "0x0")})";
-        public override string ToString() => Url.ToString();
+        /// <summary>
+        ///     Gets the URL of the thumbnail.
+        /// </summary>
+        /// <returns>
+        ///     A string that resolves to <see cref="Discord.EmbedThumbnail.Url" />.
+        /// </returns>
+        public override string ToString() => Url;
     }
 }

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

@@ -12,32 +12,75 @@ namespace Discord
         /// <summary>
         ///     Modifies this message.
         /// </summary>
+        /// <example>
+        /// <code language="cs">
+        /// await msg.ModifyAsync(x =&gt; x.Content = "Hello World!");
+        /// </code>
+        /// </example>
+        /// <param name="func">A delegate containing the properties to modify the message with.</param>
+        /// <param name="options">The options to be used when sending the request.</param>
+        /// <returns>
+        ///     An awaitable <see cref="Task"/>.
+        /// </returns>
         Task ModifyAsync(Action<MessageProperties> func, RequestOptions options = null);
         /// <summary>
         ///     Adds this message to its channel's pinned messages.
         /// </summary>
+        /// <param name="options">The options to be used when sending the request.</param>
+        /// <returns>
+        ///     An awaitable <see cref="Task"/>.
+        /// </returns>
         Task PinAsync(RequestOptions options = null);
         /// <summary>
         ///     Removes this message from its channel's pinned messages.
         /// </summary>
+        /// <param name="options">The options to be used when sending the request.</param>
+        /// <returns>
+        ///     An awaitable <see cref="Task"/>.
+        /// </returns>
         Task UnpinAsync(RequestOptions options = null);
 
         /// <summary>
-        ///     Returns all reactions included in this message.
+        ///     Gets all reactions included in this message.
         /// </summary>
         IReadOnlyDictionary<IEmote, ReactionMetadata> Reactions { get; }
 
         /// <summary>
         ///     Adds a reaction to this message.
         /// </summary>
+        /// <example>
+        /// <code language="cs">
+        /// await msg.AddReactionAsync(new Emoji("\U0001f495"));
+        /// </code>
+        /// </example>
+        /// <param name="emote">The emoji used to react to this message.</param>
+        /// <param name="options">The options to be used when sending the request.</param>
+        /// <returns>
+        ///     An awaitable <see cref="Task"/>.
+        /// </returns>
         Task AddReactionAsync(IEmote emote, RequestOptions options = null);
         /// <summary>
         ///     Removes a reaction from message.
         /// </summary>
+        /// <example>
+        /// <code language="cs">
+        /// await msg.RemoveReactionAsync(new Emoji("\U0001f495"), msg.Author);
+        /// </code>
+        /// </example>
+        /// <param name="emote">The emoji used to react to this message.</param>
+        /// <param name="user">The user that added the emoji.</param>
+        /// <param name="options">The options to be used when sending the request.</param>
+        /// <returns>
+        ///     An awaitable <see cref="Task"/>.
+        /// </returns>
         Task RemoveReactionAsync(IEmote emote, IUser user, RequestOptions options = null);
         /// <summary>
         ///     Removes all reactions from this message.
         /// </summary>
+        /// <param name="options">The options to be used when sending the request.</param>
+        /// <returns>
+        ///     An awaitable <see cref="Task"/>.
+        /// </returns>
         Task RemoveAllReactionsAsync(RequestOptions options = null);
         /// <summary>
         ///     Gets all users that reacted to a message with a given emote.
@@ -47,6 +90,11 @@ namespace Discord
         /// <summary>
         ///     Transforms this message's text into a human-readable form by resolving its tags.
         /// </summary>
+        /// <param name="userHandling">Determines how the user tag should be handled.</param>
+        /// <param name="channelHandling">Determines how the channel tag should be handled.</param>
+        /// <param name="roleHandling">Determines how the role tag should be handled.</param>
+        /// <param name="everyoneHandling">Determines how the @everyone tag should be handled.</param>
+        /// <param name="emojiHandling">Determines how the emoji tag should be handled.</param>
         string Resolve(
             TagHandling userHandling = TagHandling.Name,
             TagHandling channelHandling = TagHandling.Name,

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

@@ -4,12 +4,12 @@ using System.Threading.Tasks;
 namespace Discord
 {
     /// <summary>
-    ///     Represents a generic role object.
+    ///     Represents a generic role object to be given to a guild user.
     /// </summary>
     public interface IRole : ISnowflakeEntity, IDeletable, IMentionable, IComparable<IRole>
     {
         /// <summary>
-        ///     Gets the guild owning this role.
+        ///     Gets the guild that owns this role.
         /// </summary>
         /// <returns>
         ///     A guild representing the parent guild of this role.

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

@@ -1,7 +1,7 @@
 namespace Discord
 {
     /// <summary>
-    ///     Represents a Discord user's presence status.
+    ///     Represents the user's presence status. This may include their online status and their activity.
     /// </summary>
     public interface IPresence
     {

src/Discord.Net.Core/Logging/LogMessage.cs

@@ -4,29 +4,41 @@ using System.Text;
 namespace Discord
 {
     /// <summary>
-    ///     Represents a message used for logging purposes.
+    ///     Provides a message object used for logging purposes.
     /// </summary>
     public struct LogMessage
     {
         /// <summary>
-        ///     Gets the severity of the log message.
+        ///     Gets the severity of the log entry.
         /// </summary>
+        /// <returns>
+        ///     A <see cref="LogSeverity"/> enum to indicate the severeness of the incident or event.
+        /// </returns>
         public LogSeverity Severity { get; }
         /// <summary>
-        ///     Gets the source of the log message.
+        ///     Gets the source of the log entry.
         /// </summary>
+        /// <returns>
+        ///     A string representing the source of the log entry.
+        /// </returns>
         public string Source { get; }
         /// <summary>
-        ///     Gets the message of the log message.
+        ///     Gets the message of this log entry.
         /// </summary>
+        /// <returns>
+        ///     A string containing the message of this log entry.
+        /// </returns>
         public string Message { get; }
         /// <summary>
-        ///     Gets the exception of the log message.
+        ///     Gets the exception of this log entry.
         /// </summary>
+        /// <returns>
+        ///     An <see cref="Discord.LogMessage.Exception" /> object associated with an incident; otherwise <c>null</c>.
+        /// </returns>
         public Exception Exception { get; }
 
         /// <summary>
-        ///     Initializes a new <see cref="LogMessage" /> struct with the severity, source, message of the event, and
+        ///     Initializes a new <see cref="LogMessage"/> struct with the severity, source, message of the event, and
         ///     optionally, an exception.
         /// </summary>
         /// <param name="severity">The severity of the event.</param>

src/Discord.Net.Core/RequestOptions.cs

@@ -13,11 +13,23 @@ namespace Discord
         public static RequestOptions Default => new RequestOptions();
 
         /// <summary>
-        ///     Gets or set the max time, in milliseconds, to wait for this request to complete. If 
-        ///     <c>null</c>, a request will not time out. If a rate limit has been triggered for this
-        ///     request's bucket and will not be unpaused in time, this request will fail immediately.
+        ///     Gets or sets the maximum time to wait for for this request to complete.
         /// </summary>
+        /// <remarks>
+        ///     Gets or set the max time, in milliseconds, to wait for for this request to complete. If 
+        ///     <c>null</c>, a request will not time out. If a rate limit has been triggered for this request's bucket
+        ///     and will not be unpaused in time, this request will fail immediately.
+        /// </remarks>
+        /// <returns>
+        ///     A <see cref="int"/> in milliseconds for when the request times out.
+        /// </returns>
         public int? Timeout { get; set; }
+        /// <summary>
+        ///     Gets or sets the cancellation token for this request.
+        /// </summary>
+        /// <returns>
+        ///     A <see cref="CancellationToken"/> for this request.
+        /// </returns>
         public CancellationToken CancelToken { get; set; } = CancellationToken.None;
         /// <summary>
         ///     Gets or sets the retry behavior when the request fails.

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

@@ -2,13 +2,12 @@ using System;
 
 namespace Discord
 {
-    //Source: https://github.com/dotnet/coreclr/blob/master/src/mscorlib/src/System/DateTimeOffset.cs
+    /// <see href="https://github.com/dotnet/coreclr/blob/master/src/mscorlib/src/System/DateTimeOffset.cs"/>
     internal static class DateTimeUtils
     {
         public static DateTimeOffset FromTicks(long ticks)
             => new DateTimeOffset(ticks, TimeSpan.Zero);
         public static DateTimeOffset? FromTicks(long? ticks)
             => ticks != null ? new DateTimeOffset(ticks.Value, TimeSpan.Zero) : (DateTimeOffset?)null;
-       
     }
 }

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

@@ -5,7 +5,7 @@ using System.Text;
 namespace Discord
 {
     /// <summary>
-    ///     Represents a helper class for mention-related parsing.
+    ///     Provides a series of helper methods for parsing mentions.
     /// </summary>
     public static class MentionUtils
     {

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

@@ -2,10 +2,27 @@ using System;
 
 namespace Discord
 {
+    /// <summary>
+    ///     Provides a series of helper methods for handling snowflake identifiers.
+    /// </summary>
     public static class SnowflakeUtils
     {
+        /// <summary>
+        ///     Resolves the time of which the snowflake is generated.
+        /// </summary>
+        /// <param name="value">The snowflake identifier to resolve.</param>
+        /// <returns>
+        ///     A <see cref="DateTimeOffset" /> representing the time for when the object is geenrated.
+        /// </returns>
         public static DateTimeOffset FromSnowflake(ulong value)
             => DateTimeOffset.FromUnixTimeMilliseconds((long)((value >> 22) + 1420070400000UL));
+        /// <summary>
+        ///     Generates a pseudo-snowflake identifier with a <see cref="DateTimeOffset"/>.
+        /// </summary>
+        /// <param name="value">The time to be used in the new snowflake.</param>
+        /// <returns>
+        ///     A <see cref="UInt64" /> representing the newly generated snowflake identifier.
+        /// </returns>
         public static ulong ToSnowflake(DateTimeOffset value)
             => ((ulong)value.ToUnixTimeMilliseconds() - 1420070400000UL) << 22;
     }

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

@@ -3,6 +3,7 @@ using System;
 using System.Collections.Generic;
 using System.Collections.Immutable;
 using System.Diagnostics;
+using System.Diagnostics.CodeAnalysis;
 using System.IO;
 using System.Linq;
 using System.Threading.Tasks;

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

@@ -20,7 +20,14 @@ namespace Discord.WebSocket
 
         /// <inheritdoc />
         public string Topic { get; private set; }
+        /// <inheritdoc />
         public ulong? CategoryId { get; private set; }
+        /// <summary>
+        ///     Gets the parent (category) of this channel in the guild's channel list.
+        /// </summary>
+        /// <returns>
+        ///     An <see cref="ICategoryChannel"/> representing the parent of this channel; <c>null</c> if none is set.
+        /// </returns>
         public ICategoryChannel Category
             => CategoryId.HasValue ? Guild.GetChannel(CategoryId.Value) as ICategoryChannel : null;
 
@@ -66,6 +73,15 @@ namespace Discord.WebSocket
         /// <inheritdoc />
         public SocketMessage GetCachedMessage(ulong id)
             => _messages?.Get(id);
+        /// <summary>
+        ///     Gets a message from this message channel.
+        /// </summary>
+        /// <param name="id">The ID of the message.</param>
+        /// <param name="options">The options to be used when sending the request.</param>
+        /// <returns>
+        ///     An awaitable <see cref="Task"/> containing the downloaded message; <c>null</c> if none is found or if
+        ///     the message fails to be retrieved.
+        /// </returns>
         public async Task<IMessage> GetMessageAsync(ulong id, RequestOptions options = null)
         {
             IMessage msg = _messages?.Get(id);
@@ -73,10 +89,41 @@ namespace Discord.WebSocket
                 msg = await ChannelHelper.GetMessageAsync(this, Discord, id, options).ConfigureAwait(false);
             return msg;
         }
+        /// <summary>
+        ///     Gets the last N messages from this message channel.
+        /// </summary>
+        /// <param name="limit">The numbers of message to be gotten from.</param>
+        /// <param name="options">The options to be used when sending the request.</param>
+        /// <returns>
+        ///     Paged collection of messages. Flattening the paginated response into a collection of messages with 
+        ///     <see cref="AsyncEnumerableExtensions.FlattenAsync{T}"/> is required if you wish to access the messages.
+        /// </returns>
         public IAsyncEnumerable<IReadOnlyCollection<IMessage>> GetMessagesAsync(int limit = DiscordConfig.MaxMessagesPerBatch, RequestOptions options = null)
             => SocketChannelHelper.GetMessagesAsync(this, Discord, _messages, null, Direction.Before, limit, CacheMode.AllowDownload, options);
+        /// <summary>
+        ///     Gets a collection of messages in this channel.
+        /// </summary>
+        /// <param name="fromMessageId">The ID of the starting message to get the messages from.</param>
+        /// <param name="dir">The direction of the messages to be gotten from.</param>
+        /// <param name="limit">The numbers of message to be gotten from.</param>
+        /// <param name="options">The options to be used when sending the request.</param>
+        /// <returns>
+        ///     Paged collection of messages. Flattening the paginated response into a collection of messages with 
+        ///     <see cref="AsyncEnumerableExtensions.FlattenAsync{T}"/> is required if you wish to access the messages.
+        /// </returns>
         public IAsyncEnumerable<IReadOnlyCollection<IMessage>> GetMessagesAsync(ulong fromMessageId, Direction dir, int limit = DiscordConfig.MaxMessagesPerBatch, RequestOptions options = null)
             => SocketChannelHelper.GetMessagesAsync(this, Discord, _messages, fromMessageId, dir, limit, CacheMode.AllowDownload, options);
+        /// <summary>
+        ///     Gets a collection of messages in this channel.
+        /// </summary>
+        /// <param name="fromMessage">The starting message to get the messages from.</param>
+        /// <param name="dir">The direction of the messages to be gotten from.</param>
+        /// <param name="limit">The numbers of message to be gotten from.</param>
+        /// <param name="options">The options to be used when sending the request.</param>
+        /// <returns>
+        ///     Paged collection of messages. Flattening the paginated response into a collection of messages with 
+        ///     <see cref="AsyncEnumerableExtensions.FlattenAsync{T}"/> is required if you wish to access the messages.
+        /// </returns>
         public IAsyncEnumerable<IReadOnlyCollection<IMessage>> GetMessagesAsync(IMessage fromMessage, Direction dir, int limit = DiscordConfig.MaxMessagesPerBatch, RequestOptions options = null)
             => SocketChannelHelper.GetMessagesAsync(this, Discord, _messages, fromMessage.Id, dir, limit, CacheMode.AllowDownload, options);
         /// <inheritdoc />
@@ -93,13 +140,16 @@ namespace Discord.WebSocket
             => ChannelHelper.GetPinnedMessagesAsync(this, Discord, options);
 
         /// <inheritdoc />
+        /// <exception cref="ArgumentOutOfRangeException">Message content is too long, length must be less or equal to <see cref="DiscordConfig.MaxMessageSize"/>.</exception>
         public Task<RestUserMessage> SendMessageAsync(string text = null, bool isTTS = false, Embed embed = null, RequestOptions options = null)
             => ChannelHelper.SendMessageAsync(this, Discord, text, isTTS, embed, options);
 
         /// <inheritdoc />
         public Task<RestUserMessage> SendFileAsync(string filePath, string text, bool isTTS = false, Embed embed = null, RequestOptions options = null)
             => ChannelHelper.SendFileAsync(this, Discord, filePath, text, isTTS, embed, options);
+
         /// <inheritdoc />
+        /// <exception cref="ArgumentOutOfRangeException">Message content is too long, length must be less or equal to <see cref="DiscordConfig.MaxMessageSize"/>.</exception>
         public Task<RestUserMessage> SendFileAsync(Stream stream, string filename, string text, bool isTTS = false, Embed embed = null, RequestOptions options = null)
             => ChannelHelper.SendFileAsync(this, Discord, stream, filename, text, isTTS, embed, options);
 
@@ -110,8 +160,10 @@ namespace Discord.WebSocket
         public Task DeleteMessagesAsync(IEnumerable<ulong> messageIds, RequestOptions options = null)
             => ChannelHelper.DeleteMessagesAsync(this, Discord, messageIds, options);
 
+        /// <inheritdoc />
         public Task DeleteMessageAsync(ulong messageId, RequestOptions options = null)
             => ChannelHelper.DeleteMessageAsync(this, messageId, Discord, options);
+        /// <inheritdoc />
         public Task DeleteMessageAsync(IMessage message, RequestOptions options = null)
             => ChannelHelper.DeleteMessageAsync(this, message.Id, Discord, options);
 
@@ -150,7 +202,7 @@ namespace Discord.WebSocket
         /// <param name="avatar">The avatar of the webhook.</param>
         /// <param name="options">The options to be used when sending the request.</param>
         /// <returns>
-        ///     The created webhook.
+        ///     An awaitable <see cref="Task"/> containing the created webhook.
         /// </returns>
         public Task<RestWebhook> CreateWebhookAsync(string name, Stream avatar = null, RequestOptions options = null)
             => ChannelHelper.CreateWebhookAsync(this, Discord, name, avatar, options);
@@ -160,7 +212,8 @@ namespace Discord.WebSocket
         /// <param name="id">The identifier of the webhook.</param>
         /// <param name="options">The options to be used when sending the request.</param>
         /// <returns>
-        ///     An awaitable <see cref="Task"/> webhook associated with the identifier, or <c>null</c> if not found.
+        ///     An awaitable <see cref="Task"/> containing a webhook associated with the identifier; <c>null</c> if not
+        ///     found.
         /// </returns>
         public Task<RestWebhook> GetWebhookAsync(ulong id, RequestOptions options = null)
             => ChannelHelper.GetWebhookAsync(this, Discord, id, options);
@@ -169,7 +222,7 @@ namespace Discord.WebSocket
         /// </summary>
         /// <param name="options">The options to be used when sending the request.</param>
         /// <returns>
-        ///     An awaitable <see cref="Task"/> collection of webhooks.
+        ///     An awaitable <see cref="Task"/> containing a collection of found webhooks.
         /// </returns>
         public Task<IReadOnlyCollection<RestWebhook>> GetWebhooksAsync(RequestOptions options = null)
             => ChannelHelper.GetWebhooksAsync(this, Discord, options);
@@ -229,6 +282,7 @@ namespace Discord.WebSocket
             => await SendMessageAsync(text, isTTS, embed, options).ConfigureAwait(false);
 
         // INestedChannel
+        /// <inheritdoc />
         Task<ICategoryChannel> INestedChannel.GetCategoryAsync(CacheMode mode, RequestOptions options)
             => Task.FromResult(Category);
     }

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

@@ -20,7 +20,14 @@ namespace Discord.WebSocket
         public int Bitrate { get; private set; }
         /// <inheritdoc />
         public int? UserLimit { get; private set; }
+        /// <inheritdoc />
         public ulong? CategoryId { get; private set; }
+        /// <summary>
+        ///     Gets the parent (category) of this channel in the guild's channel list.
+        /// </summary>
+        /// <returns>
+        ///     An <see cref="ICategoryChannel"/> representing the parent of this channel; <c>null</c> if none is set.
+        /// </returns>
         public ICategoryChannel Category
             => CategoryId.HasValue ? Guild.GetChannel(CategoryId.Value) as ICategoryChannel : null;
 
@@ -56,6 +63,12 @@ namespace Discord.WebSocket
             return await Guild.ConnectAudioAsync(Id, selfDeaf, selfMute, external).ConfigureAwait(false);
         }
 
+        /// <summary>
+        ///     Disconnects from this voice channel if the client is in an active voice connection.
+        /// </summary>
+        /// <returns>
+        ///     An awaitable <see cref="Task" /> .
+        /// </returns>
         public async Task DisconnectAsync()
             => await Guild.DisconnectAudioAsync();
 
@@ -80,6 +93,7 @@ namespace Discord.WebSocket
             => ImmutableArray.Create<IReadOnlyCollection<IGuildUser>>(Users).ToAsyncEnumerable();
 
         // INestedChannel
+        /// <inheritdoc />
         Task<ICategoryChannel> INestedChannel.GetCategoryAsync(CacheMode mode, RequestOptions options)
             => Task.FromResult(Category);
     }

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

@@ -415,8 +415,26 @@ namespace Discord.WebSocket
         /// </returns>
         public Task<IReadOnlyCollection<RestBan>> GetBansAsync(RequestOptions options = null)
             => GuildHelper.GetBansAsync(this, Discord, options);
+        /// <summary>
+        ///     Gets a ban object for a banned user.
+        /// </summary>
+        /// <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.
+        /// </returns>
         public Task<RestBan> GetBanAsync(IUser user, RequestOptions options = null)
             => GuildHelper.GetBanAsync(this, Discord, user.Id, options);
+        /// <summary>
+        ///     Gets a ban object for a banned user.
+        /// </summary>
+        /// <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.
+        /// </returns>
         public Task<RestBan> GetBanAsync(ulong userId, RequestOptions options = null)
             => GuildHelper.GetBanAsync(this, Discord, userId, options);
 
@@ -895,6 +913,9 @@ namespace Discord.WebSocket
         /// <summary>
         ///     Gets the name of the guild.
         /// </summary>
+        /// <returns>
+        ///     A string that resolves to the <see cref="Discord.WebSocket.SocketGuild.Name" /> of this guild.
+        /// </returns>
         public override string ToString() => Name;
         private string DebuggerDisplay => $"{Name} ({Id})";
         internal SocketGuild Clone() => MemberwiseClone() as SocketGuild;

src/Discord.Net.WebSocket/Entities/Roles/SocketRole.cs

@@ -8,9 +8,18 @@ using Model = Discord.API.Role;
 
 namespace Discord.WebSocket
 {
+    /// <summary>
+    ///     Represents a WebSocket-based role to be given to a guild user.
+    /// </summary>
     [DebuggerDisplay(@"{DebuggerDisplay,nq}")]
     public class SocketRole : SocketEntity<ulong>, IRole
     {
+        /// <summary>
+        ///     Gets the guild that owns this role.
+        /// </summary>
+        /// <returns>
+        ///     A <see cref="SocketGuild"/> representing the parent guild of this role.
+        /// </returns>
         public SocketGuild Guild { get; }
 
         /// <inheritdoc />
@@ -30,6 +39,12 @@ namespace Discord.WebSocket
 
         /// <inheritdoc />
         public DateTimeOffset CreatedAt => SnowflakeUtils.FromSnowflake(Id);
+        /// <summary>
+        ///     Returns a value that determines if the role is an @everyone role.
+        /// </summary>
+        /// <returns>
+        ///     <c>true</c> if the role is @everyone; otherwise <c>false</c>.
+        /// </returns>
         public bool IsEveryone => Id == Guild.Id;
         /// <inheritdoc />
         public string Mention => IsEveryone ? "@everyone" : MentionUtils.MentionRole(Id);
@@ -65,6 +80,12 @@ namespace Discord.WebSocket
         public Task DeleteAsync(RequestOptions options = null)
             => RoleHelper.DeleteAsync(this, Discord, options);
 
+        /// <summary>
+        ///     Gets the name of the role.
+        /// </summary>
+        /// <returns>
+        ///     A string that resolves to <see cref="Discord.WebSocket.SocketRole.Name" />.
+        /// </returns>
         public override string ToString() => Name;
         private string DebuggerDisplay => $"{Name} ({Id})";
         internal SocketRole Clone() => MemberwiseClone() as SocketRole;

src/Discord.Net.WebSocket/Entities/Users/SocketGroupUser.cs

@@ -6,7 +6,14 @@ namespace Discord.WebSocket
     [DebuggerDisplay("{DebuggerDisplay,nq}")]
     public class SocketGroupUser : SocketUser, IGroupUser
     {
+        /// <summary>
+        ///     Gets the group channel of the user.
+        /// </summary>
+        /// <returns>
+        ///     A <see cref="SocketGroupChannel" /> representing the channel of which the user belongs to.
+        /// </returns>
         public SocketGroupChannel Channel { get; }
+        /// <inheritdoc />
         internal override SocketGlobalUser GlobalUser { get; }
 
         /// <inheritdoc />
@@ -17,6 +24,7 @@ namespace Discord.WebSocket
         public override ushort DiscriminatorValue { get { return GlobalUser.DiscriminatorValue; } internal set { GlobalUser.DiscriminatorValue = value; } }
         /// <inheritdoc />
         public override string AvatarId { get { return GlobalUser.AvatarId; } internal set { GlobalUser.AvatarId = value; } }
+        /// <inheritdoc />
         internal override SocketPresence Presence { get { return GlobalUser.Presence; } set { GlobalUser.Presence = value; } }
 
         /// <inheritdoc />

src/Discord.Net.WebSocket/Entities/Users/SocketPresence.cs

@@ -3,6 +3,9 @@ using Model = Discord.API.Presence;
 
 namespace Discord.WebSocket
 {
+    /// <summary>
+    ///     Represents the WebSocket user's presence status. This may include their online status and their activity.
+    /// </summary>
     [DebuggerDisplay(@"{DebuggerDisplay,nq}")]
     public struct SocketPresence : IPresence
     {
@@ -21,6 +24,12 @@ namespace Discord.WebSocket
             return new SocketPresence(model.Status, model.Game?.ToEntity());
         }
 
+        /// <summary>
+        ///     Gets the status of the user.
+        /// </summary>
+        /// <returns>
+        ///     A string that resolves to <see cref="Discord.WebSocket.SocketPresence.Status" />.
+        /// </returns>
         public override string ToString() => Status.ToString();
         private string DebuggerDisplay => $"{Status}{(Activity != null ? $", {Activity.Name}": "")}";
 

src/Discord.Net.WebSocket/Entities/Users/SocketSelfUser.cs

@@ -6,6 +6,9 @@ using Model = Discord.API.User;
 
 namespace Discord.WebSocket
 {
+    /// <summary>
+    ///     Represents the logged-in WebSocker-based user.
+    /// </summary>
     [DebuggerDisplay(@"{DebuggerDisplay,nq}")]
     public class SocketSelfUser : SocketUser, ISelfUser
     {

src/Discord.Net.WebSocket/Entities/Users/SocketUnknownUser.cs

@@ -4,17 +4,30 @@ using Model = Discord.API.User;
 
 namespace Discord.WebSocket
 {
+    /// <summary>
+    ///     Represents a WebSocket-based user that is yet to be recognized by the client.
+    /// </summary>
+    /// <remarks>
+    ///     A user may not be recognized due to the user missing from the cache or failed to be recognized properly.
+    /// </remarks>
     [DebuggerDisplay(@"{DebuggerDisplay,nq}")]
     public class SocketUnknownUser : SocketUser
     {
+        /// <inheritdoc />
         public override string Username { get; internal set; }
+        /// <inheritdoc />
         public override ushort DiscriminatorValue { get; internal set; }
+        /// <inheritdoc />
         public override string AvatarId { get; internal set; }
+        /// <inheritdoc />
         public override bool IsBot { get; internal set; }
-
+        
+        /// <inheritdoc />
         public override bool IsWebhook => false;
 
         internal override SocketPresence Presence { get { return new SocketPresence(UserStatus.Offline, null); } set { } }
+        /// <inheritdoc />
+        /// <exception cref="NotSupportedException">This field is not supported for an unknown user.</exception>
         internal override SocketGlobalUser GlobalUser =>
             throw new NotSupportedException();
 

src/Discord.Net.WebSocket/Entities/Users/SocketVoiceState.cs

@@ -4,9 +4,15 @@ using Model = Discord.API.VoiceState;
 
 namespace Discord.WebSocket
 {
+    /// <summary>
+    ///     Represents a WebSocket user's voice connection status.
+    /// </summary>
     [DebuggerDisplay(@"{DebuggerDisplay,nq}")]
     public struct SocketVoiceState : IVoiceState
     {
+        /// <summary>
+        ///     Initializes a default <see cref="SocketVoiceState"/> with everything set to <c>null</c> or <c>false</c>.
+        /// </summary>
         public static readonly SocketVoiceState Default = new SocketVoiceState(null, null, false, false, false, false, false);
 
         [Flags]
@@ -64,15 +70,16 @@ namespace Discord.WebSocket
         }
 
         /// <summary>
-        ///     Gets the name of the voice channel.
+        ///     Gets the name of this voice channel.
         /// </summary>
         /// <returns>
-        ///     The name of the voice channel.
+        ///     A string that resolves to name of this voice channel; otherwise "Unknown".
         /// </returns>
         public override string ToString() => VoiceChannel?.Name ?? "Unknown";
         private string DebuggerDisplay => $"{VoiceChannel?.Name ?? "Unknown"} ({_voiceStates})";
         internal SocketVoiceState Clone() => this;
 
+        /// <inheritdoc />
         IVoiceChannel IVoiceState.VoiceChannel => VoiceChannel;
     }
 }