feat docs: add explicit references to seome entities and update S3API tier

Some of the missing `@ref` were added via `find . -type f | xargs sed -i 's/\([^f#@ ]\) \([a-rtv-z]*\)::/\1 @ref \2::/g` script

Tests: протестировано локально
commit_hash:87fafd9f53204f5173dcc103d6ec1089957900c2

Author: apolukhin

samples/chaotic_openapi_service/testsuite/test_hello.py

@@ -10,10 +10,12 @@ async def call(service_client):
 
 
 async def test_hello_base(service_client, mockserver, dynamic_config):
+    # /// [Functional test]
     @mockserver.handler('test/test')
     def test(request):
         assert request.query['name'] == 'john'
         return mockserver.make_response('"tost"')
+        # /// [Functional test]
 
     p = await call(service_client)
     assert p['http.request.max_resend_count'] == '1'

scripts/docs/en/userver/cache_dumps.md

@@ -8,12 +8,10 @@ and skips the synchronous `Update`.
 Advantages:
 - Faster service start: the service no longer waits for the first synchronous
   `Update` that may query a database or make some other network requests.
-- Better fault tolerance: the service now boots successfully even if the first
-  update fails.
+- Better fault tolerance: the service now boots successfully even if the first update fails.
 
 Disadvantages:
-- CPU time is spent on periodic serialization of data and writing to the dump
-  file.
+- CPU time is spent on periodic serialization of data and writing to the dump file.
 - Disk accesses consume the IO quota, which can negatively affect other disk
   users (for example, logging or other caches).
 
@@ -56,8 +54,7 @@ In order for a data type to be serialized for cache dumps the `Write` and
     * Integers, floats, doubles, strings, `std::chrono`, `enum`, `uuid` in
       `<userver/dump/common.hpp>`
     * C++ Standard Library and Boost containers, `std::optional`,
-      `utils::StrongTypedef`, `std::{unique,shared}_ptr` in
-      `<userver/dump/common_containers.hpp>`
+      `utils::StrongTypedef`, `std::{unique,shared}_ptr` in `<userver/dump/common_containers.hpp>`
     * Protobuf messages in `<userver/dump/protobuf.hpp>`
     * Trivial structures (aggregates) in `<userver/dump/aggregates.hpp>`, but
       you will have to enable dumps manually:

scripts/docs/en/userver/caches.md

@@ -11,17 +11,16 @@ in the background and do not block users from working with the cache.
 As a result, the user usually works with slightly outdated data, but at the same
 time always has an instant access to some version of the data.
 
-Caches usually inherit from components::CachingComponentBase or
-cache::LruCacheComponent. Sections below describe the features of
-components::CachingComponentBase. For information on cache::LruCacheComponent
+Caches usually inherit from @ref components::CachingComponentBase or
+@ref cache::LruCacheComponent. Sections below describe the features of
+@ref components::CachingComponentBase. For information on @ref cache::LruCacheComponent
 refer to @ref scripts/docs/en/userver/lru_cache.md.
 
 
 ## Update Modes
 
 Caches have two update modes:
-* Full update. In this mode, the cache requests its full state from an external
-  resource.
+* Full update. In this mode, the cache requests its full state from an external resource.
 * Incremental update. In this mode, the cache requests changes since the last
   Full update, patching its current state.
 
@@ -59,8 +58,7 @@ yaml
 `update-interval` is the time interval between the `Update` calls.
 In particular this means:
 - `Update` is not called concurrently
-- Only with `update-jitter: 0s` and `is-strong-period: true` updates follow a
-  strict schedule.
+- Only with `update-jitter: 0s` and `is-strong-period: true` updates follow a strict schedule.
 
 `full-update-interval` is the minimum interval between `full` updates in
 `full-and-incremental` cache. With each update, the cache checks if 
