From af40f5edf7725ef655873dd248d0b97427638b7c Mon Sep 17 00:00:00 2001
From: Still Hsu <341464@gmail.com>
Date: Wed, 7 Nov 2018 02:29:36 +0800
Subject: [PATCH] Add caching-related docs to ISocketMessageChannel

---
 .../Channels/ISocketMessageChannel.cs         | 63 +++++++++++++++++--
 1 file changed, 57 insertions(+), 6 deletions(-)

diff --git a/src/Discord.Net.WebSocket/Entities/Channels/ISocketMessageChannel.cs b/src/Discord.Net.WebSocket/Entities/Channels/ISocketMessageChannel.cs
index 9f04239ad..61a70d156 100644
--- a/src/Discord.Net.WebSocket/Entities/Channels/ISocketMessageChannel.cs
+++ b/src/Discord.Net.WebSocket/Entities/Channels/ISocketMessageChannel.cs
@@ -75,16 +75,41 @@ namespace Discord.WebSocket
         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.
+        ///     Gets a cached message from this channel.
         /// </summary>
-        /// <param name="id">The ID of the message.</param>
+        /// <remarks>
+        ///     <note type="warning">
+        ///         This method requires the use of cache, which is not enabled by default; if caching is not enabled,
+        ///         this method will always return <c>null</c>. Please refer to
+        ///         <see cref="Discord.WebSocket.DiscordSocketConfig.MessageCacheSize" /> for more details.
+        ///     </note>
+        ///     <para>
+        ///         This method retrieves the message from the local WebSocket cache and does not send any additional
+        ///         request to Discord. This message may be a message that has been deleted.
+        ///     </para>
+        /// </remarks>
+        /// <param name="id">The snowflake identifier of the message.</param>
         /// <returns>
-        ///     Cached message object; <c>null</c> if it doesn't exist in the cache.
+        ///     A WebSocket-based message object; <c>null</c> if it does not exist in the cache or if caching is not
+        ///     enabled.
         /// </returns>
         SocketMessage GetCachedMessage(ulong id);
         /// <summary>
-        ///     Gets the last N messages from this message channel.
+        ///     Gets the last N cached messages from this message channel.
         /// </summary>
+        /// <remarks>
+        ///     <note type="warning">
+        ///         This method requires the use of cache, which is not enabled by default; if caching is not enabled,
+        ///         this method will always return an empty collection. Please refer to
+        ///         <see cref="Discord.WebSocket.DiscordSocketConfig.MessageCacheSize" /> for more details.
+        ///     </note>
+        ///     <para>
+        ///         This method retrieves the message(s) from the local WebSocket cache and does not send any additional
+        ///         request to Discord. This read-only collection may include messages that have been deleted. The
+        ///         maximum number of messages that can be retrieved from this method depends on the
+        ///         <see cref="Discord.WebSocket.DiscordSocketConfig.MessageCacheSize" /> set.
+        ///     </para>
+        /// </remarks>
         /// <param name="limit">The number of messages to get.</param>
         /// <returns>
         ///     A read-only collection of WebSocket-based messages.
@@ -92,8 +117,21 @@ namespace Discord.WebSocket
         IReadOnlyCollection<SocketMessage> GetCachedMessages(int limit = DiscordConfig.MaxMessagesPerBatch);
 
         /// <summary>
-        ///     Gets a collection of messages in this channel.
+        ///     Gets the last N cached messages starting from a certain message in this message channel.
         /// </summary>
+        /// <remarks>
+        ///     <note type="warning">
+        ///         This method requires the use of cache, which is not enabled by default; if caching is not enabled,
+        ///         this method will always return an empty collection. Please refer to
+        ///         <see cref="Discord.WebSocket.DiscordSocketConfig.MessageCacheSize" /> for more details.
+        ///     </note>
+        ///     <para>
+        ///         This method retrieves the message(s) from the local WebSocket cache and does not send any additional
+        ///         request to Discord. This read-only collection may include messages that have been deleted. The
+        ///         maximum number of messages that can be retrieved from this method depends on the
+        ///         <see cref="Discord.WebSocket.DiscordSocketConfig.MessageCacheSize" /> set.
+        ///     </para>
+        /// </remarks>
         /// <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>
@@ -102,8 +140,21 @@ namespace Discord.WebSocket
         /// </returns>
         IReadOnlyCollection<SocketMessage> GetCachedMessages(ulong fromMessageId, Direction dir, int limit = DiscordConfig.MaxMessagesPerBatch);
         /// <summary>
-        ///     Gets a collection of messages in this channel.
+        ///     Gets the last N cached messages starting from a certain message in this message channel.
         /// </summary>
+        /// <remarks>
+        ///     <note type="warning">
+        ///         This method requires the use of cache, which is not enabled by default; if caching is not enabled,
+        ///         this method will always return an empty collection. Please refer to
+        ///         <see cref="Discord.WebSocket.DiscordSocketConfig.MessageCacheSize" /> for more details.
+        ///     </note>
+        ///     <para>
+        ///         This method retrieves the message(s) from the local WebSocket cache and does not send any additional
+        ///         request to Discord. This read-only collection may include messages that have been deleted. The
+        ///         maximum number of messages that can be retrieved from this method depends on the
+        ///         <see cref="Discord.WebSocket.DiscordSocketConfig.MessageCacheSize" /> set.
+        ///     </para>
+        /// </remarks>
         /// <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>