feat docs: use schemas in core for docs in more cases

Also improve diagnostics for utils::FindResource

Tests: протестировано в CI, проверено локально что все поля отображаются и форматируются приятно для глаза (или хотя бы как было раньше)
commit_hash:1880366a72b980ec3fb3e76658c7454414ca38c5

Author: apolukhin

core/include/userver/cache/caching_component_base.hpp

@@ -31,8 +31,6 @@ USERVER_NAMESPACE_BEGIN
 
 namespace components {
 
-// clang-format off
-
 /// @ingroup userver_components userver_base_classes
 ///
 /// @brief Base class for caching components
@@ -53,30 +51,11 @@ namespace components {
 /// * @ref USERVER_CACHES
 /// * @ref USERVER_DUMPS
 ///
-/// ## Static options:
+/// ## Static options of @ref components::CachingComponentBase :
+/// @include{doc} scripts/docs/en/components_schema/core/src/cache/caching_component_base.md
 ///
-/// Name | Description | Default value
-/// ---- | ----------- | -------------
-/// update-types | specifies whether incremental and/or full updates will be used | see below
-/// update-interval | (*required*) interval between Update invocations | --
-/// update-jitter | max. amount of time by which update-interval may be adjusted for requests dispersal | update_interval / 10
-/// full-update-interval | interval between full updates | --
-/// full-update-jitter | max. amount of time by which full-update-interval may be adjusted for requests dispersal | full-update-interval / 10
-/// updates-enabled | if false, cache updates are disabled (except for the first one if !first-update-fail-ok) | true
-/// first-update-fail-ok | whether first update failure is non-fatal; see also @ref MayReturnNull | false
-/// task-processor | the name of the TaskProcessor for running DoWork | main-task-processor
-/// config-settings | enables dynamic reconfiguration with CacheConfigSet | true
-/// exception-interval | Used instead of `update-interval` in case of exception | update_interval
-/// additional-cleanup-interval | how often to run background RCU garbage collector | 10 seconds
-/// is-strong-period | whether to include Update execution time in update-interval | false
-/// testsuite-force-periodic-update | override testsuite-periodic-update-enabled in TestsuiteSupport component config | --
-/// failed-updates-before-expiration | the number of consecutive failed updates for data expiration | --
-/// has-pre-assign-check | enables the check before changing the value in the cache, by default it is the check that the new value is not empty | false
-/// alert-on-failing-to-update-times | fire an alert if the cache update failed specified amount of times in a row. If zero - alerts are disabled. Value from dynamic config takes priority over static | 0
-/// safe-data-lifetime | enables awaiting data destructors in the component's destructor. Can be set to `false` if the stored data does not refer to the component and its dependencies. | true
-/// dump.* | Manages cache behavior after dump load | -
-/// dump.first-update-mode | Behavior of update after successful load from dump. See info on modes below | skip
-/// dump.first-update-type | Update type after successful load from dump (`full`, `incremental` or `incremental-then-async-full`) | full
+/// Options inherited from @ref components::ComponentBase :
+/// @include{doc} scripts/docs/en/components_schema/core/src/components/impl/component_base.md
 ///
 /// ### Update types
 ///  * `full-and-incremental`: both `update-interval` and `full-update-interval`
@@ -103,7 +82,8 @@ namespace components {
 /// * size of database: 1000 objects
 /// * removal rate: 30 objects per minute (0.5 objects per second)
 ///
-/// Let's say we allow 20% extra garbage objects in cache in addition to the actual objects from the database. In this case we need:
+/// Let's say we allow 20% extra garbage objects in cache in addition to the actual objects from the database. In this
+/// case we need:
 ///
 /// full-update-interval = (size-of-database * 20% / removal-rate) = 400s
 ///
@@ -132,11 +112,11 @@ namespace components {
 ///
 /// Further customizes the behavior of @ref dump::Dumper "cache dumps".
 ///
-/// Mode          | Description
-/// ------------- | -----------
-/// `skip`        | after successful load from dump, do nothing
-/// `required`    | make a synchronous update of type `first-update-type`, stop the service on failure
-/// `best-effort` | make a synchronous update of type `first-update-type`, keep working and use data from dump on failure
+/// Mode        | Description
+/// ----------- | -----------
+/// skip        | after successful load from dump, do nothing
+/// required    | make a synchronous update of type `first-update-type`, stop the service on failure
+/// best-effort | make a synchronous update of type `first-update-type`, keep working and use data from dump on failure
 ///
 /// ### testsuite-force-periodic-update
 ///  use it to enable periodic cache update for a component in testsuite environment
@@ -151,9 +131,6 @@ namespace components {
 ///
 /// @see @ref scripts/docs/en/userver/caches.md. pytest_userver.client.Client.invalidate_caches()
 /// for a function to force cache update from testsuite.
-
-// clang-format on
-
 template <typename T>
 // NOLINTNEXTLINE(fuchsia-multiple-inheritance)
 class CachingComponentBase : public ComponentBase, public cache::DataProvider<T>, protected cache::CacheUpdateTrait {

core/include/userver/cache/lru_cache_component_base.hpp

@@ -38,8 +38,6 @@ yaml_config::Schema GetLruCacheComponentBaseSchema();
 
 }  // namespace impl
 
-// clang-format off
-
 /// @ingroup userver_components userver_base_classes
 ///
 /// @brief Base class for LRU-cache components
@@ -53,14 +51,11 @@ yaml_config::Schema GetLruCacheComponentBaseSchema();
 /// ## LruCacheComponent Dynamic config
 /// * @ref USERVER_LRU_CACHES
 ///
-/// ## Static options:
-/// Name | Description | Default value
-/// ---- | ----------- | -------------
-/// size | max amount of items to store in cache | --
-/// ways | number of ways for associative cache | --
-/// lifetime | TTL for cache entries (0 is unlimited) | 0
-/// background-update | enables asynchronous updates for expiring values | false
-/// config-settings | enables dynamic reconfiguration with CacheConfigSet | true
+/// ## Static options of @ref cache::LruCacheComponent :
+/// @include{doc} scripts/docs/en/components_schema/core/src/cache/lru_cache_component_base.md
+///
+/// Options inherited from @ref components::ComponentBase :
+/// @include{doc} scripts/docs/en/components_schema/core/src/components/impl/component_base.md
 ///
 /// ## Example usage:
 ///
@@ -71,8 +66,6 @@ yaml_config::Schema GetLruCacheComponentBaseSchema();
 ///
 /// ## Example config:
 /// @snippet cache/lru_cache_component_base_test.cpp  Sample lru cache component config
-
-// clang-format on
 template <typename Key, typename Value, typename Hash = std::hash<Key>, typename Equal = std::equal_to<Key>>
 // NOLINTNEXTLINE(fuchsia-multiple-inheritance)
 class LruCacheComponent : public components::ComponentBase, private dump::DumpableEntity {

core/include/userver/clients/http/component.hpp

@@ -15,8 +15,6 @@ USERVER_NAMESPACE_BEGIN
 
 namespace components {
 
-// clang-format off
-
 /// @ingroup userver_components
 ///
 /// @brief Component that manages @ref clients::http::ClientWithPlugins.
@@ -27,17 +25,15 @@ namespace components {
 /// Returned references to @ref clients::http::Client live for a lifetime of the
 /// component and are safe for concurrent use.
 ///
-/// ## Static options:
-/// Name | Description | Default value
-/// ---- | ----------- | -------------
-/// core-component | name of components::HttpClientCore component to use | 'http-client-core'
-/// plugins | map of plugins to apply, plugin-name -> ordering index. A plugin component is called "http-client-plugin-" plus the plugin name. | {}
+/// ## Static options of @ref components::HttpClient :
+/// @include{doc} scripts/docs/en/components_schema/core/src/clients/http/component.md
+///
+/// Options inherited from @ref components::ComponentBase :
+/// @include{doc} scripts/docs/en/components_schema/core/src/components/impl/component_base.md
 ///
 /// ## Static configuration example:
 ///
 /// @snippet components/common_component_list_test.cpp  Sample http client component config
-
-// clang-format on
 class HttpClient final : public ComponentBase {
 public:
     /// @ingroup userver_component_names

core/include/userver/clients/http/component_core.hpp

@@ -35,21 +35,11 @@ namespace components {
 /// * @ref HTTP_CLIENT_CONNECT_THROTTLE
 /// * @ref HTTP_CLIENT_CONNECTION_POOL_SIZE
 ///
-/// ## Static options:
-/// Name | Description | Default value
-/// ---- | ----------- | -------------
-/// pool-statistics-disable | set to true to disable statistics for connection pool | false
-/// thread-name-prefix | set OS thread name to this value | ''
-/// threads | number of threads to process low level HTTP related IO system calls | 8
-/// fs-task-processor | task processor to run blocking HTTP related calls, like DNS resolving or hosts reading | engine::current_task::GetBlockingTaskProcessor()
-/// destination-metrics-auto-max-size | set max number of automatically created destination metrics | 100
-/// user-agent | User-Agent HTTP header to show on all requests, result of utils::GetUserverIdentifier() if empty | empty
-/// testsuite-enabled | enable testsuite testing support | false
-/// testsuite-timeout | if set, force the request timeout regardless of the value passed in code | -
-/// testsuite-allowed-url-prefixes | if set, checks that all URLs start with any of the passed prefixes, asserts if not. Set for testing purposes only. | ''
-/// dns_resolver | server hostname resolver type (getaddrinfo or async) | 'async'
-/// set-deadline-propagation-header | whether to set http::common::kXYaTaxiClientTimeoutMs request header, see @ref scripts/docs/en/userver/deadline_propagation.md | true
-/// cancellation-policy | Cancellation policy for new requests. | cancel
+/// ## Static options @ref components::HttpClientCore :
+/// @include{doc} scripts/docs/en/components_schema/core/src/clients/http/component_core.md
+///
+/// Options inherited from @ref components::ComponentBase :
+/// @include{doc} scripts/docs/en/components_schema/core/src/components/impl/component_base.md
 ///
 /// ## Static configuration example:
 ///

core/src/cache/caching_component_base.yaml

@@ -33,6 +33,7 @@ properties:
     exception-interval:
         type: string
         description: sleep interval after an unhandled exception
+        defaultDescription: update_interval
     first-update-fail-ok:
         type: boolean
         description: whether first update failure is non-fatal
@@ -103,6 +104,7 @@ properties:
                   - skip
                   - required
                   - best-effort
+                defaultDescription: skip
             first-update-type:
                 type: string
                 description: |

core/src/clients/http/component.yaml

@@ -4,11 +4,12 @@ additionalProperties: false
 properties:
     core-component:
         type: string
-        description: name of HttpClientCore component to use
+        description: name of components::HttpClientCore component to use
         defaultDescription: http-client-core
     plugins:
         type: object
-        description: HTTP client plugins
+        description: map of plugins to apply, plugin-name -> ordering index. A plugin
+            component is called "http-client-plugin-" plus the plugin name.
         properties: {}
         additionalProperties:
             type: integer

core/src/clients/http/component_core.yaml

@@ -28,7 +28,7 @@ properties:
         type: string
         description: User-Agent HTTP header to show on all requests, result of utils::GetUserverIdentifier()
             if empty
-        defaultDescription: empty
+        defaultDescription: ''
     testsuite-enabled:
         type: boolean
         description: enable testsuite testing support
@@ -46,7 +46,7 @@ properties:
             description: URL prefix
     dns_resolver:
         type: string
-        description: server hostname resolver type (getaddrinfo or async)
+        description: server hostname resolver type
         defaultDescription: 'async'
         enum:
           - getaddrinfo
@@ -65,3 +65,4 @@ properties:
         enum:
           - cancel
           - ignore
+        defaultDescription: 'cancel'

scripts/docs/components_schema_to_table.py

@@ -3,13 +3,14 @@
 import argparse
 import os
 import pathlib
+from typing import Any
 
 import yaml
 
 USERVER_ROOT = pathlib.Path(__file__).parent.parent.parent
 
 
-def normalize_default_value(data) -> str:
+def normalize_default_value(data: Any) -> str:
     if data is True:
         return 'true'
     elif data is False:
@@ -18,24 +19,35 @@ def normalize_default_value(data) -> str:
         return data
 
 
-def merge_descriptions(yaml, other):
-    if yaml.get('description') and other.get('description'):
-        description = yaml['description'].strip()
+def merge_descriptions(yaml_node: dict, other: dict) -> dict:
+    if yaml_node.get('description') and other.get('description'):
+        description = yaml_node['description'].strip()
+        description = f'{description[0].upper()}{description[1:]}'
         if not description.endswith('.'):
             description += '.'
         description += ' <i>Each of the elements:</i> ' + other['description']
 
-        value_merged = yaml.copy()
+        value_merged = yaml_node.copy()
         value_merged['description'] = description
         return value_merged
-    elif yaml.get('description'):
-        return yaml
+    elif yaml_node.get('description'):
+        return yaml_node
     else:
         return other
 
 
-def visit_object(yaml, prefix: str = ''):
-    properties = yaml.get('properties', {})
+def enrich_description(yaml_node: dict) -> str:
+    description = yaml_node['description'].replace('\n', ' ').strip()
+    description = f'{description[0].upper()}{description[1:]}'
+    if not description.endswith('.'):
+        description += '.'
+    if enum := yaml_node.get('enum'):
+        description += ' <i>Possible values:</i> ' + ', '.join(str(x) for x in enum) + '.'
+    return description
+
+
+def visit_object(yaml_node: dict, prefix: str = ''):
+    properties = yaml_node.get('properties', {})
 
     for key, value in properties.items():
         if value.get('type') == 'array':
@@ -49,37 +61,37 @@ def visit_object(yaml, prefix: str = ''):
         else:
             yield (prefix + key, value)
 
-    additionals = yaml.get('additionalProperties')
+    additionals = yaml_node.get('additionalProperties')
     if additionals is True:
-        yield (prefix + '*', yaml)
+        yield (prefix + '*', yaml_node)
     elif not additionals:
         return
     elif additionals.get('type') == 'object':
-        yield from visit_object(yaml['additionalProperties'], prefix + '*.')
+        yield from visit_object(yaml_node['additionalProperties'], prefix + '*.')
     elif additionals.get('type') == 'array':
-        value_merged = merge_descriptions(yaml, additionals['items'])
+        value_merged = merge_descriptions(yaml_node, additionals['items'])
         yield (prefix + '*.[]', value_merged)
     else:
-        value_merged = merge_descriptions(yaml, additionals)
+        value_merged = merge_descriptions(yaml_node, additionals)
         yield (prefix + '*', value_merged)
 
 
-def format_schema(yaml) -> str:
+def format_schema(yaml_node: Any) -> str:
     result = ''
-    key_values = list(visit_object(yaml))
+    key_values = list(visit_object(yaml_node))
     if not key_values:
         result += 'No options'
         return result
 
     max_key_size = max(len(key) for key, _ in key_values)
-    max_value_size = max(len(value['description']) for _, value in key_values)
+    max_value_size = max(len(enrich_description(value)) for _, value in key_values)
 
     result += f'{"Name":{max_key_size}} | {"Description":{max_value_size}} | Default value\n'
     result += f'{"":-<{max_key_size}} | {"":-<{max_value_size}} | {"":-<16}\n'
 
     for key, value in key_values:
         key = key.replace('\n', ' ')
-        description = value['description'].replace('\n', ' ')
+        description = enrich_description(value)
         default = normalize_default_value(value.get('defaultDescription', '--'))
         result += f'{key:{max_key_size}} | {description:{max_value_size}} | {default}\n'
 
@@ -93,7 +105,7 @@ def parse_args():
     return parser.parse_args()
 
 
-def handle_file(ifname: pathlib.Path, output_dir: pathlib.Path):
+def handle_file(ifname: pathlib.Path, output_dir: pathlib.Path) -> None:
     with open(ifname) as ifile:
         content = yaml.load(ifile.read(), yaml.Loader)
 

universal/include/userver/utils/resources.hpp

@@ -9,8 +9,11 @@ USERVER_NAMESPACE_BEGIN
 
 namespace utils {
 
+/// Registeres a resource; used by `userver_embed_file` CMake function
 void RegisterResource(std::string_view name, std::string_view value);
 
+/// Returns a resource by name, registered by `userver_embed_file` CMake function (or RESOURCE() macro in some
+/// other build systems)
 std::string FindResource(std::string_view name);
 
 }  // namespace utils

universal/src/utils/resources.cpp

@@ -1,5 +1,8 @@
 #include <userver/utils/resources.hpp>
 
+#include <fmt/format.h>
+
+#include <stdexcept>
 #include <unordered_map>
 
 #if __has_include(<library/cpp/resource/resource.h>)
@@ -19,11 +22,15 @@ std::unordered_map<std::string_view, std::string_view>& Resources() {
 void RegisterResource(std::string_view name, std::string_view value) { Resources().emplace(name, value); }
 
 std::string FindResource(std::string_view name) {
+    try {
 #ifdef ARCADIA
-    return NResource::Find(name);
+        return NResource::Find(name);
 #else
-    return std::string{Resources().at(name)};
+        return std::string{Resources().at(name)};
 #endif
+    } catch (const std::exception& e) {
+        throw std::runtime_error(fmt::format("Failed to locate resource with name '{}': {}", name, e.what()));
+    }
 }
 
 }  // namespace utils