@@ -159,16 +157,16 @@ cluster increases, which is why the consumed by caches CPU fraction increases.
 **The second option**. Add context switching. If you call
 engine::Yield() every 1-2ms, then the framework engine has time to execute the
 other ready for execution coroutines and the queue of ready coroutines does not
-grow to undesirable values. To simplify working with engine::Yield, it is
-recommended to use utils::CpuRelax rather than calling engine::Yield() manually.
+grow to undesirable values. To simplify working with @ref engine::Yield, it is
+recommended to use utils::CpuRelax rather than calling @ref engine::Yield() manually.
 
 ## Specializations for DB
 
 Caches over DB are caching components that use a trait structure as a
 template argument for customization. Such components are:
 
-- components::MongoCache
-- components::PostgreCache
+- @ref components::MongoCache
+- @ref components::PostgreCache
 
 A typical case of cache usage consists of trait structure definition:
 
@@ -183,7 +181,7 @@ The DB caches are simple to use and quite poverfull.
 ## Writing a cache
 
 To write your own cache using only the components::CachingComponentBase base
-class, you need to override the cache::CacheUpdateTrait::Update,
+class, you need to override the @ref cache::CacheUpdateTrait::Update,
 implement Full and Incremental updates. In Update(), don't forget to put down
 metrics for the `stats_scope` object, describing how many objects were read,
 how many parsing errors there were, and how many elements are in the final cache.

scripts/docs/en/userver/component_system.md

