Provide better documentation

[payne911]

trafficstars

There are only 2 utility functions (onRateLimit and onSecondaryRateLimit) to define to use this library, yet they remain relatively cryptic despite the example provided in the README.

• What is the relationship between those 2 functions?
• When are those 2 functions respectively called?
• How does the returned value affect their execution?
• What are all the "sub-parameters" of the options parameter?
• Which of those parameters have default values, and what are those values?

Currently, it seems like I can mostly only imply these:

1. onRateLimit will execute a retry if it returns true (but what about false? and what onSecondaryRateLimit?)
2. retryAfter uses the seconds as its time unit (why not include that information directly in the variable name? as per its name, this could even be interpreted as being a boolean we could use to trigger yet another retry)
3. retryCount is a counter which starts at 0 and gets incremented by 1 after onRateLimit is called
4. options contains at least 2 values: url and method (but what even is method?)

There is already #76 but it seems to mostly relate to GHE (and it's been open for so long anyways). Personally, I built a tool that extensively relies on plugin-throttling and I would assume most of my users are non-GHE, so I'm creating this issue to hopefully cover my case as well.

[payne911]

As per a recent PR, this doc link already provides a bit more info: https://octokit.github.io/rest.js/v19#throttling

Maybe it should be somehow integrated in the README.

[hoshsadiq]

Just ran into this as well, some additional information on this that might help understand at least some of your question can be found on the GH docs.

[wolfy1339]

I recently added some more type information to the onRateLimit and onSecondaryRateLimit, and internal functions.

That should satisfy the needs for the options parameter.

The method key of the options parameter is the HTTP method of the request, ie POST

As mentioned, this all relates to the GitHub docs, https://docs.github.com/en/rest/overview/rate-limits-for-the-rest-api?apiVersion=2022-11-28