Add XML docs & rewrite GetMessagesAsync docs

This commit rewrites the remarks section of GetMessagesAsync, as well as adding examples to several methods.

src/Discord.Net.Commands/Results/ExecuteResult.cs

@@ -3,6 +3,9 @@ using System.Diagnostics;
 
 namespace Discord.Commands
 {
+    /// <summary>
+    ///     Contains information of the command's overall execution result.
+    /// </summary>
     [DebuggerDisplay(@"{DebuggerDisplay,nq}")]
     public struct ExecuteResult : IResult
     {
@@ -26,15 +29,56 @@ namespace Discord.Commands
             ErrorReason = errorReason;
         }
 
+        /// <summary>
+        ///     Initializes a new <see cref="ExecuteResult" /> with no error, indicating a successful execution.
+        /// </summary>
+        /// <returns>
+        ///     A <see cref="ExecuteResult" /> that does not contain any errors.
+        /// </returns>
         public static ExecuteResult FromSuccess()
             => new ExecuteResult(null, null, null);
+        /// <summary>
+        ///     Initializes a new <see cref="ExecuteResult" /> with a specified <see cref="CommandError" /> and its
+        ///     reason, indicating an unsuccessful execution.
+        /// </summary>
+        /// <param name="error">The type of error.</param>
+        /// <param name="reason">The reason behind the error.</param>
+        /// <returns>
+        ///     A <see cref="ExecuteResult" /> that contains a <see cref="CommandError" /> and reason.
+        /// </returns>
         public static ExecuteResult FromError(CommandError error, string reason)
             => new ExecuteResult(null, error, reason);
+        /// <summary>
+        ///     Initializes a new <see cref="ExecuteResult" /> with a specified exception, indicating an unsuccessful
+        ///     execution.
+        /// </summary>
+        /// <param name="ex">The exception that caused the command execution to fail.</param>
+        /// <returns>
+        ///     A <see cref="ExecuteResult" /> that contains the exception that caused the unsuccessful execution, along
+        ///     with a <see cref="CommandError" /> of type <c>Exception</c> as well as the exception message as the
+        ///     reason.
+        /// </returns>
         public static ExecuteResult FromError(Exception ex)
             => new ExecuteResult(ex, CommandError.Exception, ex.Message);
+        /// <summary>
+        ///     Initializes a new <see cref="ExecuteResult" /> with a specified result; this may or may not be an
+        ///     successful execution depending on the <see cref="Discord.Commands.IResult.Error" /> and
+        ///     <see cref="Discord.Commands.IResult.ErrorReason" /> specified.
+        /// </summary>
+        /// <param name="result">The result to inherit from.</param>
+        /// <returns>
+        ///     A <see cref="ExecuteResult"/> that inherits the <see cref="IResult"/> error type and reason.
+        /// </returns>
         public static ExecuteResult FromError(IResult result)
             => new ExecuteResult(null, result.Error, result.ErrorReason);
-        
+
+        /// <summary>
+        ///     Gets a string that indicates the execution result.
+        /// </summary>
+        /// <returns>
+        ///     <c>Success</c> if <see cref="IsSuccess"/> is <c>true</c>; otherwise "<see cref="Error"/>: 
+        ///     <see cref="ErrorReason"/>".
+        /// </returns>
         public override string ToString() => IsSuccess ? "Success" : $"{Error}: {ErrorReason}";
         private string DebuggerDisplay => IsSuccess ? "Success" : $"{Error}: {ErrorReason}";
     }

src/Discord.Net.Commands/Results/IResult.cs

