Explain the rate limiting mechanism in the docs

[HarHarLinks]

The code has this very comprehensive docstring explaining the mechanism really well.

synapse/synapse/api/ratelimiting.py

Lines 33 to 69 in 57efc8c

	class Ratelimiter:
	"""
	Ratelimit actions marked by arbitrary keys.
	(Note that the source code speaks of "actions" and "burst_count" rather than
	"tokens" and a "bucket_size".)
	This is a "leaky bucket as a meter". For each key to be tracked there is a bucket
	containing some number 0 <= T <= `burst_count` of tokens corresponding to previously
	permitted requests for that key. Each bucket starts empty, and gradually leaks
	tokens at a rate of `rate_hz`.
	Upon an incoming request, we must determine:
	- the key that this request falls under (which bucket to inspect), and
	- the cost C of this request in tokens.
	Then, if there is room in the bucket for C tokens (T + C <= `burst_count`),
	the request is permitted and `cost` tokens are added to the bucket.
	Otherwise, the request is denied, and the bucket continues to hold T tokens.
	This means that the limiter enforces an average request frequency of `rate_hz`,
	while accumulating a buffer of up to `burst_count` requests which can be consumed
	instantaneously.
	The tricky bit is the leaking. We do not want to have a periodic process which
	leaks every bucket! Instead, we track
	- the time point when the bucket was last completely empty, and
	- how many tokens have added to the bucket permitted since then.
	Then for each incoming request, we can calculate how many tokens have leaked
	since this time point, and use that to decide if we should accept or reject the
	request.
	Args:
	store: The datastore providing get_ratelimit_for_user.
	clock: A homeserver clock, for retrieving the current time
	cfg: The ratelimit configuration for this rate limiter including the
	allowed rate and burst count.
	"""

Meanwhile, the docs for admins who are supposed to understand how to configure these settings, are completely devoid of an explanation of how the burst works.

synapse/docs/usage/configuration/config_documentation.md

Lines 1637 to 1643 in 57efc8c

	## Ratelimiting
	Options related to ratelimiting in Synapse.
	Each ratelimiting configuration is made of two parameters:
	- `per_second`: number of requests a client can send per second.
	- `burst_count`: number of requests a client can send before being throttled.
	---

I think this could well be resolved by copying the relevant half from the docstring to the docs.