From 323d58059bd2b3d925fe23982460b245c5a5c4ad Mon Sep 17 00:00:00 2001 From: Nanaloveyuki Date: Sun, 14 Jun 2026 01:43:27 +0800 Subject: [PATCH] :memo: refine formatter config docs --- docs/api/default-text-formatter-config.md | 3 +++ docs/api/text-formatter-config-to-formatter.md | 3 ++- docs/api/text-formatter-config.md | 4 ++++ 3 files changed, 9 insertions(+), 1 deletion(-) diff --git a/docs/api/default-text-formatter-config.md b/docs/api/default-text-formatter-config.md index 02e8bcb..74ff01e 100644 --- a/docs/api/default-text-formatter-config.md +++ b/docs/api/default-text-formatter-config.md @@ -30,6 +30,7 @@ pub fn default_text_formatter_config() -> TextFormatterConfig { Detailed rules explaining key parameters and behaviors - This helper returns the same baseline config value used by `text_console(...)`, `file(...)`, and `SinkConfig::new(...)` defaults. +- The implementation is exactly `TextFormatterConfig::new()`, so it stays aligned with the constructor defaults rather than duplicating a separate preset object. - It is a config object, not a runtime `TextFormatter`. - Call `to_formatter()` when a runtime formatter is needed. @@ -58,3 +59,5 @@ e.g.: 1. Use this helper for explicit config composition. 2. Use `text_formatter(...)` when you want a runtime formatter directly. + +3. `parse_logger_config_text(...)` also falls back to this same baseline when a sink omits its nested `text_formatter` object. diff --git a/docs/api/text-formatter-config-to-formatter.md b/docs/api/text-formatter-config-to-formatter.md index c4a913f..49c4319 100644 --- a/docs/api/text-formatter-config-to-formatter.md +++ b/docs/api/text-formatter-config-to-formatter.md @@ -35,8 +35,9 @@ Detailed rules explaining key parameters and behaviors - This helper forwards the stored visibility flags, separators, template, color settings, and markup settings into `text_formatter(...)`. - When `style_tags` is empty, the runtime formatter is built without a local style-tag registry. -- When `style_tags` is non-empty, the config map is converted into a fresh `StyleTagRegistry` before formatter construction. +- When `style_tags` is non-empty, the config map is converted into a fresh `StyleTagRegistry` and each stored tag is registered on that new registry before formatter construction. - This conversion does not mutate the source config object. +- Sync and async config-driven builder paths both rely on this helper when a text formatter config must become a concrete runtime formatter. ### How to Use diff --git a/docs/api/text-formatter-config.md b/docs/api/text-formatter-config.md index a87b1f9..fdc06ae 100644 --- a/docs/api/text-formatter-config.md +++ b/docs/api/text-formatter-config.md @@ -52,6 +52,8 @@ Detailed rules explaining key parameters and behaviors - `to_formatter()` converts config into a runtime `TextFormatter`. - `style_tags` are stored as concrete style objects instead of alias-style runtime behavior. - This config type is used by `SinkConfig`, `LoggerConfig`, and config-driven sink assembly. +- The constructor defaults match the parser defaults: timestamps, level, target, and fields are shown by default; separators default to a single space; `template` defaults to empty; `color_mode` defaults to `Never`; `color_support` defaults to `TrueColor`; `style_markup` defaults to `Full`; and target/field-specific markup defaults to `Disabled`. +- `parse_logger_config_text(...)` rehydrates formatter config through this same constructor path, so omitted formatter fields fall back to the same defaults whether config is built in code or parsed from JSON. ### How to Use @@ -93,3 +95,5 @@ e.g.: 1. Prefer this API when formatter behavior must be stored, parsed, or serialized. 2. Prefer `text_formatter(...)` when writing direct runtime code without config. + +3. Use `default_text_formatter_config()` when callers want the standard formatter baseline without spelling out every field manually.