@@ -72,15 +72,15 @@ class ComponentA: components::ComponentBase {
 ```
 
 Only components should know about components. Clients and other types
-constructed by components should not use components::ComponentConfig,
-components::ComponentContext, or components directly. All the components
-should inherit from components::ComponentBase base class and may
+constructed by components should not use @ref components::ComponentConfig,
+@ref components::ComponentContext, or components directly. All the components
+should inherit from @ref components::ComponentBase base class and may
 override its methods.
 
 All the components are listed at the @ref userver_components API Group.
 
 ## Startup context
-On component construction a components::ComponentContext is passed as a
+On component construction a @ref components::ComponentContext is passed as a
 second parameter to the constructor of the component. That context could
 be used to get references to other components. That reference to the
 component is guaranteed to outlive the component that is being constructed.
@@ -89,32 +89,30 @@ component is guaranteed to outlive the component that is being constructed.
 Please see docs on @ref components::ServiceLifetimeStage.
 
 ## Components construction and destruction order
-utils::DaemonMain, components::Run or components::RunOnce
-start all the components from the passed components::ComponentList.
-Each component is constructed in a separate engine::Task on the default
+@ref utils::DaemonMain, @ref components::Run or @ref components::RunOnce
+start all the components from the passed @ref components::ComponentList.
+Each component is constructed in a separate @ref engine::Task on the default
 task processor and is initialized concurrently with other components.
 
 This is a useful feature, for example in cases
 with multiple caches that slowly read from different databases.
 
 To make component *A* depend on component *B* just call
-components::ComponentContext::FindComponent<B>() in the constructor of A.
+@ref components::ComponentContext::FindComponent<B>() in the constructor of A.
 FindComponent() suspends the current task and continues only after the
 construction of component B is finished. Components are destroyed
 in reverse order of construction, so the component A is destroyed before
 the component B. In other words - references from FindComponent() outlive
 the component that called the FindComponent() function. If any component
 loading fails, FindComponent() wakes up and throws an
-components::ComponentsLoadCancelledException.
+@ref components::ComponentsLoadCancelledException.
 
 @anchor clients_from_components_lifetime
 ## References from components and lifetime of clients
-It is a common practice to have a component that returns a reference *R* from
-some function *F*. In such cases:
+It is a common practice to have a component that returns a reference *R* from some function *F*. In such cases:
 * a reference *R* lives as long as the component is alive
 * a reference *R* is usually a client 
-* and it is safe to invoke member functions of reference *R* concurrently
-  unless otherwise specified.
+* and it is safe to invoke member functions of reference *R* concurrently unless otherwise specified.
 
 Examples:
 * components::HttpClient::GetHttpClient()
@@ -123,17 +121,17 @@ Examples:
 ## Components static configuration
 components::ManagerControllerComponent configures the engine internals from
 information provided in its static config: preallocates coroutines, creates
-the engine::TaskProcessor, creates threads for low-level event processing.
+the @ref engine::TaskProcessor, creates threads for low-level event processing.
 After that it starts all the components that
 were added to the components::ComponentList. Each registered component
 should have a section in service config (also known as static config).
 
 The component configuration is passed as a first parameter of type
-components::ComponentConfig to the constructor of the component. Note that
-components::ComponentConfig extends the functionality of
-yaml_config::YamlConfig with YamlConfig::Mode::kEnvAllowed mode
+@ref components::ComponentConfig to the constructor of the component. Note that
+@ref components::ComponentConfig extends the functionality of
+@ref yaml_config::YamlConfig with @ref YamlConfig::Mode::kEnvAllowed mode
 that is able to substitute variables with values, use environment variales and
-fallbacks. See yaml_config::YamlConfig for more info and examples.
+fallbacks. See @ref yaml_config::YamlConfig for more info and examples.
 
 All the components have the following options:
 
@@ -197,13 +195,12 @@ the component.
 You need a component if:
 * you need a static config
 * you need to work with other components
-* you are writing clients (you need a component to be the factory for your
-clients)
+* you are writing clients (you need a component to be the factory for your clients)
 * you want to subscribe for configs or cache changes
 
 ### HowTo
 Start writing your component from adding a header file with a class
-inherited from components::ComponentBase.
+inherited from @ref components::ComponentBase.
 @snippet components/component_sample_test.hpp  Sample user component header
 
 In source file write the implementation of the component:
@@ -218,9 +215,9 @@ If you need dynamic configs, you can get them using this approach:
 @note See @ref scripts/docs/en/userver/tutorial/config_service.md for info on how to
 implement your own config server.
 
-Do not forget to register your component in components::ComponentList
-before invoking the utils::DaemonMain, components::Run or
-components::RunOnce.
+Do not forget to register your component in @ref components::ComponentList
+before invoking the @ref utils::DaemonMain, @ref components::Run or
+@ref components::RunOnce.
 
 Done! You've implemented your first component. Full sources:
 * @ref components/component_sample_test.hpp

scripts/docs/en/userver/deadline_propagation.md

@@ -140,16 +140,16 @@ support deadline propagation.
 ### Blocking the deadline propagation
 
 Task-inherited deadline is by default propagated from the handler task to child tasks created via `utils::*Async*`.
-There it is used in all clients that support it. This is implemented via `server::request::kTaskInheritedData`
-and `server::request::GetTaskInheritedDeadline`.
+There it is used in all clients that support it. This is implemented via @ref server::request::kTaskInheritedData
+and @ref server::request::GetTaskInheritedDeadline.
 
 In _background tasks_ that are started from the task of the request, but do not affect its completion, the deadline
 should not be propagated from the request tasks. Blocking such deadline propagation can be achieved by the following
 mechanisms:
 
-- `concurrent::BackgroundTaskStorage::AsyncDetach`
-- `utils::AsyncBackground`
-- `engine::AsyncNoSpan` (don't use it if you are not sure that you need it!)
+- @ref concurrent::BackgroundTaskStorage::AsyncDetach()
+- @ref utils::AsyncBackground
+- @ref engine::AsyncNoSpan (don't use it if you are not sure that you need it!)
 
 @warning when creating background tasks via `utils::Async` (instead of `utils::AsyncBackground`), requests performed
 in them will be interrupted along with the parent task**
@@ -181,7 +181,7 @@ Metrics:
 * `cancelled-by-deadline` (monotonic counter) - counts requests the handling of which was cancelled by deadline
   (deadline expired by the end of handling, or some operation estimated that the deadline would surely expire).
 
-Log tags of the request's `tracing::Span`:
+Log tags of the request's @ref tracing::Span :
 
 * `deadline_received_ms=...` if the calling service has set a deadline for the request
 * if deadline expired while handling the request:

scripts/docs/en/userver/development/releases.md

@@ -40,7 +40,7 @@ snapshots of the `develop` sources with
 Releases do not evolve, all the new functionality and bugfixes go to
 develop branch of git to become a new release some day.
 
-Starting from userver 2.0 we do a new minor release monthly.
+Starting from userver 2.0 we do a new minor release once in a month or two.
 
 
 ## Issue, feature and pull requests (PR)

scripts/docs/en/userver/development/stability.md

@@ -60,10 +60,8 @@ less popular.
 
 There are tiers to differentiate technologies:
 
-* **Platinum Tier** - driver is known to be used in multiple high load critical
-  to uptime services in huge companies.
-* **Golden Tier** - driver that has not enough usage
-  feedback from huge companies. Still fine for production usage.
+* **Platinum Tier** - driver is known to be used in multiple high load critical to uptime services in huge companies.
+* **Golden Tier** - driver that has not enough usage feedback from huge companies. Still fine for production usage.
 * **Silver Tier** - early days of the driver. It passes all the tests and works
   fine, but more feedback/time required to become a Golden Tier driver. Fine
   for prototyping and production usage with some caution.

scripts/docs/en/userver/driver_guide.md

@@ -42,7 +42,7 @@ in userver.
 Otherwise, if the native driver is written in C++ and is not too big, then
 it may be possible to patch it to use userver IO primitives
 (engine::io::Socket, for example) and cleaning out other blocking primitives
-in favor of userver ones (engine::Mutex, engine::ConditionVariable). This
+in favor of userver ones (engine::Mutex, @ref engine::ConditionVariable). This
 approach was used to write the Clickhouse driver in userver.
 
 In both approaches there is a downside. The native library must be integrated
@@ -56,7 +56,7 @@ Implement the protocol yourself (probably reusing a subset of the native
 library functionality).  This approach was used to write the PostgreSQL driver
 in userver - it creates a
 connection in a separate `TaskProcessor` via native functions, and then
-subscribes to the socket via engine::io::Socket, parses the protocol in the
+subscribes to the socket via @ref engine::io::Socket, parses the protocol in the
 main `TaskProcessor`.
 
 Such an approach may open the door for further optimizations. If no native

scripts/docs/en/userver/faq.md

@@ -51,7 +51,7 @@ Otherwise, there could be enough information to reproduce the problem.
   a `noexcept` function. See the trace for the place where that happened and add
   `try`+`catch` block in your sources, to catch and print the exception that
   is thrown.
-* Take a closer look at the utils::Async and engine::AsyncNoSpan usage in
+* Take a closer look at the utils::Async and @ref engine::AsyncNoSpan usage in
   your code. Captured by reference variables in lambdas should outlive the
   returned task.
 

scripts/docs/en/userver/grpc/grpc.md

@@ -19,7 +19,7 @@ See also:
 * Creating asynchronous gRPC clients and services;
 * Forwarding gRPC Core logs to userver logs;
 * Caching and reusing connections;
-* @ref scripts/docs/en/userver/grpc/grpc_retries.md;
+* @ref scripts/docs/en/userver/grpc/timeouts_retries.md;
 * Collection of metrics on driver usage;
 * Cancellation support;
 * Automatic authentication using middlewares;
@@ -53,7 +53,7 @@ In a component constructor, find @ref ugrpc::client::ClientFactoryComponent and
 
 Client creation in an expensive operation! Either create them once at the server boot time or cache them. An automated
 solution for client creation and caching is the @ref ugrpc::client::SimpleClientComponent. It also allows to
-specify dynamic config for @ref ugrpc::client::ClientQos:
+specify dynamic config for @ref ugrpc::client::ClientQos :
 
 @snippet samples/grpc_service/src/greeter_client.hpp  component