@@ -1,13 +1,31 @@
 namespace Discord.Commands
 {
-    /// <summary> Represents information of the command execution result. </summary>
+    /// <summary>
+    ///     Contains information of the result related to a command.
+    /// </summary>
     public interface IResult
     {
-        /// <summary> Describes the error type that may have occurred during the operation. </summary>
+        /// <summary>
+        ///     Describes the error type that may have occurred during the operation.
+        /// </summary>
+        /// <returns>
+        ///     A <see cref="CommandError" /> indicating the type of error that may have occurred during the operation; 
+        ///     <c>null</c> if the operation was successful.
+        /// </returns>
         CommandError? Error { get; }
-        /// <summary> Describes the reason for the error. </summary>
+        /// <summary>
+        ///     Describes the reason for the error.
+        /// </summary>
+        /// <returns>
+        ///     A string containing the error reason.
+        /// </returns>
         string ErrorReason { get; }
-        /// <summary> Indicates whether the operation was successful or not. </summary>
+        /// <summary>
+        ///     Indicates whether the operation was successful or not.
+        /// </summary>
+        /// <returns>
+        ///     <c>true</c> if the result is positive; otherwise <c>false</c>.
+        /// </returns>
         bool IsSuccess { get; }
     }
 }

src/Discord.Net.Commands/Results/ParseResult.cs

