Add XML Docs

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

@@ -117,7 +117,7 @@ IAsyncEnumerable<IReadOnlyCollection<IMessage>> GetMessagesAsync(IMessage fromMe
         /// </summary>
         /// <param name="options">The options to be used when sending the request.</param>
         /// <returns>
-        ///     A collection of messages.
+        ///     An awaitable Task containing a collection of messages.
         /// </returns>
         Task<IReadOnlyCollection<IMessage>> GetPinnedMessagesAsync(RequestOptions options = null);
 

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

@@ -31,14 +31,20 @@ public interface IMessage : ISnowflakeEntity, IDeletable
         /// <summary>
         ///     Gets the time this message was sent.
         /// </summary>
+        /// <returns>
+        ///     Time of when the message was sent.
+        /// </returns>
         DateTimeOffset Timestamp { get; }
         /// <summary>
-        ///     Gets the time of this message's last edit, or <see langword="null" /> if none is set.
+        ///     Gets the time of this message's last edit.
         /// </summary>
+        /// <returns>
+        ///     Time of when the message was last edited; <see langword="null"/> when the message is never edited.
+        /// </returns>
         DateTimeOffset? EditedTimestamp { get; }
 
         /// <summary>
-        ///     Gets the channel this message was sent to.
+        ///     Gets the source channel of the message.
         /// </summary>
         IMessageChannel Channel { get; }
         /// <summary>
@@ -49,10 +55,16 @@ public interface IMessage : ISnowflakeEntity, IDeletable
         /// <summary>
         ///     Returns all attachments included in this message.
         /// </summary>
+        /// <returns>
+        ///     Collection of attachments.
+        /// </returns>
         IReadOnlyCollection<IAttachment> Attachments { get; }
         /// <summary>
         ///     Returns all embeds included in this message.
         /// </summary>
+        /// <returns>
+        ///     Collection of embed objects.
+        /// </returns>
         IReadOnlyCollection<IEmbed> Embeds { get; }
         /// <summary>
         ///     Returns all tags included in this message's content.
@@ -61,14 +73,23 @@ public interface IMessage : ISnowflakeEntity, IDeletable
         /// <summary>
         ///     Returns the IDs of channels mentioned in this message.
         /// </summary>
+        /// <returns>
+        ///     Collection of channel IDs.
+        /// </returns>
         IReadOnlyCollection<ulong> MentionedChannelIds { get; }
         /// <summary>
         ///     Returns the IDs of roles mentioned in this message.
         /// </summary>
+        /// <returns>
+        ///     Collection of role IDs.
+        /// </returns>
         IReadOnlyCollection<ulong> MentionedRoleIds { get; }
         /// <summary>
         ///     Returns the IDs of users mentioned in this message.
         /// </summary>
+        /// <returns>
+        ///     Collection of user IDs.
+        /// </returns>
         IReadOnlyCollection<ulong> MentionedUserIds { get; }
     }
 }

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

