Skip to content

Commit 26ded17

Browse files
apolukhinapolukhin
committed
feat docs: use schemas for documentation in more cases
Tests: протестировано в CI, проверено локально что все поля отображаются и форматируются приятно для глаза (или хотя бы как было раньше) commit_hash:5a68f90bd573c96780e6b25ab25348dd7d5722ed
1 parent 27a7f66 commit 26ded17

File tree

14 files changed

+82
-89
lines changed

14 files changed

+82
-89
lines changed

‎.mapping.json‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -3032,6 +3032,7 @@
30323032
"mongo/include/userver/storages/mongo/write_result.hpp":"taxi/uservices/userver/mongo/include/userver/storages/mongo/write_result.hpp",
30333033
"mongo/library.yaml":"taxi/uservices/userver/mongo/library.yaml",
30343034
"mongo/src/cache/base_mongo_cache.cpp":"taxi/uservices/userver/mongo/src/cache/base_mongo_cache.cpp",
3035+
"mongo/src/cache/base_mongo_cache.yaml":"taxi/uservices/userver/mongo/src/cache/base_mongo_cache.yaml",
30353036
"mongo/src/cache/mongo_cache_type_traits_test.cpp":"taxi/uservices/userver/mongo/src/cache/mongo_cache_type_traits_test.cpp",
30363037
"mongo/src/formats/bson/binary.cpp":"taxi/uservices/userver/mongo/src/formats/bson/binary.cpp",
30373038
"mongo/src/formats/bson/binary_test.cpp":"taxi/uservices/userver/mongo/src/formats/bson/binary_test.cpp",
@@ -3429,6 +3430,7 @@
34293430
"postgresql/pq-extra/pq_workaround.c":"taxi/uservices/userver/postgresql/pq-extra/pq_workaround.c",
34303431
"postgresql/pq-extra/pq_workaround.h":"taxi/uservices/userver/postgresql/pq-extra/pq_workaround.h",
34313432
"postgresql/src/cache/base_postgres_cache.cpp":"taxi/uservices/userver/postgresql/src/cache/base_postgres_cache.cpp",
3433+
"postgresql/src/cache/base_postgres_cache.yaml":"taxi/uservices/userver/postgresql/src/cache/base_postgres_cache.yaml",
34323434
"postgresql/src/cache/postgres_cache_test.cpp":"taxi/uservices/userver/postgresql/src/cache/postgres_cache_test.cpp",
34333435
"postgresql/src/cache/postgres_cache_test_fwd.hpp":"taxi/uservices/userver/postgresql/src/cache/postgres_cache_test_fwd.hpp",
34343436
"postgresql/src/chaotic/io/userver/storages/postgres/time_point_tz.cpp":"taxi/uservices/userver/postgresql/src/chaotic/io/userver/storages/postgres/time_point_tz.cpp",

‎mongo/CMakeLists.txt‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -20,6 +20,7 @@ userver_module(
2020
DEPENDS core
2121
GENERATE_DYNAMIC_CONFIGS
2222
EMBED_FILES
23+
src/cache/base_mongo_cache.yaml
2324
src/storages/mongo/component.yaml
2425
src/storages/mongo/component_multi.yaml
2526
src/storages/mongo/dist_lock_component_base.yaml

‎mongo/include/userver/cache/base_mongo_cache.hpp‎

Lines changed: 9 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -36,8 +36,6 @@ std::chrono::milliseconds GetMongoCacheUpdateCorrection(const ComponentConfig&);
3636

3737
}
3838

