From f19e9649afae4306cd8d77e46984fc0aaef54289 Mon Sep 17 00:00:00 2001 From: Nanaloveyuki Date: Sun, 14 Jun 2026 00:29:22 +0800 Subject: [PATCH] :memo: align async build config docs --- docs/api/async-logger-build-config-to-json.md | 18 ++++++++++++++++-- docs/api/async-logger-build-config.md | 13 +++++++++++-- .../parse-async-logger-build-config-text.md | 4 +++- .../api/stringify-async-logger-build-config.md | 15 +++++++++++++-- 4 files changed, 43 insertions(+), 7 deletions(-) diff --git a/docs/api/async-logger-build-config-to-json.md b/docs/api/async-logger-build-config-to-json.md index 85c15d6..6ca2b23 100644 --- a/docs/api/async-logger-build-config-to-json.md +++ b/docs/api/async-logger-build-config-to-json.md @@ -2,8 +2,8 @@ name: async-logger-build-config-to-json group: api category: async -update-time: 20260512 -description: Convert AsyncLoggerBuildConfig into a JSON value for exporting complete async logger build settings. +update-time: 20260614 +description: Convert AsyncLoggerBuildConfig into a JSON value for exporting the full shared async build shape that can later feed either async builder path. key-word: - async - build @@ -39,6 +39,8 @@ Detailed rules explaining key parameters and behaviors - Logger export is delegated to `@bitlogger.logger_config_to_json(...)`. - Async export is delegated to `async_logger_config_to_json(...)`. - 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. ### How to Use @@ -58,6 +60,8 @@ let payload = async_logger_build_config_to_json( In this example, both layers of configuration are exported together. +And later consumers can still choose whether to rebuild through `build_async_logger(...)` or the narrower `build_async_text_logger(...)` path. + #### When Need Roundtrip-friendly Build Config Data When generated build config should later be parsed again: @@ -74,3 +78,13 @@ e.g.: - If callers want direct text output, they should use `stringify_async_logger_build_config(...)` instead. +- Exporting the full `logger` section does not imply that every async builder will later consume every logger field equally. + +### Notes + +1. Use this helper when tools or tests need a structured JSON object instead of text. + +2. Use `stringify_async_logger_build_config(...)` when the same build shape should be emitted as JSON text directly. + +3. The resulting object round-trips through `parse_async_logger_build_config_text(...)`, even though different async builders later consume different parts of the embedded `LoggerConfig`. + diff --git a/docs/api/async-logger-build-config.md b/docs/api/async-logger-build-config.md index 82adfdd..933afc7 100644 --- a/docs/api/async-logger-build-config.md +++ b/docs/api/async-logger-build-config.md @@ -3,7 +3,7 @@ name: async-logger-build-config group: api category: async update-time: 20260614 -description: Create the combined sync-and-async build config used by async logger builder APIs, with the sync logger config applied before the outer async layer. +description: Create the combined sync-and-async build config used by async logger builder APIs, whether callers later choose the full sync-first builder path or the specialized text-console builder path. key-word: - async - build @@ -13,7 +13,7 @@ key-word: ## Async-logger-build-config -Create an `AsyncLoggerBuildConfig` value that combines the base synchronous `LoggerConfig` with the async runtime `AsyncLoggerConfig`. This is the constructor used when async builder APIs should receive one typed object carrying both layers of setup. +Create an `AsyncLoggerBuildConfig` value that combines the base synchronous `LoggerConfig` with the async runtime `AsyncLoggerConfig`. This is the constructor used when async builder APIs should receive one typed object carrying both layers of setup, even though different builders later consume different parts of the embedded sync config. ### Interface @@ -41,6 +41,7 @@ Detailed rules explaining key parameters and behaviors - Omitting `async_config` uses `AsyncLoggerConfig::new()`. - The constructor simply packages both config objects into one public build shape. - When passed to `build_async_logger(...)`, the `logger` portion is built first through the normal synchronous config path before the outer async queue layer is applied. +- When passed to `build_async_text_logger(...)`, the same `logger` portion is consumed more narrowly: `text_formatter`, `min_level`, `target`, and `timestamp` are used directly to build a text console sink, while `LoggerConfig.queue` is not applied. - This helper is the main code-side counterpart to `parse_async_logger_build_config_text(...)`. ### How to Use @@ -59,6 +60,8 @@ let config = AsyncLoggerBuildConfig::new( In this example, the builder input keeps both configuration layers in one typed value. +And later code can still decide whether that shared config should flow into the full sync-first builder or the narrower text-console builder. + #### When Need Defaulted Async Build Settings When code only wants the standard combined config shape with few overrides: @@ -75,8 +78,14 @@ e.g.: - If callers only need async runtime policy and not the full builder input shape, `AsyncLoggerConfig::new(...)` is the smaller API. +- If callers expect every field inside `LoggerConfig` to affect every async builder equally, that assumption is too broad: `build_async_text_logger(...)` intentionally skips the optional sync queue layer. + ### Notes 1. Use this helper when async builder APIs should receive one combined config object. 2. Pair it with `build_async_logger(...)`, `build_async_text_logger(...)`, or `parse_async_logger_build_config_text(...)` depending on whether the source is code or JSON text. + +3. Prefer `build_async_logger(...)` after constructing this value when configured sync sink behavior, including `LoggerConfig.queue`, should be preserved before async wrapping. + +4. Prefer `build_async_text_logger(...)` after constructing this value when the goal is specifically config-driven text console output with a concrete `FormattedConsoleSink`. diff --git a/docs/api/parse-async-logger-build-config-text.md b/docs/api/parse-async-logger-build-config-text.md index 1ef05cd..51a5c53 100644 --- a/docs/api/parse-async-logger-build-config-text.md +++ b/docs/api/parse-async-logger-build-config-text.md @@ -23,7 +23,7 @@ pub fn parse_async_logger_build_config_text(input : String) -> AsyncLoggerBuildC #### input -- `input : String` - JSON text containing `logger` and `async_config` sections. +- `input : String` - JSON text that may contain `logger` and `async_config` sections. #### output @@ -36,6 +36,8 @@ Detailed rules explaining key parameters and behaviors - The JSON root is split into `logger` and `async_config`. - `logger` reuses the same synchronous config schema parsed by `parse_logger_config_text(...)`. - `async_config` is parsed through `parse_async_logger_config_text(...)`. +- If `logger` is omitted, parsing falls back to `default_logger_config()`. +- If `async_config` is omitted, parsing falls back to `AsyncLoggerConfig::new()`. - This API separates validation from actual async runtime construction. - When the parsed config is later passed to `build_async_logger(...)`, the embedded `logger` section goes through the normal sync builder path first, including optional `LoggerConfig.queue` handling. - When the same parsed config is passed to `build_async_text_logger(...)`, only `logger.sink.text_formatter` plus the top-level `min_level`, `target`, and `timestamp` fields are consumed directly, so the sync queue layer is not applied. diff --git a/docs/api/stringify-async-logger-build-config.md b/docs/api/stringify-async-logger-build-config.md index 22eacf0..c64635b 100644 --- a/docs/api/stringify-async-logger-build-config.md +++ b/docs/api/stringify-async-logger-build-config.md @@ -2,8 +2,8 @@ name: stringify-async-logger-build-config group: api category: async -update-time: 20260512 -description: Serialize AsyncLoggerBuildConfig into compact or pretty JSON text for export and diagnostics. +update-time: 20260614 +description: Serialize AsyncLoggerBuildConfig into compact or pretty JSON text for export and diagnostics across both async builder paths. key-word: - async - build @@ -41,6 +41,7 @@ Detailed rules explaining key parameters and behaviors - `pretty=true` returns indented JSON for human inspection. - This helper is built on top of `async_logger_build_config_to_json(...)`. - 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. ### How to Use @@ -55,6 +56,8 @@ println(stringify_async_logger_build_config(AsyncLoggerBuildConfig::new(), prett In this example, the full build configuration is rendered as readable JSON. +And the resulting text still describes a shared config object that can feed either async builder path later. + #### When Need Compact Generated Build Config When config text should stay small for snapshots or transport: @@ -73,3 +76,11 @@ e.g.: - If only one layer of config is required, this helper may be broader than necessary. +### Notes + +1. Use this helper when the async build shape should be logged or stored as text directly. + +2. Use `pretty=true` for review and diagnostics, or the default compact form for snapshots and transport. + +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. +