From bfd3f8b78b9d8141b98089ac58244b1250d38824 Mon Sep 17 00:00:00 2001
From: Still Hsu <5843208+Still34@users.noreply.github.com>
Date: Wed, 17 Jul 2019 17:58:35 +0800
Subject: [PATCH] Clarify all instances of IAsnycEnumerable

---
 .../Entities/Channels/IChannel.cs              | 18 ++++++++++++++----
 .../Entities/Channels/IGuildChannel.cs         | 10 ++++++----
 .../Extensions/AsyncEnumerableExtensions.cs    |  5 +++++
 3 files changed, 25 insertions(+), 8 deletions(-)

diff --git a/src/Discord.Net.Core/Entities/Channels/IChannel.cs b/src/Discord.Net.Core/Entities/Channels/IChannel.cs
index b66f778fb..e2df86f2a 100644
--- a/src/Discord.Net.Core/Entities/Channels/IChannel.cs
+++ b/src/Discord.Net.Core/Entities/Channels/IChannel.cs
@@ -17,14 +17,24 @@ namespace Discord
         string Name { get; }
 
         /// <summary>
-        ///     Gets a collection of all users in this channel.
+        ///     Gets a collection of users that are able to view the channel or are currently 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>
+        ///     This method will attempt to fetch all users that is able to view this channel or is currently in this channel.
+        ///     The library will attempt to split up the requests according to and <see cref="DiscordConfig.MaxUsersPerBatch"/>.
+        ///     In other words, if there are 3000 users, and the <see cref="Discord.DiscordConfig.MaxUsersPerBatch"/> constant
+        ///     is <c>1000</c>, the request will be split into 3 individual requests; thus returning 53individual asynchronous
+        ///     responses, hence the need of flattening.
+        /// </remarks>
         /// <param name="mode">The <see cref="CacheMode"/> that determines whether the object should be fetched from cache.</param>
         /// <param name="options">The options to be used when sending the request.</param>
         /// <returns>
-        ///     A paged collection containing a collection of users that can access this channel. Flattening the
-        ///     paginated response into a collection of users with 
-        ///     <see cref="AsyncEnumerableExtensions.FlattenAsync{T}"/> is required if you wish to access the users.
+        ///     Paged collection of users.
         /// </returns>
         IAsyncEnumerable<IReadOnlyCollection<IUser>> GetUsersAsync(CacheMode mode = CacheMode.AllowDownload, RequestOptions options = null);
 
diff --git a/src/Discord.Net.Core/Entities/Channels/IGuildChannel.cs b/src/Discord.Net.Core/Entities/Channels/IGuildChannel.cs
index efa5fb1e8..992bd71fc 100644
--- a/src/Discord.Net.Core/Entities/Channels/IGuildChannel.cs
+++ b/src/Discord.Net.Core/Entities/Channels/IGuildChannel.cs
@@ -132,14 +132,16 @@ namespace Discord
         Task AddPermissionOverwriteAsync(IUser user, OverwritePermissions permissions, RequestOptions options = null);
 
         /// <summary>
-        ///     Gets a collection of users that are able to view the channel.
+        ///     Gets a collection of users that are able to view the channel or are currently in this channel.
         /// </summary>
+        /// <remarks>
+        ///     This method follows the same behavior as described in <see cref="IChannel.GetUsersAsync"/>.
+        ///     Please visit its documentation for more details on this method.
+        /// </remarks>
         /// <param name="mode">The <see cref="CacheMode" /> that determines whether the object should be fetched from cache.</param>
         /// <param name="options">The options to be used when sending the request.</param>
         /// <returns>
-        ///     A paged collection containing a collection of guild users that can access this channel. Flattening the
-        ///     paginated response into a collection of users with 
-        ///     <see cref="AsyncEnumerableExtensions.FlattenAsync{T}"/> is required if you wish to access the users.
+        ///     Paged collection of users.
         /// </returns>
         new IAsyncEnumerable<IReadOnlyCollection<IGuildUser>> GetUsersAsync(CacheMode mode = CacheMode.AllowDownload, RequestOptions options = null);
         /// <summary>
diff --git a/src/Discord.Net.Core/Extensions/AsyncEnumerableExtensions.cs b/src/Discord.Net.Core/Extensions/AsyncEnumerableExtensions.cs
index 56ed68cfe..282d20517 100644
--- a/src/Discord.Net.Core/Extensions/AsyncEnumerableExtensions.cs
+++ b/src/Discord.Net.Core/Extensions/AsyncEnumerableExtensions.cs
@@ -5,6 +5,11 @@ using System.Threading.Tasks;
 namespace Discord
 {
     /// <summary> An extension class for squashing <see cref="IAsyncEnumerable{T}"/>. </summary>
+    /// <remarks>
+    ///     This set of extension methods will squash an <see cref="IAsyncEnumerable{T}"/> into a
+    ///     single <see cref="IEnumerable{T}"/>. This is often associated with requests that has a
+    ///     set limit when requesting.
+    /// </remarks>
     public static class AsyncEnumerableExtensions
     {
         /// <summary> Flattens the specified pages into one <see cref="IEnumerable{T}"/> asynchronously. </summary>