39-
// clang-format off
40-
4139
/// @ingroup userver_components
4240
///
4341
/// @brief %Base class for all caches polling mongo collection
@@ -47,11 +45,15 @@ std::chrono::milliseconds GetMongoCacheUpdateCorrection(const ComponentConfig&);
4745
/// For avoiding "memory leaks", see the respective section
4846
/// in @ref components::CachingComponentBase.
4947
///
50-
/// ## Static options:
51-
/// All options of CachingComponentBase and
52-
/// Name | Description | Default value
53-
/// ---- | ----------- | -------------
54-
/// update-correction | adjusts incremental updates window to overlap with previous update | 0
48+
/// ## Static options or @ref components::MongoCache :
49+
///
50+
/// @include{doc} scripts/docs/en/components_schema/mongo/src/cache/base_mongo_cache.md
51+
///
52+
/// Options inherited from @ref components::CachingComponentBase :
53+
/// @include{doc} scripts/docs/en/components_schema/core/src/cache/caching_component_base.md
54+
///
55+
/// Options inherited from @ref components::ComponentBase :
56+
/// @include{doc} scripts/docs/en/components_schema/core/src/components/impl/component_base.md
5557
///
5658
/// ## Traits example:
5759
/// All fields below (except for function overrides) are mandatory.
@@ -115,9 +117,6 @@ std::chrono::milliseconds GetMongoCacheUpdateCorrection(const ComponentConfig&);
115117
/// using MongoCollectionsComponent = components::MongoCollections;
116118
/// };
117119
/// ```
118-
119-
// clang-format on
120-
121120
template <class MongoCacheTraits>
122121
class MongoCache : public CachingComponentBase<typename MongoCacheTraits::DataType> {
123122
using CollectionsType = mongo_cache::impl::CollectionsType<decltype(MongoCacheTraits::kMongoCollectionsField)>;

‎mongo/src/cache/base_mongo_cache.cpp‎

Lines changed: 6 additions & 13 deletions
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,11 @@
11
#include <userver/cache/base_mongo_cache.hpp>
22

33
#include <userver/components/component_config.hpp>
4-
#include <userver/yaml_config/merge_schemas.hpp>
4+
#include <userver/utils/resources.hpp>
5+
6+
#ifndef ARCADIA_ROOT
7+
#include "generated/src/cache/base_mongo_cache.yaml.hpp" // Y_IGNORE
8+
#endif
59

610
USERVER_NAMESPACE_BEGIN
711

@@ -11,18 +15,7 @@ std::chrono::milliseconds GetMongoCacheUpdateCorrection(const ComponentConfig& c
1115
return config["update-correction"].As<std::chrono::milliseconds>(0);
1216
}
1317

14-
std::string GetMongoCacheSchema() {
15-
return R"(
16-
type: object
17-
description: Base class for all caches polling mongo collection
18-
additionalProperties: false
19-
properties:
20-
update-correction:
21-
type: string
22-
description: adjusts incremental updates window to overlap with previous update
23-
defaultDescription: 0
24-
)";
25-
}
18+
std::string GetMongoCacheSchema() { return utils::FindResource("src/cache/base_mongo_cache.yaml"); }
2619

2720
} // namespace components::impl
2821

‎mongo/src/cache/base_mongo_cache.yaml‎

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,8 @@
1+
type: object
2+
description: Base class for all caches polling mongo collection
3+
additionalProperties: false
4+
properties:
5+
update-correction:
6+
type: string
7+
description: adjusts incremental updates window to overlap with previous update
8+
defaultDescription: 0

‎mysql/src/storages/mysql/component.yaml‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -5,7 +5,7 @@ properties:
55
initial_pool_size:
66
type: integer
77
description: number of connections created initially
8-
defaultDescription: 1
8+
defaultDescription: 5
99
max_pool_size:
1010
type: integer
1111
description: maximum number of created connections

‎otlp/include/userver/otlp/logs/component.hpp‎

