From 571ae622d0632e6510d0f2792eb3d1ab038c0471 Mon Sep 17 00:00:00 2001 From: Nanaloveyuki Date: Sun, 14 Jun 2026 10:33:10 +0800 Subject: [PATCH] :memo: clarify async build config stringify routing --- docs/api/stringify-async-logger-build-config.md | 8 ++++++++ 1 file changed, 8 insertions(+) diff --git a/docs/api/stringify-async-logger-build-config.md b/docs/api/stringify-async-logger-build-config.md index d990b4b..6013b49 100644 --- a/docs/api/stringify-async-logger-build-config.md +++ b/docs/api/stringify-async-logger-build-config.md @@ -44,6 +44,8 @@ Detailed rules explaining key parameters and behaviors - 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. - That includes preserving whatever `logger.sink.kind` text is present in the config, even though the later text-specific builder path still ignores that sink-kind branch and constructs `FormattedConsoleSink` from `logger.sink.text_formatter`. +- The serialized text is also the shared handoff format for the application and library facade routes after parse. `parse_async_logger_build_config_text(...)` can read this text back into `AsyncLoggerBuildConfig`, and that parsed value can then flow unchanged into `build_application_async_logger(...)`, `build_application_text_async_logger(...)`, `build_library_async_logger(...)`, or `build_library_async_text_logger(...)`. +- Because of that, the text describes one shared build-config shape rather than committing the next consumer to one public async type. The later builder or facade API still decides whether the runtime-sink line or the text-console line is taken. ### How to Use @@ -62,6 +64,8 @@ And the resulting text still describes a shared config object that can feed eith And if later code chooses `build_async_text_logger(...)`, that choice still matters more than the serialized `logger.sink.kind` text because only the formatter-backed text path is consumed there. +And the same serialized text can just as well be parsed and then routed into the application or library facade builders when the next consumer wants a narrower public async type. + #### When Need Compact Generated Build Config When config text should stay small for snapshots or transport: @@ -80,6 +84,8 @@ e.g.: - If only one layer of config is required, this helper may be broader than necessary. +- Choosing an application or library facade builder after parsing this text does not change the meaning of the serialized config by itself; those facade APIs inherit the same runtime-sink-versus-text-console split from the direct builder they delegate to. + ### Notes 1. Use this helper when the async build shape should be logged or stored as text directly. @@ -92,3 +98,5 @@ e.g.: 5. Use `async_logger_build_config_to_json(...)` when the next consumer still needs a `JsonValue` for composition before final stringification. +6. After parsing, the same text can also feed the application or library facade builders; string export preserves one shared build-config shape, not a direct-builder-only route. +