Skip to content

Commit 91f82ae

Browse files
apolukhinapolukhin
committed
feat docs: use schemas in core for docs in more cases
Tests: протестировано в CI, проверено локально что все поля отображаются и форматируются приятно для глаза (или хотя бы как было раньше) commit_hash:11acc32e14d18a2e6f15fe8b53e6870744038722
1 parent efce0f8 commit 91f82ae

File tree

19 files changed

+111
-177
lines changed

19 files changed

+111
-177
lines changed

‎core/include/userver/components/dump_configurator.hpp‎

Lines changed: 9 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,8 @@
11
#pragma once
22

3+
/// @file userver/components/dump_configurator.hpp
4+
/// @brief @copybrief components::DumpConfigurator
5+
36
#include <string>
47

58
#include <userver/components/component_base.hpp>
@@ -9,28 +12,25 @@ USERVER_NAMESPACE_BEGIN
912

1013
namespace components {
1114

12-
// clang-format off
13-
1415
/// @ingroup userver_components
1516
///
1617
/// @brief Helper component that manages common configuration for userver dumps.
1718
///
1819
/// The component must be configured in service config.
1920
///
20-
/// ## Static options:
21-
/// Name | Description | Default value
22-
/// ---- | ----------- | -------------
23-
/// dump-root | Components store dumps in subdirectories of this directory | -
21+
/// ## Static options of @ref components::DumpConfigurator :
22+
/// @include{doc} scripts/docs/en/components_schema/core/src/components/dump_configurator.md
23+
///
24+
/// Options inherited from @ref components::ComponentBase :
25+
/// @include{doc} scripts/docs/en/components_schema/core/src/components/impl/component_base.md
2426
///
2527
/// ## Config example:
2628
///
2729
/// @snippet components/common_component_list_test.cpp Sample dump configurator component config
28-
29-
// clang-format on
3030
class DumpConfigurator final : public ComponentBase {
3131
public:
3232
/// @ingroup userver_component_names
33-
/// @brief The default name of components::DumpConfigurator component
33+
/// @brief The default name of @ref components::DumpConfigurator component
3434
static constexpr std::string_view kName = "dump-configurator";
3535

3636
DumpConfigurator(const ComponentConfig& config, const ComponentContext& context);

‎core/include/userver/components/fs_cache.hpp‎

Lines changed: 5 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -11,21 +11,15 @@ USERVER_NAMESPACE_BEGIN
1111

1212
namespace components {
1313

14-
// clang-format off
15-
1614
/// @ingroup userver_components
1715
///
1816
/// @brief Component for storing files in memory
19-
/// ## Static options:
2017
///
21-
/// Name | Description | Default value
22-
/// ----------------- | ---------------------------------------------------- | -------------
23-
/// dir | directory to cache files from   | /var/www
24-
/// update-period | Update period (0 - fill the cache only at startup) | 0
25-
/// fs-task-processor | task processor to do filesystem operations | engine::current_task::GetBlockingTaskProcessor()
26-
27-
// clang-format on
28-
18+
/// ## Static options of @ref components::FsCache :
19+
/// @include{doc} scripts/docs/en/components_schema/core/src/components/fs_cache.md
20+
///
21+
/// Options inherited from @ref components::ComponentBase :
22+
/// @include{doc} scripts/docs/en/components_schema/core/src/components/impl/component_base.md
2923
class FsCache final : public components::ComponentBase {
3024
public:
3125
using Client = fs::FsCacheClient;

‎core/include/userver/components/logging_configurator.hpp‎

Lines changed: 6 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -18,8 +18,6 @@ struct DynamicDebugConfig;
1818

1919
namespace components {
2020

21-
// clang-format off
22-
2321
/// @ingroup userver_components
2422
///
2523
/// @brief Helper component to configure logging.
@@ -31,21 +29,19 @@ namespace components {
3129
/// * @ref USERVER_LOG_DYNAMIC_DEBUG
3230
/// * @ref USERVER_NO_LOG_SPANS
3331
///
34-
/// ## Static options:
35-
/// Name | Description | Default value
36-
/// ---- | ----------- | -------------
37-
/// limited-logging-enable | set to true to make LOG_LIMITED drop repeated logs | -
38-
/// limited-logging-interval | utils::StringToDuration suitable duration string to group repeated logs into one message | -
32+
/// ## Static options of @ref components::LoggingConfigurator :
33+
/// @include{doc} scripts/docs/en/components_schema/core/src/components/logging_configurator.md
34+
///
35+
/// Options inherited from @ref components::ComponentBase :
36+
/// @include{doc} scripts/docs/en/components_schema/core/src/components/impl/component_base.md
3937
///
4038
/// ## Config example:
4139
///
4240
/// @snippet components/common_component_list_test.cpp Sample logging configurator component config
43-
44-
// clang-format on
4541
class LoggingConfigurator final : public RawComponentBase {
4642
public:
4743
/// @ingroup userver_component_names
48-
/// @brief The default name of components::LoggingConfigurator component
44+
/// @brief The default name of @ref components::LoggingConfigurator component
4945
static constexpr std::string_view kName = "logging-configurator";
5046

5147
LoggingConfigurator(const ComponentConfig& config, const ComponentContext& context);

‎core/include/userver/components/process_starter.hpp‎

Lines changed: 6 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -11,22 +11,19 @@ USERVER_NAMESPACE_BEGIN
1111

1212
namespace components {
1313

14-
// clang-format off
15-
1614
/// @ingroup userver_components
1715
///
1816
/// @brief Component for getting the engine::subprocess::ProcessStarter.
1917
///
20-
/// ## Static options:
21-
/// Name | Description | Default value
22-
/// ---- | ----------- | -------------
23-
/// task_processor | the name of the TaskProcessor for asynchronous process starting | the 'default_task_processor' value from components::ManagerControllerComponent
24-
25-
// clang-format on
18+
/// ## Static options of @ref components::ProcessStarter :
19+
/// @include{doc} scripts/docs/en/components_schema/core/src/components/process_starter.md
20+
///
21+
/// Options inherited from @ref components::ComponentBase :
22+
/// @include{doc} scripts/docs/en/components_schema/core/src/components/impl/component_base.md
2623
class ProcessStarter final : public ComponentBase {
2724
public:
2825
/// @ingroup userver_component_names
29-
/// @brief The default name of components::ProcessStarter component
26+
/// @brief The default name of @ref components::ProcessStarter component
3027
static constexpr std::string_view kName = "process-starter";
3128

3229
ProcessStarter(const ComponentConfig& config, const ComponentContext& context);

‎core/include/userver/components/tcp_acceptor_base.hpp‎

Lines changed: 6 additions & 15 deletions
Original file line numberDiff line numberDiff line change
@@ -16,28 +16,19 @@ struct ListenerConfig;
1616

1717
namespace components {
1818

19-
// clang-format off
20-
2119
/// @ingroup userver_base_classes userver_components
2220
///
2321
/// @brief Component for accepting incoming TCP connections.
2422
///
25-
/// Each accepted socket is processed in a new coroutine by ProcessSocket of
26-
/// the derived class.
23+
/// Each accepted socket is processed in a new coroutine by ProcessSocket of the derived class.
24+
///
25+
/// ## Static options of @ref components::TcpAcceptorBase :
26+
/// @include{doc} scripts/docs/en/components_schema/core/src/components/tcp_acceptor_base.md
2727
///
28-
/// ## Static options:
29-
/// Name | Description | Default value
30-
/// ---- | ----------- | -------------
31-
/// port | port to listen on | -
32-
/// unix-socket | unix socket to listen on instead of listening on a port | ''
33-
/// task_processor | task processor to accept incoming connections | the 'default_task_processor' value from components::ManagerControllerComponent
34-
/// backlog | max count of new connections pending acceptance | 1024
35-
/// no_delay | whether to set the `TCP_NODELAY` option on incoming sockets | true
36-
/// sockets_task_processor | task processor to process accepted sockets | value of `task_processor`
28+
/// Options inherited from @ref components::ComponentBase :
29+
/// @include{doc} scripts/docs/en/components_schema/core/src/components/impl/component_base.md
3730
///
3831
/// @see @ref scripts/docs/en/userver/tutorial/tcp_service.md
39-
40-
// clang-format on
4132
class TcpAcceptorBase : public ComponentBase {
4233
public:
4334
TcpAcceptorBase(const ComponentConfig&, const ComponentContext&);

‎core/include/userver/congestion_control/component.hpp‎

Lines changed: 6 additions & 13 deletions
Original file line numberDiff line numberDiff line change
@@ -16,8 +16,6 @@ namespace congestion_control {
1616

1717
class Controller;
1818

19-
// clang-format off
20-
2119
/// @ingroup userver_components
2220
///
2321
/// @brief Component to limit too active requests, also known as CC.
@@ -26,24 +24,19 @@ class Controller;
2624
/// * @ref USERVER_RPS_CCONTROL
2725
/// * @ref USERVER_RPS_CCONTROL_ENABLED
2826
///
29-
/// ## Static options:
30-
/// Name | Description | Default value
31-
/// ---- | ----------- | -------------
32-
/// fake-mode | if set, an actual throttling is skipped, but FSM is still working and producing informational logs | false
33-
/// min-cpu | force fake-mode if the current cpu number is less than the specified value | 1
34-
/// only-rtc | if set to true and hostinfo::IsInRtc() returns false then forces the fake-mode | true
35-
/// status-code | HTTP status code for ratelimited responses | 429
27+
/// ## Static options of @ref congestion_control::Component :
28+
/// @include{doc} scripts/docs/en/components_schema/core/src/congestion_control/component.md
29+
///
30+
/// Options inherited from @ref components::ComponentBase :
31+
/// @include{doc} scripts/docs/en/components_schema/core/src/components/impl/component_base.md
3632
///
3733
/// ## Static configuration example:
3834
///
3935
/// @snippet components/common_server_component_list_test.cpp Sample congestion control component config
40-
41-
// clang-format on
42-
4336
class Component final : public components::ComponentBase {
4437
public:
4538
/// @ingroup userver_component_names
46-
/// @brief The default name of congestion_control::Component component
39+
/// @brief The default name of @ref congestion_control::Component component
4740
static constexpr std::string_view kName = "congestion-control";
4841

4942
Component(const components::ComponentConfig&, const components::ComponentContext&);

‎core/include/userver/dump/dumper.hpp‎

Lines changed: 5 additions & 13 deletions
Original file line numberDiff line numberDiff line change
@@ -55,7 +55,6 @@ enum class UpdateType {
5555
kAlreadyUpToDate,
5656
};
5757

58-
// clang-format off
5958
/// @brief Manages dumps of a cache-like component
6059
///
6160
/// The class is thread-safe.
@@ -74,23 +73,16 @@ enum class UpdateType {
7473
/// ## Dumper Dynamic config
7574
/// * @ref USERVER_DUMPS
7675
///
77-
/// ## Static config
78-
/// Name | Type | Description | Default value
79-
/// ---- | ---- | ----------- | -------------
80-
/// `enable` | `boolean` | Whether this `Dumper` should actually read and write dumps | (required)
81-
/// `world-readable` | `boolean` | If `true`, dumps are created with access `0444`, otherwise with access `0400` | (required)
82-
/// `format-version` | `integer` | Allows to ignore dumps written with an obsolete `format-version` | (required)
83-
/// `max-age` | optional `string` (duration) | Overdue dumps are ignored | null
84-
/// `max-count` | optional `integer` | Old dumps over the limit are removed from disk | `1`
85-
/// `min-interval` | `string` (duration) | `WriteDumpAsync` calls performed in a fast succession are ignored | `0s`
86-
/// `fs-task-processor` | `string` | `TaskProcessor` for blocking disk IO | engine::current_task::GetBlockingTaskProcessor()
87-
/// `encrypted` | `boolean` | Whether to encrypt the dump | `false`
76+
/// ## Static config of @ref dump::Dumper :
77+
/// @include{doc} scripts/docs/en/components_schema/core/src/dump/dumper.md
78+
///
79+
/// Options inherited from @ref components::ComponentBase :
80+
/// @include{doc} scripts/docs/en/components_schema/core/src/components/impl/component_base.md
8881
///
8982
/// ## Sample usage
9083
/// @snippet core/src/dump/dumper_test.cpp Sample Dumper usage
9184
///
9285
/// @see components::DumpConfigurator
93-
// clang-format on
9486
class Dumper final {
9587
public:
9688
/// @brief The primary constructor for when `Dumper` is stored in a component

‎core/include/userver/engine/task_processors_load_monitor.hpp‎

Lines changed: 5 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -11,24 +11,20 @@ USERVER_NAMESPACE_BEGIN
1111

1212
namespace engine {
1313

14-
// clang-format off
1514
/// @ingroup userver_components
1615
///
1716
/// @brief Component to monitor CPU usage for every TaskProcessor present in
1817
/// the service, and dump per-thread stats into metrics.
1918
///
20-
/// ## Static options:
21-
/// Inherits all the options from components::ComponentBase and adds the
22-
/// following ones:
19+
/// ## Static options of @ref engine::TaskProcessorsLoadMonitor :
20+
/// @include{doc} scripts/docs/en/components_schema/core/src/engine/task_processors_load_monitor.md
2321
///
24-
/// Name | Description | Default value
25-
/// -------------- | ---------------------------------------------- | ---------------------------------
26-
/// task-processor | name of the TaskProcessor to run monitoring on | default monitoring task processor
27-
// clang-format on
22+
/// Options inherited from @ref components::ComponentBase :
23+
/// @include{doc} scripts/docs/en/components_schema/core/src/components/impl/component_base.md
2824
class TaskProcessorsLoadMonitor final : public components::ComponentBase {
2925
public:
3026
/// @ingroup userver_component_names
31-
/// @brief The default name of engine::TaskProcessorsLoadMonitor
27+
/// @brief The default name of @ref engine::TaskProcessorsLoadMonitor
3228
static constexpr std::string_view kName{"task-processors-load-monitor"};
3329

3430
TaskProcessorsLoadMonitor(const components::ComponentConfig& config, const components::ComponentContext& context);

‎core/include/userver/storages/secdist/component.hpp‎

Lines changed: 8 additions & 12 deletions
Original file line numberDiff line numberDiff line change
@@ -11,33 +11,29 @@
1111
USERVER_NAMESPACE_BEGIN
1212

1313
namespace components {
14-
// clang-format off
1514

1615
/// @ingroup userver_components
1716
///
1817
/// @brief Component that stores security related data (keys, passwords, ...).
1918
///
2019
/// The component must be configured in service config.
2120
///
22-
/// Secdist requires a provider storages::secdist::SecdistProvider
23-
/// You can implement your own or use components::DefaultSecdistProvider
21+
/// Secdist requires a provider @ref storages::secdist::SecdistProvider
22+
/// You can implement your own or use @ref components::DefaultSecdistProvider.
2423
///
2524
/// ## Static configuration example:
2625
///
2726
/// @snippet samples/redis_service/static_config.yaml Sample secdist static config
2827
///
29-
/// ## Static options:
30-
/// Name | Description | Default value
31-
/// ---- | ----------- | -------------
32-
/// provider | optional secdist provider component name | 'default-secdist-provider'
33-
/// update-period | period between data updates in utils::StringToDuration() suitable format ('0s' for no updates) | 10s
34-
35-
// clang-format on
36-
28+
/// ## Static options of @ref components::Secdist :
29+
/// @include{doc} scripts/docs/en/components_schema/core/src/storages/secdist/component.md
30+
///
31+
/// Options inherited from @ref components::ComponentBase :
32+
/// @include{doc} scripts/docs/en/components_schema/core/src/components/impl/component_base.md
3733
class Secdist final : public ComponentBase {
3834
public:
3935
/// @ingroup userver_component_names
40-
/// @brief The default name of components::Secdist
36+
/// @brief The default name of @ref components::Secdist
4137
static constexpr std::string_view kName = "secdist";
4238

4339
Secdist(const ComponentConfig&, const ComponentContext&);

‎core/include/userver/storages/secdist/provider_component.hpp‎

Lines changed: 6 additions & 14 deletions
Original file line numberDiff line numberDiff line change
@@ -35,30 +35,22 @@ class DefaultLoader final : public storages::secdist::SecdistProvider {
3535
} // namespace storages::secdist
3636

3737
namespace components {
38-
// clang-format off
3938

4039
/// @ingroup userver_components
4140
///
4241
/// @brief Component that stores security related data (keys, passwords, ...).
4342
///
4443
/// The component must be configured in service config.
4544
///
46-
/// ## Static options:
47-
/// Name | Description | Default value
48-
/// ---- | ----------- | -------------
49-
/// config | path to the config file with data | ''
50-
/// inline | inline data | -
51-
/// format | config format, one of `json`, `yaml`, `yaml_config` | 'json'
52-
/// missing-ok | do not terminate components load if no file found by the config option | false
53-
/// environment-secrets-key | name of environment variable from which to load additional data | -
54-
/// blocking-task-processor | name of task processor for background blocking operations | engine::current_task::GetBlockingTaskProcessor()
55-
56-
// clang-format on
57-
45+
/// ## Static options of @ref components::DefaultSecdistProvider :
46+
/// @include{doc} scripts/docs/en/components_schema/core/src/storages/secdist/provider_component.md
47+
///
48+
/// Options inherited from @ref components::ComponentBase :
49+
/// @include{doc} scripts/docs/en/components_schema/core/src/components/impl/component_base.md
5850
class DefaultSecdistProvider final : public ComponentBase, public storages::secdist::SecdistProvider {
5951
public:
6052
/// @ingroup userver_component_names
61-
/// @brief The default name of components::DefaultSecdistProvider
53+
/// @brief The default name of @ref components::DefaultSecdistProvider
6254
static constexpr std::string_view kName = "default-secdist-provider";
6355

6456
DefaultSecdistProvider(const ComponentConfig&, const ComponentContext&);

0 commit comments

Comments
 (0)