From 324ff47b103206f3af142e9a07eda23f299d42e3 Mon Sep 17 00:00:00 2001
From: Nanaloveyuki <miaomiao_159@outlook.com>
Date: Sun, 14 Jun 2026 01:38:16 +0800
Subject: [PATCH] :memo: clarify config model docs

---
 docs/api/logger-config.md | 4 ++++
 docs/api/queue-config.md  | 3 +++
 docs/api/sink-config.md   | 5 +++++
 3 files changed, 12 insertions(+)

diff --git a/docs/api/logger-config.md b/docs/api/logger-config.md
index 8e45ca9..a267016 100644
--- a/docs/api/logger-config.md
+++ b/docs/api/logger-config.md
@@ -47,6 +47,8 @@ Detailed rules explaining key parameters and behaviors
 - `sink` describes the final sink shape before optional queue wrapping.
 - `queue=None` means no configured synchronous queue layer.
 - This same type is embedded into async build config as the synchronous sink/runtime portion.
+- `build_logger(...)` consumes this value directly by building the base runtime sink from `sink`, optionally wrapping it with `queue`, and then applying `min_level`, `target`, and `timestamp` onto the resulting `Logger[RuntimeSink]`.
+- `build_async_logger(...)` reuses this same synchronous config path before adding the outer async layer, while `build_async_text_logger(...)` only uses the selected text-oriented fields instead of the full sync runtime-sink build path.
 
 ### How to Use
 
@@ -88,3 +90,5 @@ e.g.:
 1. This is the core typed config object for sync logger assembly.
 
 2. Prefer this API when config is generated in code rather than parsed from text.
+
+3. Use `default_logger_config()` when callers want the same field defaults as the parser and runtime helpers without spelling them out manually.
diff --git a/docs/api/queue-config.md b/docs/api/queue-config.md
index b17f08a..18f92cf 100644
--- a/docs/api/queue-config.md
+++ b/docs/api/queue-config.md
@@ -39,6 +39,7 @@ Detailed rules explaining key parameters and behaviors
 
 - This config is used by `build_logger(...)` and `parse_and_build_logger(...)` when `queue` is present in `LoggerConfig`.
 - It configures the synchronous `QueuedSink`, not the async adapter package.
+- The runtime builder applies this config after the base `RuntimeSink` is chosen, so the queue wrapper can sit around console, JSON console, text console, or file output.
 - The queue remains explicit and drain-based.
 - Overflow behavior is limited to the supported queue policies.
 
@@ -77,3 +78,5 @@ e.g.:
 1. This API is for config-driven queue wrapping, not `bitlogger_async`.
 
 2. Use `Logger::with_queue(...)` when you want code-side queue composition instead of config.
+
+3. Parsing defaults to `DropNewest` when queue overflow text is omitted, while omitting `queue` from `LoggerConfig` means no synchronous queue wrapper is added at all.
diff --git a/docs/api/sink-config.md b/docs/api/sink-config.md
index 3ef2b48..ba63016 100644
--- a/docs/api/sink-config.md
+++ b/docs/api/sink-config.md
@@ -49,6 +49,9 @@ Detailed rules explaining key parameters and behaviors
 - File-only options are stored even though only `kind=File` actually consumes them.
 - Text formatter config is always present, making text-driven sink configuration simpler and stable.
 - This type is consumed by `build_logger(...)` and `parse_and_build_logger(...)`.
+- `build_logger(...)` maps `kind` to the concrete base runtime sink: `Console`, `JsonConsole`, and `TextConsole` build their matching console sink variants, while `File` builds a file sink using `path`, `append`, `auto_flush`, `rotation`, and text formatting derived from `text_formatter`.
+- The constructor itself does not reject an empty file path, but JSON parsing does: `parse_logger_config_text(...)` raises `ConfigError` when `kind=File` and `path` is empty.
+- The same `text_formatter` field is also reused by the direct async text-builder path when `build_async_text_logger(...)` or its facade variants create `FormattedConsoleSink` values.
 
 ### How to Use
 
@@ -91,3 +94,5 @@ e.g.:
 1. This type is sink-shape configuration, not the runtime sink itself.
 
 2. Use `sink_config_to_json(...)` and `stringify_sink_config(...)` for export.
+
+3. Use `default_sink_config()` when callers want the standard console default without spelling out every sink field.