From b3fb59e6b5a32a615f57161405f2858060e0336d Mon Sep 17 00:00:00 2001 From: Nanaloveyuki Date: Sun, 14 Jun 2026 01:41:02 +0800 Subject: [PATCH] :memo: clarify config export docs --- docs/api/logger-config-to-json.md | 8 ++++++++ docs/api/queue-config-to-json.md | 7 +++++++ docs/api/sink-config-to-json.md | 8 ++++++++ 3 files changed, 23 insertions(+) diff --git a/docs/api/logger-config-to-json.md b/docs/api/logger-config-to-json.md index b286794..98ea472 100644 --- a/docs/api/logger-config-to-json.md +++ b/docs/api/logger-config-to-json.md @@ -35,6 +35,8 @@ Detailed rules explaining key parameters and behaviors - The output includes `min_level`, `target`, `timestamp`, `sink`, and optional `queue`. - Sink export is delegated to `sink_config_to_json(...)`. +- Queue export is delegated to `queue_config_to_json(...)` only when `config.queue` is present; otherwise the `queue` field is omitted entirely. +- `min_level` is serialized using `Level::label()`, so the emitted string follows the same stable config vocabulary accepted by the parser. - The result is suitable for downstream JSON composition as well as stringification. - Exported JSON follows the stable supported config schema rather than raw internal runtime state. @@ -67,3 +69,9 @@ e.g.: - If some sink options are unused by the chosen sink kind, they still follow the supported config export shape rather than a runtime-only interpretation. +### Notes + +1. Use this helper when you need a reusable JSON value rather than a final JSON string. + +2. Use `stringify_logger_config(...)` when the next consumer expects JSON text instead of `JsonValue`. + diff --git a/docs/api/queue-config-to-json.md b/docs/api/queue-config-to-json.md index 8f3d010..31fdded 100644 --- a/docs/api/queue-config-to-json.md +++ b/docs/api/queue-config-to-json.md @@ -35,6 +35,7 @@ Detailed rules explaining key parameters and behaviors - The output includes `max_pending` and `overflow`. - Overflow is serialized using the supported config labels such as `DropNewest` and `DropOldest`. +- `max_pending` is emitted as a JSON number and `overflow` is emitted as the stable parser-facing text label, so the result stays aligned with `parse_logger_config_text(...)` roundtrips. - This helper is intended for config export rather than runtime queue inspection. - The JSON shape matches the queue section accepted by `parse_logger_config_text(...)`. @@ -69,3 +70,9 @@ e.g.: - If callers need direct text output instead of a JSON value, they should use `stringify_queue_config(...)` instead. +### Notes + +1. Use this helper when you need a reusable JSON value rather than a final JSON string. + +2. Use `stringify_queue_config(...)` when the next consumer expects text instead of `JsonValue`. + diff --git a/docs/api/sink-config-to-json.md b/docs/api/sink-config-to-json.md index e68e0a2..0846af8 100644 --- a/docs/api/sink-config-to-json.md +++ b/docs/api/sink-config-to-json.md @@ -35,6 +35,8 @@ Detailed rules explaining key parameters and behaviors - The output includes `kind`, `path`, `append`, `auto_flush`, and `text_formatter`. - `rotation` is only included when present. +- `kind` is serialized using the stable parser-facing sink labels such as `console`, `json_console`, `text_console`, and `file`. +- `text_formatter` export is delegated to `text_formatter_config_to_json(...)`, so nested formatter settings follow the same config schema used elsewhere. - The exported shape is schema-oriented and shared by larger config export helpers. - This helper is especially useful when building larger config payloads manually. @@ -67,3 +69,9 @@ e.g.: - If file-related fields are unused by the sink kind, they are still exported according to the stable config shape. +### Notes + +1. Use this helper when you need a reusable JSON value rather than a final JSON string. + +2. `logger_config_to_json(...)` reuses this helper for the nested `sink` field. +