@@ -1,7 +1,7 @@
 namespace Discord
 {
     /// <summary>
-    ///     Represents a message sent by the system.
+    ///     Represents a generic message sent by the system.
     /// </summary>
     public interface ISystemMessage : IMessage
     {

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

@@ -5,7 +5,7 @@
 namespace Discord
 {
     /// <summary>
-    ///     Represents a Discord message object.
+    ///     Represents a generic message sent by a user.
     /// </summary>
     public interface IUserMessage : IMessage
     {

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

@@ -12,37 +12,102 @@ public interface IRestMessageChannel : IMessageChannel
         /// <summary>
         ///     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="options">The options to be used when sending the request.</param>
+        /// <returns>
+        ///     An awaitable Task containing the message sent to the channel.
+        /// </returns>
         new Task<RestUserMessage> SendMessageAsync(string text, bool isTTS = false, Embed embed = null, RequestOptions options = null);
 #if FILESYSTEM
         /// <summary>
         ///     Sends a file to this message channel, with an optional caption.
         /// </summary>
+        /// <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="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.
+        /// </returns>
         new Task<RestUserMessage> SendFileAsync(string filePath, string text = null, bool isTTS = false, Embed embed = null, RequestOptions options = null);
 #endif
         /// <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>
+        /// <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="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.
+        /// </returns>
         new Task<RestUserMessage> SendFileAsync(Stream stream, string filename, string text = null, bool isTTS = false, Embed embed = null, RequestOptions options = null);
 
         /// <summary>
-        ///     Gets a message from this message channel with the given ID, or <see langword="null"/> if not found.
+        ///     Gets a message from this message channel with the given id, or <see langword="null"/> if not found.
         /// </summary>
+        /// <param name="id">The ID of the message.</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 <see langword="null"/> if none is found.
+        /// </returns>
         Task<RestMessage> GetMessageAsync(ulong id, RequestOptions options = null);
         /// <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>
         IAsyncEnumerable<IReadOnlyCollection<RestMessage>> GetMessagesAsync(int limit = DiscordConfig.MaxMessagesPerBatch, RequestOptions options = null);
         /// <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>
         IAsyncEnumerable<IReadOnlyCollection<RestMessage>> GetMessagesAsync(ulong fromMessageId, Direction dir, int limit = DiscordConfig.MaxMessagesPerBatch, RequestOptions options = null);
         /// <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>
         IAsyncEnumerable<IReadOnlyCollection<RestMessage>> GetMessagesAsync(IMessage fromMessage, Direction dir, int limit = DiscordConfig.MaxMessagesPerBatch, RequestOptions options = null);
         /// <summary>
         ///     Gets a collection of pinned messages in this channel.
         /// </summary>
+        /// <param name="options">The options to be used when sending the request.</param>
+        /// <returns>
+        ///     An awaitable Task containing a collection of messages.
+        /// </returns>
         new Task<IReadOnlyCollection<RestMessage>> GetPinnedMessagesAsync(RequestOptions options = null);
     }
 }

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

@@ -10,7 +10,12 @@ namespace Discord.WebSocket
     /// </summary>
     public interface ISocketMessageChannel : IMessageChannel
     {
-        /// <summary> Gets all messages in this channel's cache. </summary>
+        /// <summary>
+        ///     Gets all messages in this channel's cache.
+        /// </summary>
+        /// <returns>
+        ///     A collection of WebSocket-based messages.
+        /// </returns>
         IReadOnlyCollection<SocketMessage> CachedMessages { get; }
 
         /// <summary>
@@ -20,6 +25,9 @@ public interface ISocketMessageChannel : IMessageChannel
         /// <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="options">The options to be used when sending the request.</param>
+        /// <returns>
+        ///     An awaitable Task containing the message sent to the channel.
+        /// </returns>
         new Task<RestUserMessage> SendMessageAsync(string text, bool isTTS = false, Embed embed = null, RequestOptions options = null);
 #if FILESYSTEM
         /// <summary>
@@ -35,6 +43,9 @@ public interface ISocketMessageChannel : IMessageChannel
         ///     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.
+        /// </returns>
         new Task<RestUserMessage> SendFileAsync(string filePath, string text = null, bool isTTS = false, Embed embed = null, RequestOptions options = null);
 #endif
         /// <summary>
@@ -51,14 +62,47 @@ public interface ISocketMessageChannel : IMessageChannel
         ///     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.
+        /// </returns>
         new Task<RestUserMessage> SendFileAsync(Stream stream, string filename, string text = null, bool isTTS = false, Embed embed = null, RequestOptions options = null);
 
+        /// <summary>
+        ///     Gets the cached message if one exists.
+        /// </summary>
+        /// <param name="id">The ID of the message.</param>
+        /// <returns>
+        ///     Cached message object; <see langword="null"/> if it doesn't exist in the cache.
+        /// </returns>
         SocketMessage GetCachedMessage(ulong id);
-        /// <summary> Gets the last N messages from this message channel. </summary>
+        /// <summary>
+        ///     Gets the last N messages from this message channel.
+        /// </summary>
+        /// <param name="limit">The number of messages to get.</param>
+        /// <returns>
+        ///     A collection of WebSocket-based messages.
+        /// </returns>
         IReadOnlyCollection<SocketMessage> GetCachedMessages(int limit = DiscordConfig.MaxMessagesPerBatch);
-        /// <summary> Gets a collection of messages in this channel. </summary>
+
+        /// <summary>
+        ///     Gets a collection of messages in this channel.
+        /// </summary>
+        /// <param name="fromMessageId">The message ID to start the fetching from.</param>
+        /// <param name="dir">The direction of which the message should be gotten from.</param>
+        /// <param name="limit">The number of messages to get.</param>
+        /// <returns>
+        ///     A collection of WebSocket-based messages.
+        /// </returns>
         IReadOnlyCollection<SocketMessage> GetCachedMessages(ulong fromMessageId, Direction dir, int limit = DiscordConfig.MaxMessagesPerBatch);
-        /// <summary> Gets a collection of messages in this channel. </summary>
+        /// <summary>
+        ///     Gets a collection of messages in this channel.
+        /// </summary>
+        /// <param name="fromMessage">The message to start the fetching from.</param>
+        /// <param name="dir">The direction of which the message should be gotten from.</param>
+        /// <param name="limit">The number of messages to get.</param>
+        /// <returns>
+        ///     A collection of WebSocket-based messages.
+        /// </returns>
         IReadOnlyCollection<SocketMessage> GetCachedMessages(IMessage fromMessage, Direction dir, int limit = DiscordConfig.MaxMessagesPerBatch);
         /// <summary>
         ///     Gets a collection of pinned messages in this channel.

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

@@ -14,6 +14,7 @@ namespace Discord.WebSocket
     [DebuggerDisplay(@"{DebuggerDisplay,nq}")]
     public class SocketCategoryChannel : SocketGuildChannel, ICategoryChannel
     {
+        /// <inheritdoc />
         public override IReadOnlyCollection<SocketGuildUser> Users
             => Guild.Users.Where(x => Permissions.GetValue(
                Permissions.ResolveChannel(Guild, x, this, Permissions.ResolveGuild(Guild, x)),

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

@@ -30,7 +30,7 @@ internal SocketDMChannel(DiscordSocketClient discord, ulong id, SocketGlobalUser
             Recipient = recipient;
             recipient.GlobalUser.AddRef();
             if (Discord.MessageCacheSize > 0)
-                _messages = new MessageCache(Discord, this);
+                _messages = new MessageCache(Discord);
         }
         internal static SocketDMChannel Create(DiscordSocketClient discord, ClientState state, Model model)
         {

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

@@ -39,7 +39,7 @@ internal SocketGroupChannel(DiscordSocketClient discord, ulong id)
             : base(discord, id)
         {
             if (Discord.MessageCacheSize > 0)
-                _messages = new MessageCache(Discord, this);
+                _messages = new MessageCache(Discord);
             _voiceStates = new ConcurrentDictionary<ulong, SocketVoiceState>(ConcurrentHashSet.DefaultConcurrencyLevel, 5);
             _users = new ConcurrentDictionary<ulong, SocketGroupUser>(ConcurrentHashSet.DefaultConcurrencyLevel, 5);
         }
@@ -108,6 +108,7 @@ public Task<IReadOnlyCollection<RestMessage>> GetPinnedMessagesAsync(RequestOpti
             => 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, bool isTTS = false, Embed embed = null, RequestOptions options = null)
             => ChannelHelper.SendMessageAsync(this, Discord, text, isTTS, embed, options);
 #if FILESYSTEM

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

@@ -21,7 +21,7 @@ public class SocketGuildChannel : SocketChannel, IGuildChannel
         ///     Gets the guild associated with this channel.
         /// </summary>
         /// <returns>
-        ///     The guild that this channel belongs to.
+        ///     A guild that this channel belongs to.
         /// </returns>
         public SocketGuild Guild { get; }
         /// <inheritdoc />
@@ -34,15 +34,15 @@ public class SocketGuildChannel : SocketChannel, IGuildChannel
         ///     Gets the parent category of this channel.
         /// </summary>
         /// <returns>
-        ///     The parent category ID associated with this channel, or <see langword="null"/> if none is set.
+        ///     A parent category ID associated with this channel, or <see langword="null"/> if none is set.
         /// </returns>
         public ICategoryChannel Category 
             => CategoryId.HasValue ? Guild.GetChannel(CategoryId.Value) as ICategoryChannel : null;
 
         /// <inheritdoc />
         public IReadOnlyCollection<Overwrite> PermissionOverwrites => _overwrites;
         /// <summary>
-        ///     Returns a collection of users that are able to view the channel.
+        ///     Gets a collection of users that are able to view the channel.
         /// </summary>
         /// <returns>
         ///     A collection of users that can access the channel (i.e. the users seen in the user list).

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

@@ -39,7 +39,7 @@ internal SocketTextChannel(DiscordSocketClient discord, ulong id, SocketGuild gu
             : base(discord, id, guild)
         {
             if (Discord.MessageCacheSize > 0)
-                _messages = new MessageCache(Discord, this);
+                _messages = new MessageCache(Discord);
         }
         internal new static SocketTextChannel Create(SocketGuild guild, ClientState state, Model model)
         {