From 75f1b457fa454460583728248a415c50b13d677b Mon Sep 17 00:00:00 2001 From: Nanaloveyuki Date: Sun, 14 Jun 2026 01:47:02 +0800 Subject: [PATCH] :memo: clarify async config export docs --- docs/api/async-logger-build-config-to-json.md | 1 + docs/api/stringify-async-logger-build-config.md | 3 +++ docs/api/stringify-async-logger-config.md | 3 +++ 3 files changed, 7 insertions(+) diff --git a/docs/api/async-logger-build-config-to-json.md b/docs/api/async-logger-build-config-to-json.md index 6ca2b23..40ece06 100644 --- a/docs/api/async-logger-build-config-to-json.md +++ b/docs/api/async-logger-build-config-to-json.md @@ -38,6 +38,7 @@ Detailed rules explaining key parameters and behaviors - The output always includes `logger` and `async_config`. - Logger export is delegated to `@bitlogger.logger_config_to_json(...)`. - Async export is delegated to `async_logger_config_to_json(...)`. +- Because both sections are always materialized, parsed defaults that were originally omitted in JSON input become explicit again in the exported build-config shape. - This helper is useful when generated setup should preserve both sink/logger behavior and async runtime behavior together. - The exported `logger` section keeps the full `LoggerConfig` shape, including fields that only matter on the full sync-first builder path such as the optional sync queue layer. - That means the JSON shape is broader than the consumption pattern of `build_async_text_logger(...)`, which only uses selected text-oriented logger fields when building the sink. diff --git a/docs/api/stringify-async-logger-build-config.md b/docs/api/stringify-async-logger-build-config.md index c64635b..8d5a407 100644 --- a/docs/api/stringify-async-logger-build-config.md +++ b/docs/api/stringify-async-logger-build-config.md @@ -40,6 +40,7 @@ Detailed rules explaining key parameters and behaviors - `pretty=false` returns compact JSON. - `pretty=true` returns indented JSON for human inspection. - This helper is built on top of `async_logger_build_config_to_json(...)`. +- Internally it serializes the `JsonValue` result with `@json_parser.stringify(...)` or `@json_parser.stringify_pretty(value, 2)`, so the text form stays aligned with the structured async build-config export helper. - The output keeps `logger` and `async_config` as separate sections, matching supported parser input. - The serialized `logger` section preserves the full `LoggerConfig` shape, even though `build_async_text_logger(...)` later consumes only the selected text-oriented subset of that logger config. @@ -84,3 +85,5 @@ e.g.: 3. The serialized shape round-trips through `parse_async_logger_build_config_text(...)`, but the later builder choice still controls whether the full sync config path or only the text-oriented subset is consumed during construction. +4. Use `async_logger_build_config_to_json(...)` when the next consumer still needs a `JsonValue` for composition before final stringification. + diff --git a/docs/api/stringify-async-logger-config.md b/docs/api/stringify-async-logger-config.md index 8206f57..fcebf31 100644 --- a/docs/api/stringify-async-logger-config.md +++ b/docs/api/stringify-async-logger-config.md @@ -37,6 +37,7 @@ Detailed rules explaining key parameters and behaviors - `pretty=false` returns compact JSON suitable for transport and snapshots. - `pretty=true` returns indented JSON for humans. - This helper is built on top of `async_logger_config_to_json(...)`. +- Internally it serializes the `JsonValue` result with `@json_parser.stringify(...)` or `@json_parser.stringify_pretty(value, 2)`, so the text form stays aligned with the structured async-config export helper. - The exported text follows the supported async config schema rather than internal queue implementation details. - Canonical policy labels such as `DropNewest` and `Never` are emitted even though the parser also accepts aliases like `DropLatest` and `None`. @@ -77,3 +78,5 @@ e.g.: 2. If negative `max_pending` semantics matter, remember that the serialized text preserves the config value while runtime queue creation later clamps the queue limit to `0`. +3. Use `async_logger_config_to_json(...)` when the next consumer still needs a `JsonValue` for composition before final stringification. +