feat docs: more links and cleaner docs for CongestionControl

Tests: на прод не влияет
commit_hash:2d7ff10c527b1ed10120d4803c40d8cd217a6f9e

Author: apolukhin

scripts/docs/en/userver/congestion_control.md

@@ -2,38 +2,48 @@
 
 ## Introduction
 
-congestion_control::Component (aka CC) limits the active requests count. CC has a RPS (request per second) limit mechanism that turns on
-and off automatically depending on the main task processor workload. In case of overload CC responds with HTTP 429 codes to some requests,
-allowing your service to properly process the rest. The RPS limit is determined by a heuristic algorithm inside CC. 
-All the significant parts of the component are configured by dynamic config options USERVER_RPS_CCONTROL and USERVER_RPS_CCONTROL_ENABLED.
+@ref congestion_control::Component (aka CC) limits the active requests count. CC has a RPS (request per second)
+limit mechanism that turns on and off automatically depending on the main task processor workload. In case of overload
+CC responds with HTTP 429 codes to some requests, allowing your service to properly process the rest. The RPS limit
+is determined by a heuristic algorithm inside CC.  All the significant parts of the component are configured
+by dynamic config options @ref USERVER_RPS_CCONTROL and @ref USERVER_RPS_CCONTROL_ENABLED.
 
 CC can run in `fake-mode` with no RPS limit (but FSM works). CC goes into `fake-mode` in the following cases:
 
 * there are no reliable guarantees on CPU, in this case RPS-limit would be triggered too often,
-* service has no HTTP-handles others than server::handlers::Ping.
+* service has no HTTP-handles others than @ref server::handlers::Ping.
 
-`fake-mode` can be useful for more flexible traffic restriction settings, according to it's more complex logic, which can be implemented in a middleware.
+`fake-mode` can be useful for more flexible traffic restriction settings, according to it's more complex logic, which
+can be implemented in a middleware.
 
 ## Usage
 
-congestion_control::Component can be useful if your service stops handling requests when overloaded, significantly increasing response time, responding with HTTP 500 codes to requests, eating memory.
+@ref congestion_control::Component can be useful if your service stops handling requests when overloaded, significantly
+increasing response time, responding with HTTP 500 codes to requests, eating memory.
+
 Including CC in your service will help you handle some reasonable request flow returning HTTP error codes to the rest. 
 
 ### Usage restrictions
 
-congestion_control::Component cannot be useful if:
+@ref congestion_control::Component cannot be useful if:
 
-1. Your service has an exact RPS limit requirement. The heuristic algorithm depends on how much and in what mode the CPU is used in the current container. 
+1. Your service has an exact RPS limit requirement. The heuristic algorithm depends on how much and in what mode the
+   CPU is used in the current container. 
 
 2. CPU is not a limiting resource.
 
-3. Stable response time is not needed. Some services do not need stable response time. They process events in batches which can come at random times. Despite peak overload may be reached there is enough resources to process event flow on average. For example services like PUBSUB subscriber or message broker consumer cannot benefit from a CC component.
+3. Stable response time is not needed. Some services do not need stable response time. They process events in batches
+   which can come at random times. Despite peak overload may be reached there is enough resources to process event flow
+   on average. For example services like PUBSUB subscriber or message broker consumer cannot benefit from a
+   CC component.
 
-4. CPU request processing lasts a considerable time. The RPS limit mechanism assumes that the handler processing time is short and RPC limit change affects CPU workload (seconds or less). If the handler takes a long time to process a request then the feedback will be stalling and maximum RPS convergence is not guaranteed.
+4. CPU request processing lasts a considerable time. The RPS limit mechanism assumes that the handler processing time
+   is short and RPC limit change affects CPU workload (seconds or less). If the handler takes a long time to process
+   a request then the feedback will be stalling and maximum RPS convergence is not guaranteed.
 
 ## Example configuration
 
-1. Add congestion_control::Component in the static config:
+1. Add @ref congestion_control::Component in the static config:
 ```
 # yaml
 components_manager:
@@ -43,11 +53,12 @@ components_manager:
             load-enabled: true
 ```
 
-2. Enable USERVER_RPS_CCONTROL_ENABLED.
+2. Set to `true` the value of @ref USERVER_RPS_CCONTROL_ENABLED dynamic config.
 
-3. Adjust the heuristic settings in USERVER_RPS_CCONTROL if needed.
+3. Adjust the heuristic settings in @ref USERVER_RPS_CCONTROL if needed.
 
-It is a good idea to disable congestion_control::Component in unit tests to avoid getting HTTP 429 on an overloaded CI server.
+It is a good idea to disable @ref congestion_control::Component in unit tests to avoid getting HTTP 429 on an
+overloaded CI server.
 
 ## Settings
 
@@ -59,15 +70,16 @@ In some situations default settings are ineffective. For example:
 
 in those situations congestion_control::Component settings need adjusting. 
 
-Basic configuration files:
+Basic dynamic configuration options:
 
-* USERVER_RPS_CCONTROL_ENABLED - turning CC on and off
+* @ref USERVER_RPS_CCONTROL_ENABLED - turning CC on and off
 
-* USERVER_RPS_CCONTROL - basic CC settings
+* @ref USERVER_RPS_CCONTROL - basic CC settings
 
-* USERVER_TASK_PROCESSOR_QOS - note `default-service.default-task-processor.wait_queue_overload.sensor_time_limit_us`. 
-This setting defines wait in queue time after which the overload events for RPS congestion control are generated. 
-It is recommended to set this setting >= 2000 (2 ms) because system scheduler (CFS) time unit by default equals 2 ms.
+* @ref USERVER_TASK_PROCESSOR_QOS - note
+  `default-service.default-task-processor.wait_queue_overload.sensor_time_limit_us`. 
+  This setting defines wait in queue time after which the overload events for RPS congestion control are generated. 
+  It is recommended to set this setting >= 2000 (2 ms) because system scheduler (CFS) time unit by default equals 2 ms.
 
 ## Diagnostics
 
@@ -83,8 +95,9 @@ Most likely your service has synchronous operations that block the coroutine flo
 
 * Try to find synchronous system calls which block the corountine flow.
 
-* Try to find slow coroutines. To do this you can use coroutine profiling. See the dynamic configuration file USERVER_TASK_PROCESSOR_PROFILER_DEBUG 
-that stores profiling settings. After finding such coroutines you need to locate trouble-making code with log analysis etc.
+* Try to find slow coroutines. To do this you can use coroutine profiling. See the dynamic configuration
+  @ref USERVER_TASK_PROCESSOR_PROFILER_DEBUG that stores profiling settings. After finding such coroutines you need
+  to locate trouble-making code with log analysis etc.
 
 ----------