From 6d75fc47684b0adbbd1265f6f3419e796fbfcd7a Mon Sep 17 00:00:00 2001
From: quin lynch <lynchquin@gmail.com>
Date: Thu, 9 Sep 2021 00:49:09 -0300
Subject: [PATCH] Add docs for ratelimits and fix grammer

---
 docs/guides/concepts/ratelimits.md            | 49 +++++++++++++++++++
 src/Discord.Net.Core/Discord.Net.Core.xml     |  4 +-
 .../Net/Rest/IRateLimitInfo.cs                |  4 +-
 3 files changed, 53 insertions(+), 4 deletions(-)
 create mode 100644 docs/guides/concepts/ratelimits.md

diff --git a/docs/guides/concepts/ratelimits.md b/docs/guides/concepts/ratelimits.md
new file mode 100644
index 000000000..3565f1370
--- /dev/null
+++ b/docs/guides/concepts/ratelimits.md
@@ -0,0 +1,49 @@
+# Ratelimits
+
+Ratelimits are a core concept of the discord api, each verified library must follow the ratelimit guidelines. Labs introduces a ratelimit exposure system to help you follow these ratelimits in your own code.
+
+### Using the ratelimit callback
+
+There is a new property within `RequestOptions` called RatelimitCallback. This callback is called when a request is made via the rest api. The callback is called with a `IRateLimitInfo` parameter:
+
+| Name       | Type            | Description                                                                                                                                        |
+| ---------- | --------------- | -------------------------------------------------------------------------------------------------------------------------------------------------- |
+| IsGlobal   | bool            | Whether or not this ratelimit info is global.                                                                                                      |
+| Limit      | int?            | The number of requests that can be made.                                                                                                           |
+| Remaining  | int?            | The number of remaining requests that can be made.                                                                                                 |
+| RetryAfter | int?            | The total time (in seconds) of when the current rate limit bucket will reset. Can have decimals to match previous millisecond ratelimit precision. |
+| Reset      | DateTimeOffset? | The time at which the rate limit resets.                                                                                                           |
+| ResetAfter | TimeSpan?       | The absolute time when this ratelimit resets.                                                                                                      |
+| Bucket     | string          | A unique string denoting the rate limit being encountered (non-inclusive of major parameters in the route path).                                   |
+| Lag        | TimeSpan?       | The amount of lag for the request. This is used to denote the precise time of when the ratelimit expires.                                          |
+| Endpoint   | string          | The endpoint that this ratelimit info came from.                                                                                                   |
+
+Let's set up a ratelimit callback that will print out the ratelimit info to the console.
+
+```cs
+public async Task MyRatelimitCallback(IRateLimitInfo info)
+{
+    Console.WriteLine($"{info.IsGlobal} {info.Limit} {info.Remaining} {info.RetryAfter} {info.Reset} {info.ResetAfter} {info.Bucket} {info.Lag} {info.Endpoint}");
+}
+```
+
+Let's use this callback in a send message function
+
+```cs
+[Command("ping")]
+public async Task ping()
+{
+    var options = new RequestOptions()
+    {
+        RatelimitCallback = MyRatelimitCallback
+    };
+
+    await Context.Channel.SendMessageAsync("Pong!", options: options);
+}
+```
+
+Running this produces the following output:
+
+```
+False 5 4  2021-09-09 3:48:14 AM +00:00 00:00:05 a06de0de4a08126315431cc0c55ee3dc 00:00:00.9891364 channels/848511736872828929/messages
+```
diff --git a/src/Discord.Net.Core/Discord.Net.Core.xml b/src/Discord.Net.Core/Discord.Net.Core.xml
index c254ad31f..b73b58fb3 100644
--- a/src/Discord.Net.Core/Discord.Net.Core.xml
+++ b/src/Discord.Net.Core/Discord.Net.Core.xml
@@ -11850,12 +11850,12 @@
         </member>
         <member name="P:Discord.IRateLimitInfo.RetryAfter">
             <summary>
-                Gets the total time (in seconds) of when the current rate limit bucket will reset. Can have decimals to match previous millisecond ratelimit precision
+                Gets the total time (in seconds) of when the current rate limit bucket will reset. Can have decimals to match previous millisecond ratelimit precision.
             </summary>
         </member>
         <member name="P:Discord.IRateLimitInfo.Reset">
             <summary>
-                Gets the <see cref="T:System.DateTimeOffset"/> at which the rate limit resets
+                Gets the <see cref="T:System.DateTimeOffset"/> at which the rate limit resets.
             </summary>
         </member>
         <member name="P:Discord.IRateLimitInfo.ResetAfter">
diff --git a/src/Discord.Net.Core/Net/Rest/IRateLimitInfo.cs b/src/Discord.Net.Core/Net/Rest/IRateLimitInfo.cs
index 00d446b10..816f25af4 100644
--- a/src/Discord.Net.Core/Net/Rest/IRateLimitInfo.cs
+++ b/src/Discord.Net.Core/Net/Rest/IRateLimitInfo.cs
@@ -27,12 +27,12 @@ namespace Discord
         int? Remaining { get; }
 
         /// <summary>
-        ///     Gets the total time (in seconds) of when the current rate limit bucket will reset. Can have decimals to match previous millisecond ratelimit precision
+        ///     Gets the total time (in seconds) of when the current rate limit bucket will reset. Can have decimals to match previous millisecond ratelimit precision.
         /// </summary>
         int? RetryAfter { get; }
 
         /// <summary>
-        ///     Gets the <see cref="DateTimeOffset"/> at which the rate limit resets
+        ///     Gets the <see cref="DateTimeOffset"/> at which the rate limit resets.
         /// </summary>
         DateTimeOffset? Reset { get; }