naloveyuki/BitLogger
1
0
Fork 0
mirror of https://github.com/Nanaloveyuki/BitLogger.git synced 2026-08-01 07:54:47 +00:00
Code Issues Packages Projects Releases Wiki Activity

📝 clarify async build config stringify routing

Browse Source
This commit is contained in:
Nanaloveyuki
2026-06-14 10:33:10 +08:00
parent 475b15c41f
commit 571ae622d0
1 changed files with 8 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/api/stringify-async-logger-build-config.md
+8
View File
@@ -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 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. - 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`. - 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 ### 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 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 Need Compact Generated Build Config
When config text should stay small for snapshots or transport: 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. - 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 ### Notes
1. Use this helper when the async build shape should be logged or stored as text directly. 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. 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.