@@ -4,6 +4,9 @@ using System.Diagnostics;
 
 namespace Discord.Commands
 {
+    /// <summary>
+    ///     Contains information for the parsing result from the command service's parser.
+    /// </summary>
     [DebuggerDisplay(@"{DebuggerDisplay,nq}")]
     public struct ParseResult : IResult
     {

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

@@ -81,32 +81,105 @@ namespace Discord
         /// <summary>
         ///     Gets the last N messages from this message channel.
         /// </summary>
+        /// <remarks>
+        ///     <note type="important">
+        ///         The returned collection is an asynchronous enumerable object; one must call 
+        ///         <see cref="AsyncEnumerableExtensions.FlattenAsync{T}"/> to access the individual messages as a
+        ///         collection.
+        ///     </note>
+        ///     <note type="warning">
+        ///         Do not fetch too many messages at once! This may cause unwanted preemptive rate limit or even actual
+        ///         rate limit, causing your bot to freeze!
+        ///     </note>
+        ///     This method will attempt to fetch the number of messages specified under <paramref name="limit"/>. The
+        ///     library will attempt to split up the requests according to your <paramref name="limit"/> and 
+        ///     <see cref="DiscordConfig.MaxMessagesPerBatch"/>. In other words, should the user request 500 messages,
+        ///     and the <see cref="Discord.DiscordConfig.MaxMessagesPerBatch"/> constant is <c>100</c>, the request will
+        ///     be split into 5 individual requests; thus returning 5 individual asynchronous responses, hence the need
+        ///     of flattening.
+        /// </remarks>
+        /// <example>
+        ///     The following example downloads 300 messages and gets messages that belong to the user 
+        ///     <c>53905483156684800</c>.
+        ///     <code lang="cs">
+        ///     var messages = await messageChannel.GetMessagesAsync(300).FlattenAsync();
+        ///     var userMessages = messages.Where(x =&gt; x.Author.Id == 53905483156684800);
+        ///     </code>
+        /// </example>
         /// <param name="limit">The numbers of message to be gotten from.</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>
-        ///     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.
+        ///     Paged collection of messages.
         /// </returns>
         IAsyncEnumerable<IReadOnlyCollection<IMessage>> GetMessagesAsync(int limit = DiscordConfig.MaxMessagesPerBatch, 
             CacheMode mode = CacheMode.AllowDownload, RequestOptions options = null);
         /// <summary>
         ///     Gets a collection of messages in this channel.
         /// </summary>
+        /// <remarks>
+        ///     <note type="important">
+        ///         The returned collection is an asynchronous enumerable object; one must call 
+        ///         <see cref="AsyncEnumerableExtensions.FlattenAsync{T}"/> to access the individual messages as a
+        ///         collection.
+        ///     </note>
+        ///     <note type="warning">
+        ///         Do not fetch too many messages at once! This may cause unwanted preemptive rate limit or even actual
+        ///         rate limit, causing your bot to freeze!
+        ///     </note>
+        ///     This method will attempt to fetch the number of messages specified under <paramref name="limit"/> around
+        ///     the message <paramref name="fromMessageId"/> depending on the <paramref name="dir"/>. The library will
+        ///     attempt to split up the requests according to your <paramref name="limit"/> and 
+        ///     <see cref="DiscordConfig.MaxMessagesPerBatch"/>. In other words, should the user request 500 messages,
+        ///     and the <see cref="Discord.DiscordConfig.MaxMessagesPerBatch"/> constant is <c>100</c>, the request will
+        ///     be split into 5 individual requests; thus returning 5 individual asynchronous responses, hence the need
+        ///     of flattening.
+        /// </remarks>
+        /// <example>
+        ///     The following example gets 5 message prior to the message identifier <c>442012544660537354</c>.
+        ///     <code lang="cs">
+        ///     var messages = await channel.GetMessagesAsync(442012544660537354, Direction.Before, 5).FlattenAsync();
+        ///     </code>
+        /// </example>
         /// <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="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>
-        ///     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.
+        ///     Paged collection of messages.
         /// </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>
+        /// <remarks>
+        ///     <note type="important">
+        ///         The returned collection is an asynchronous enumerable object; one must call 
+        ///         <see cref="AsyncEnumerableExtensions.FlattenAsync{T}"/> to access the individual messages as a
+        ///         collection.
+        ///     </note>
+        ///     <note type="warning">
+        ///         Do not fetch too many messages at once! This may cause unwanted preemptive rate limit or even actual
+        ///         rate limit, causing your bot to freeze!
+        ///     </note>
+        ///     This method will attempt to fetch the number of messages specified under <paramref name="limit"/> around
+        ///     the message <paramref name="fromMessage"/> depending on the <paramref name="dir"/>. The library will
+        ///     attempt to split up the requests according to your <paramref name="limit"/> and 
+        ///     <see cref="DiscordConfig.MaxMessagesPerBatch"/>. In other words, should the user request 500 messages,
+        ///     and the <see cref="Discord.DiscordConfig.MaxMessagesPerBatch"/> constant is <c>100</c>, the request will
+        ///     be split into 5 individual requests; thus returning 5 individual asynchronous responses, hence the need
+        ///     of flattening.
+        /// </remarks>
+        /// <example>
+        ///     The following example gets 5 message prior to a specific message, <c>oldMessage</c>.
+        ///     <code lang="cs">
+        ///     var messages = await channel.GetMessagesAsync(oldMessage, Direction.Before, 5).FlattenAsync();
+        ///     </code>
+        /// </example>
         /// <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>
@@ -114,8 +187,7 @@ namespace Discord
         /// cache.</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.
+        ///     Paged collection of messages.
         /// </returns>
         IAsyncEnumerable<IReadOnlyCollection<IMessage>> GetMessagesAsync(IMessage fromMessage, Direction dir, int limit = DiscordConfig.MaxMessagesPerBatch, 
             CacheMode mode = CacheMode.AllowDownload, RequestOptions options = null);
@@ -158,6 +230,15 @@ namespace Discord
         ///     Continuously broadcasts the "user is typing" message to all users in this channel until the returned
         ///     object is disposed.
         /// </summary>
+        /// <example>
+        ///     The following example keeps the client in the typing state until <c>LongRunningAsync</c> has finished.
+        ///     <code lang="cs">
+        ///     using (messageChannel.EnterTypingState())
+        ///     {
+        ///         await LongRunningAsync();
+        ///     }
+        ///     </code>
+        /// </example>
         /// <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

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

@@ -29,6 +29,13 @@ namespace Discord
         /// <summary>
         ///     Bulk-deletes multiple messages.
         /// </summary>
+        /// <example>
+        ///     The following example gets 250 messages from the channel and deletes them.
+        ///     <code lang="cs">
+        ///     var messages = await textChannel.GetMessagesAsync(250).FlattenAsync();
+        ///     await textChannel.DeleteMessagesAsync(messages);
+        ///     </code>
+        /// </example>
         /// <remarks>
         ///     This method attempts to remove the messages specified in bulk.
         ///     <note type="important">

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

@@ -78,35 +78,109 @@ namespace Discord.Rest
         /// <summary>
         ///     Gets the last N messages from this message channel.
         /// </summary>
+        /// <remarks>
+        ///     <note type="important">
+        ///         The returned collection is an asynchronous enumerable object; one must call 
+        ///         <see cref="AsyncEnumerableExtensions.FlattenAsync{T}"/> to access the individual messages as a
+        ///         collection.
+        ///     </note>
+        ///     <note type="warning">
+        ///         Do not fetch too many messages at once! This may cause unwanted preemptive rate limit or even actual
+        ///         rate limit, causing your bot to freeze!
+        ///     </note>
+        ///     This method will attempt to fetch the number of messages specified under <paramref name="limit"/>. The
+        ///     library will attempt to split up the requests according to your <paramref name="limit"/> and 
+        ///     <see cref="DiscordConfig.MaxMessagesPerBatch"/>. In other words, should the user request 500 messages,
+        ///     and the <see cref="Discord.DiscordConfig.MaxMessagesPerBatch"/> constant is <c>100</c>, the request will
+        ///     be split into 5 individual requests; thus returning 5 individual asynchronous responses, hence the need
+        ///     of flattening.
+        /// </remarks>
+        /// <example>
+        ///     The following example downloads 300 messages and gets messages that belong to the user 
+        ///     <c>53905483156684800</c>.
+        ///     <code lang="cs">
+        ///     var messages = await messageChannel.GetMessagesAsync(300).FlattenAsync();
+        ///     var userMessages = messages.Where(x =&gt; x.Author.Id == 53905483156684800);
+        ///     </code>
+        /// </example>
         /// <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.
+        ///     Paged collection of messages.
         /// </returns>
         IAsyncEnumerable<IReadOnlyCollection<RestMessage>> GetMessagesAsync(int limit = DiscordConfig.MaxMessagesPerBatch, RequestOptions options = null);
         /// <summary>
         ///     Gets a collection of messages in this channel.
         /// </summary>
+        /// <remarks>
+        ///     <note type="important">
+        ///         The returned collection is an asynchronous enumerable object; one must call 
+        ///         <see cref="AsyncEnumerableExtensions.FlattenAsync{T}"/> to access the individual messages as a
+        ///         collection.
+        ///     </note>
+        ///     <note type="warning">
+        ///         Do not fetch too many messages at once! This may cause unwanted preemptive rate limit or even actual
+        ///         rate limit, causing your bot to freeze!
+        ///     </note>
+        ///     This method will attempt to fetch the number of messages specified under <paramref name="limit"/> around
+        ///     the message <paramref name="fromMessageId"/> depending on the <paramref name="dir"/>. The library will
+        ///     attempt to split up the requests according to your <paramref name="limit"/> and 
+        ///     <see cref="DiscordConfig.MaxMessagesPerBatch"/>. In other words, should the user request 500 messages,
+        ///     and the <see cref="Discord.DiscordConfig.MaxMessagesPerBatch"/> constant is <c>100</c>, the request will
+        ///     be split into 5 individual requests; thus returning 5 individual asynchronous responses, hence the need
+        ///     of flattening.
+        /// </remarks>
+        /// <example>
+        ///     The following example gets 5 message prior to the message identifier <c>442012544660537354</c>.
+        ///     <code lang="cs">
+        ///     var messages = await channel.GetMessagesAsync(442012544660537354, Direction.Before, 5).FlattenAsync();
+        ///     </code>
+        /// </example>
         /// <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="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>
-        ///     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.
+        ///     Paged collection of 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>
+        /// <remarks>
+        ///     <note type="important">
+        ///         The returned collection is an asynchronous enumerable object; one must call 
+        ///         <see cref="AsyncEnumerableExtensions.FlattenAsync{T}"/> to access the individual messages as a
+        ///         collection.
+        ///     </note>
+        ///     <note type="warning">
+        ///         Do not fetch too many messages at once! This may cause unwanted preemptive rate limit or even actual
+        ///         rate limit, causing your bot to freeze!
+        ///     </note>
+        ///     This method will attempt to fetch the number of messages specified under <paramref name="limit"/> around
+        ///     the message <paramref name="fromMessage"/> depending on the <paramref name="dir"/>. The library will
+        ///     attempt to split up the requests according to your <paramref name="limit"/> and 
+        ///     <see cref="DiscordConfig.MaxMessagesPerBatch"/>. In other words, should the user request 500 messages,
+        ///     and the <see cref="Discord.DiscordConfig.MaxMessagesPerBatch"/> constant is <c>100</c>, the request will
+        ///     be split into 5 individual requests; thus returning 5 individual asynchronous responses, hence the need
+        ///     of flattening.
+        /// </remarks>
+        /// <example>
+        ///     The following example gets 5 message prior to a specific message, <c>oldMessage</c>.
+        ///     <code lang="cs">
+        ///     var messages = await channel.GetMessagesAsync(oldMessage, Direction.Before, 5).FlattenAsync();
+        ///     </code>
+        /// </example>
         /// <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="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>
-        ///     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.
+        ///     Paged collection of messages.
         /// </returns>
         IAsyncEnumerable<IReadOnlyCollection<RestMessage>> GetMessagesAsync(IMessage fromMessage, Direction dir, int limit = DiscordConfig.MaxMessagesPerBatch, RequestOptions options = null);
         /// <summary>

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

@@ -75,41 +75,109 @@ namespace Discord.WebSocket
         }
 
         /// <summary>
-        ///     Gets the last N messages from this channel.
+        ///     Gets the last N messages from this message channel.
         /// </summary>
-        /// <param name="limit">The number of messages to get.</param>
+        /// <remarks>
+        ///     <note type="important">
+        ///         The returned collection is an asynchronous enumerable object; one must call 
+        ///         <see cref="AsyncEnumerableExtensions.FlattenAsync{T}"/> to access the individual messages as a
+        ///         collection.
+        ///     </note>
+        ///     <note type="warning">
+        ///         Do not fetch too many messages at once! This may cause unwanted preemptive rate limit or even actual
+        ///         rate limit, causing your bot to freeze!
+        ///     </note>
+        ///     This method will attempt to fetch the number of messages specified under <paramref name="limit"/>. The
+        ///     library will attempt to split up the requests according to your <paramref name="limit"/> and 
+        ///     <see cref="DiscordConfig.MaxMessagesPerBatch"/>. In other words, should the user request 500 messages,
+        ///     and the <see cref="Discord.DiscordConfig.MaxMessagesPerBatch"/> constant is <c>100</c>, the request will
+        ///     be split into 5 individual requests; thus returning 5 individual asynchronous responses, hence the need
+        ///     of flattening.
+        /// </remarks>
+        /// <example>
+        ///     The following example downloads 300 messages and gets messages that belong to the user 
+        ///     <c>53905483156684800</c>.
+        ///     <code lang="cs">
+        ///     var messages = await messageChannel.GetMessagesAsync(300).FlattenAsync();
+        ///     var userMessages = messages.Where(x =&gt; x.Author.Id == 53905483156684800);
+        ///     </code>
+        /// </example>
+        /// <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.
+        ///     Paged collection of 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>
+        /// <remarks>
+        ///     <note type="important">
+        ///         The returned collection is an asynchronous enumerable object; one must call 
+        ///         <see cref="AsyncEnumerableExtensions.FlattenAsync{T}"/> to access the individual messages as a
+        ///         collection.
+        ///     </note>
+        ///     <note type="warning">
+        ///         Do not fetch too many messages at once! This may cause unwanted preemptive rate limit or even actual
+        ///         rate limit, causing your bot to freeze!
+        ///     </note>
+        ///     This method will attempt to fetch the number of messages specified under <paramref name="limit"/> around
+        ///     the message <paramref name="fromMessageId"/> depending on the <paramref name="dir"/>. The library will
+        ///     attempt to split up the requests according to your <paramref name="limit"/> and 
+        ///     <see cref="DiscordConfig.MaxMessagesPerBatch"/>. In other words, should the user request 500 messages,
+        ///     and the <see cref="Discord.DiscordConfig.MaxMessagesPerBatch"/> constant is <c>100</c>, the request will
+        ///     be split into 5 individual requests; thus returning 5 individual asynchronous responses, hence the need
+        ///     of flattening.
+        /// </remarks>
+        /// <example>
+        ///     The following example gets 5 message prior to the message identifier <c>442012544660537354</c>.
+        ///     <code lang="cs">
+        ///     var messages = await channel.GetMessagesAsync(442012544660537354, Direction.Before, 5).FlattenAsync();
+        ///     </code>
+        /// </example>
         /// <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.
+        ///     Paged collection of 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>
+        /// <remarks>
+        ///     <note type="important">
+        ///         The returned collection is an asynchronous enumerable object; one must call 
+        ///         <see cref="AsyncEnumerableExtensions.FlattenAsync{T}"/> to access the individual messages as a
+        ///         collection.
+        ///     </note>
+        ///     <note type="warning">
+        ///         Do not fetch too many messages at once! This may cause unwanted preemptive rate limit or even actual
+        ///         rate limit, causing your bot to freeze!
+        ///     </note>
+        ///     This method will attempt to fetch the number of messages specified under <paramref name="limit"/> around
+        ///     the message <paramref name="fromMessage"/> depending on the <paramref name="dir"/>. The library will
+        ///     attempt to split up the requests according to your <paramref name="limit"/> and 
+        ///     <see cref="DiscordConfig.MaxMessagesPerBatch"/>. In other words, should the user request 500 messages,
+        ///     and the <see cref="Discord.DiscordConfig.MaxMessagesPerBatch"/> constant is <c>100</c>, the request will
+        ///     be split into 5 individual requests; thus returning 5 individual asynchronous responses, hence the need
+        ///     of flattening.
+        /// </remarks>
+        /// <example>
+        ///     The following example gets 5 message prior to a specific message, <c>oldMessage</c>.
+        ///     <code lang="cs">
+        ///     var messages = await channel.GetMessagesAsync(oldMessage, Direction.Before, 5).FlattenAsync();
+        ///     </code>
+        /// </example>
         /// <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.
+        ///     Paged collection of 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);

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

@@ -92,37 +92,108 @@ namespace Discord.WebSocket
         /// <summary>
         ///     Gets the last N messages from this message channel.
         /// </summary>
+        /// <remarks>
+        ///     <note type="important">
+        ///         The returned collection is an asynchronous enumerable object; one must call 
+        ///         <see cref="AsyncEnumerableExtensions.FlattenAsync{T}"/> to access the individual messages as a
+        ///         collection.
+        ///     </note>
+        ///     <note type="warning">
+        ///         Do not fetch too many messages at once! This may cause unwanted preemptive rate limit or even actual
+        ///         rate limit, causing your bot to freeze!
+        ///     </note>
+        ///     This method will attempt to fetch the number of messages specified under <paramref name="limit"/>. The
+        ///     library will attempt to split up the requests according to your <paramref name="limit"/> and 
+        ///     <see cref="DiscordConfig.MaxMessagesPerBatch"/>. In other words, should the user request 500 messages,
+        ///     and the <see cref="Discord.DiscordConfig.MaxMessagesPerBatch"/> constant is <c>100</c>, the request will
+        ///     be split into 5 individual requests; thus returning 5 individual asynchronous responses, hence the need
+        ///     of flattening.
+        /// </remarks>
+        /// <example>
+        ///     The following example downloads 300 messages and gets messages that belong to the user 
+        ///     <c>53905483156684800</c>.
+        ///     <code lang="cs">
+        ///     var messages = await messageChannel.GetMessagesAsync(300).FlattenAsync();
+        ///     var userMessages = messages.Where(x =&gt; x.Author.Id == 53905483156684800);
+        ///     </code>
+        /// </example>
         /// <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.
+        ///     Paged collection of 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>
+        /// <remarks>
+        ///     <note type="important">
+        ///         The returned collection is an asynchronous enumerable object; one must call 
+        ///         <see cref="AsyncEnumerableExtensions.FlattenAsync{T}"/> to access the individual messages as a
+        ///         collection.
+        ///     </note>
+        ///     <note type="warning">
+        ///         Do not fetch too many messages at once! This may cause unwanted preemptive rate limit or even actual
+        ///         rate limit, causing your bot to freeze!
+        ///     </note>
+        ///     This method will attempt to fetch the number of messages specified under <paramref name="limit"/> around
+        ///     the message <paramref name="fromMessageId"/> depending on the <paramref name="dir"/>. The library will
+        ///     attempt to split up the requests according to your <paramref name="limit"/> and 
+        ///     <see cref="DiscordConfig.MaxMessagesPerBatch"/>. In other words, should the user request 500 messages,
+        ///     and the <see cref="Discord.DiscordConfig.MaxMessagesPerBatch"/> constant is <c>100</c>, the request will
+        ///     be split into 5 individual requests; thus returning 5 individual asynchronous responses, hence the need
+        ///     of flattening.
+        /// </remarks>
+        /// <example>
+        ///     The following example gets 5 message prior to the message identifier <c>442012544660537354</c>.
+        ///     <code lang="cs">
+        ///     var messages = await channel.GetMessagesAsync(442012544660537354, Direction.Before, 5).FlattenAsync();
+        ///     </code>
+        /// </example>
         /// <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.
+        ///     Paged collection of 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>
+        /// <remarks>
+        ///     <note type="important">
+        ///         The returned collection is an asynchronous enumerable object; one must call 
+        ///         <see cref="AsyncEnumerableExtensions.FlattenAsync{T}"/> to access the individual messages as a
+        ///         collection.
+        ///     </note>
+        ///     <note type="warning">
+        ///         Do not fetch too many messages at once! This may cause unwanted preemptive rate limit or even actual
+        ///         rate limit, causing your bot to freeze!
+        ///     </note>
+        ///     This method will attempt to fetch the number of messages specified under <paramref name="limit"/> around
+        ///     the message <paramref name="fromMessage"/> depending on the <paramref name="dir"/>. The library will
+        ///     attempt to split up the requests according to your <paramref name="limit"/> and 
+        ///     <see cref="DiscordConfig.MaxMessagesPerBatch"/>. In other words, should the user request 500 messages,
+        ///     and the <see cref="Discord.DiscordConfig.MaxMessagesPerBatch"/> constant is <c>100</c>, the request will
+        ///     be split into 5 individual requests; thus returning 5 individual asynchronous responses, hence the need
+        ///     of flattening.
+        /// </remarks>
+        /// <example>
+        ///     The following example gets 5 message prior to a specific message, <c>oldMessage</c>.
+        ///     <code lang="cs">
+        ///     var messages = await channel.GetMessagesAsync(oldMessage, Direction.Before, 5).FlattenAsync();
+        ///     </code>
+        /// </example>
         /// <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.
+        ///     Paged collection of 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);