Lines changed: 5 additions & 18 deletions
Original file line numberDiff line numberDiff line change
@@ -17,33 +17,20 @@ namespace otlp {
1717

1818
class Logger;
1919

20-
// clang-format off
21-
2220
/// @ingroup userver_components
2321
///
2422
/// @brief Component to configure logging via OTLP collector.
2523
///
26-
/// ## Static options:
27-
/// Name | Description | Default value
28-
/// ---- | ----------- | -------------
29-
/// endpoint | URI of otel collector (e.g. 127.0.0.1:4317). This endpoint is used both for logs and traces. If you want separate endpoints, then use below options. | -
30-
/// logs-endpoint | URI of otel collector (gRPC). This endpoint is used only for logs. | -
31-
/// tracing-endpoint | URI of otel collector (gRPC). This endpoint is used only for traces. | -
32-
/// client-factory-name | Name of the grpc client factory | -
33-
/// max-queue-size | Maximum async queue size | 65535
34-
/// max-batch-delay | Maximum batch delay | 100ms
35-
/// service-name | Service name | unknown_service
36-
/// attributes | Extra attributes for OTLP, object of key/value strings | -
37-
/// sinks | List of sinks | -
38-
/// sinks.logs | sink for logs (default|otlp|both) | otlp
39-
/// sinks.tracing | sink for tracing (default|otlp|both) | otlp
24+
/// ## Static options of @ref otlp::LoggerComponent :
25+
/// @include{doc} scripts/docs/en/components_schema/otlp/src/otlp/logs/component.md
26+
///
27+
/// Options inherited from @ref components::ComponentBase :
28+
/// @include{doc} scripts/docs/en/components_schema/core/src/components/impl/component_base.md
4029
///
4130
/// Possible sink values:
4231
/// * `otlp`: OTLP exporter
4332
/// * `default`: _default_ logger from the `logging` component
4433
/// * `both`: _default_ logger and OTLP exporter
45-
46-
// clang-format on
4734
class LoggerComponent final : public components::RawComponentBase {
4835
public:
4936
/// @ingroup userver_component_names

‎otlp/src/otlp/logs/component.yaml‎

Lines changed: 5 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -43,12 +43,15 @@ properties:
4343
max-queue-size:
4444
type: integer
4545
description: max async queue size
46+
defaultDescription: 65535
4647
max-batch-delay:
4748
type: string
4849
description: max delay between send batches (e.g. 100ms or 1s)
50+
defaultDescription: 100ms
4951
service-name:
5052
type: string
5153
description: service name
54+
defaultDescription: unknown_service
5255
sinks:
5356
type: object
5457
description: sinks to send logs/traces to
@@ -57,12 +60,12 @@ properties:
5760
logs:
5861
type: string
5962
enum: [otlp, default, both]
60-
description: logs sink
63+
description: logs sink, one of [otlp, default, both]
6164
defaultDescription: otlp
6265
tracing:
6366
type: string
6467
enum: [otlp, default, both]
65-
description: tracing sink
68+
description: tracing sink, one of [otlp, default, both]
6669
defaultDescription: otlp
6770
attributes-mapping:
6871
type: object

‎postgresql/CMakeLists.txt‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -51,6 +51,7 @@ userver_module(
5151
DEPENDS core
5252
GENERATE_DYNAMIC_CONFIGS
5353
EMBED_FILES
54+
src/cache/base_postgres_cache.yaml
5455
src/storages/postgres/component.yaml
5556
src/storages/postgres/dist_lock_component_base.yaml
5657
)

‎postgresql/include/userver/cache/base_postgres_cache.hpp‎

Lines changed: 7 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -36,8 +36,6 @@ USERVER_NAMESPACE_BEGIN
3636

3737
namespace components {
3838

39-
// clang-format off
40-
4139
/// @page pg_cache Caching Component for PostgreSQL
4240
///
4341
/// A typical components::PostgreCache usage consists of trait definition:
@@ -61,13 +59,13 @@ namespace components {
6159
/// For avoiding "memory leaks", see the respective section
6260
/// in @ref components::CachingComponentBase.
6361
///
64-
/// Name | Description | Default value
65-
/// ---- | ----------- | -------------
66-
/// full-update-op-timeout | timeout for a full update | 1m
67-
/// incremental-update-op-timeout | timeout for an incremental update | 1s
68-
/// update-correction | incremental update window adjustment | - (0 for caches with defined GetLastKnownUpdated)
69-
/// chunk-size | number of rows to request from PostgreSQL via portals, 0 to fetch all rows in one request without portals | 1000
70-
/// sleep-between-chunks | duration to wait between reading chunks from PostgreSQL | 0ms
62+
/// @include{doc} scripts/docs/en/components_schema/postgresql/src/cache/base_postgres_cache.md
63+
///
64+
/// Options inherited from @ref components::CachingComponentBase :
65+
/// @include{doc} scripts/docs/en/components_schema/core/src/cache/caching_component_base.md
66+
///
67+
/// Options inherited from @ref components::ComponentBase :
68+
/// @include{doc} scripts/docs/en/components_schema/core/src/components/impl/component_base.md
7169
///
7270
/// @section pg_cc_cache_policy Cache policy
7371
///
@@ -125,8 +123,6 @@ namespace components {
125123
/// ⇦ @ref scripts/docs/en/userver/cache_dumps.md | @ref scripts/docs/en/userver/lru_cache.md ⇨
126124
/// @htmlonly </div> @endhtmlonly
127125

128-
// clang-format on
129-
130126
namespace pg_cache::detail {
131127

132128
template <typename T>

0 commit comments

Comments
 (0)