Clarify all instances of IAsnycEnumerable

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);
 

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>

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>