From 80f15cd4554957fd56183685e1b1489dccbcd011 Mon Sep 17 00:00:00 2001 From: Nanaloveyuki Date: Tue, 12 May 2026 13:47:04 +0800 Subject: [PATCH] :memo: Polish API doc consistency and scope --- docs/api/async-logger-build-config-to-json.md | 6 ------ docs/api/async-logger-config-to-json.md | 6 ------ docs/api/async-logger-config.md | 3 +-- docs/api/async-logger-state.md | 5 ++--- docs/api/async-runtime-mode-label.md | 6 ------ docs/api/async-runtime-state-to-json.md | 6 ------ docs/api/async-runtime-state.md | 5 ++--- docs/api/logger-config-to-json.md | 6 ------ docs/api/logger-config.md | 3 +-- docs/api/logger-with-min-level.md | 6 ------ docs/api/queue-config-to-json.md | 6 ------ docs/api/queue-config.md | 3 +-- docs/api/sink-config-to-json.md | 6 ------ docs/api/sink-config.md | 3 +-- docs/api/stringify-async-logger-build-config.md | 6 ------ docs/api/stringify-async-logger-config.md | 6 ------ docs/api/stringify-async-logger-state.md | 6 ------ docs/api/stringify-async-runtime-state.md | 6 ------ docs/api/stringify-logger-config.md | 6 ------ docs/api/stringify-queue-config.md | 6 ------ docs/api/stringify-sink-config.md | 6 ------ docs/api/stringify-text-formatter-config.md | 6 ------ docs/api/text-formatter-config-to-json.md | 6 ------ docs/api/text-formatter-config.md | 3 +-- 24 files changed, 9 insertions(+), 118 deletions(-) diff --git a/docs/api/async-logger-build-config-to-json.md b/docs/api/async-logger-build-config-to-json.md index 138c547..85c15d6 100644 --- a/docs/api/async-logger-build-config-to-json.md +++ b/docs/api/async-logger-build-config-to-json.md @@ -74,9 +74,3 @@ e.g.: - If callers want direct text output, they should use `stringify_async_logger_build_config(...)` instead. -### Notes - -1. This helper exports complete build settings, not runtime state. - -2. It is useful for generated configs, test fixtures, and setup introspection. - diff --git a/docs/api/async-logger-config-to-json.md b/docs/api/async-logger-config-to-json.md index 4653b31..cfce60b 100644 --- a/docs/api/async-logger-config-to-json.md +++ b/docs/api/async-logger-config-to-json.md @@ -69,9 +69,3 @@ e.g.: - If callers want direct text output instead of a JSON value, they should use `stringify_async_logger_config(...)` instead. -### Notes - -1. This helper exports config data, not runtime counters or failure state. - -2. Use it when downstream code expects `JsonValue`. - diff --git a/docs/api/async-logger-config.md b/docs/api/async-logger-config.md index 9e99e81..c9c28e5 100644 --- a/docs/api/async-logger-config.md +++ b/docs/api/async-logger-config.md @@ -3,7 +3,7 @@ name: async-logger-config group: api category: async update-time: 20260512 -description: Build the queue, batching, linger, and flush policy config used by async loggers. +description: Create the queue, batching, linger, and flush policy config used by async loggers. key-word: - async - config @@ -88,4 +88,3 @@ e.g.: 1. This type controls async runtime behavior, not synchronous queue wrapping. 2. Prefer explicit values for production services so overflow and flush semantics are visible. - diff --git a/docs/api/async-logger-state.md b/docs/api/async-logger-state.md index 00d3193..c02c17d 100644 --- a/docs/api/async-logger-state.md +++ b/docs/api/async-logger-state.md @@ -3,7 +3,7 @@ name: async-logger-state group: api category: async update-time: 20260512 -description: Read and serialize a full async logger runtime snapshot including queue counters, lifecycle flags, and runtime mode. +description: Read a full async logger runtime snapshot including queue counters, lifecycle flags, and runtime mode. key-word: - async - state @@ -13,7 +13,7 @@ key-word: ## Async-logger-state -Read a complete async logger runtime snapshot and serialize it for diagnostics. This API is the preferred way to export queue backlog, dropped counts, lifecycle status, and runtime mode in startup logs, health endpoints, or failure reports. +Read a complete async logger runtime snapshot for diagnostics. This API is the preferred way to inspect queue backlog, dropped counts, lifecycle status, and runtime mode before exporting them through JSON helpers when needed. ### Interface @@ -78,4 +78,3 @@ e.g.: 1. Prefer this API over manually combining `pending_count()`, `dropped_count()`, and runtime-mode helpers. 2. Use `pretty=true` when emitting logs for humans and the compact form for machine-oriented payloads. - diff --git a/docs/api/async-runtime-mode-label.md b/docs/api/async-runtime-mode-label.md index 62c029c..45b2732 100644 --- a/docs/api/async-runtime-mode-label.md +++ b/docs/api/async-runtime-mode-label.md @@ -67,9 +67,3 @@ e.g.: - If callers need the whole runtime object rather than a string label, use `async_runtime_state()`. -### Notes - -1. Prefer this helper over repeated manual `match` blocks when only a label is needed. - -2. The label format is especially useful for JSON and telemetry. - diff --git a/docs/api/async-runtime-state-to-json.md b/docs/api/async-runtime-state-to-json.md index 248c621..ea6e5f6 100644 --- a/docs/api/async-runtime-state-to-json.md +++ b/docs/api/async-runtime-state-to-json.md @@ -67,9 +67,3 @@ e.g.: - If the runtime is in compatibility mode, the helper still serializes normally using the matching mode label. -### Notes - -1. This helper exports runtime capability state, not logger workload state. - -2. Use it with `async_runtime_state()` for a fresh snapshot. - diff --git a/docs/api/async-runtime-state.md b/docs/api/async-runtime-state.md index 90a1d92..50a959f 100644 --- a/docs/api/async-runtime-state.md +++ b/docs/api/async-runtime-state.md @@ -3,7 +3,7 @@ name: async-runtime-state group: api category: async update-time: 20260512 -description: Read and serialize the current backend-specific async runtime mode and worker capability. +description: Read the current backend-specific async runtime mode and worker capability. key-word: - async - runtime @@ -13,7 +13,7 @@ key-word: ## Async-runtime-state -Read the current backend-specific async runtime state and serialize it for diagnostics. This API focuses on the environment-level async mode rather than any one logger instance. +Read the current backend-specific async runtime state for diagnostics. This API focuses on the environment-level async mode rather than any one logger instance. ### Interface @@ -75,4 +75,3 @@ e.g.: 1. Use this API for environment-level diagnostics. 2. Use `AsyncLogger::state()` for logger-instance diagnostics. - diff --git a/docs/api/logger-config-to-json.md b/docs/api/logger-config-to-json.md index 4a6410b..b286794 100644 --- a/docs/api/logger-config-to-json.md +++ b/docs/api/logger-config-to-json.md @@ -67,9 +67,3 @@ 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 API when you need a JSON value instead of text output. - -2. Use `stringify_logger_config(...)` for immediate string output. - diff --git a/docs/api/logger-config.md b/docs/api/logger-config.md index 247441d..8e45ca9 100644 --- a/docs/api/logger-config.md +++ b/docs/api/logger-config.md @@ -3,7 +3,7 @@ name: logger-config group: api category: config update-time: 20260512 -description: Build the main logger configuration object used by config-driven runtime logger assembly. +description: Create the main logger configuration object used by config-driven runtime logger assembly. key-word: - logger - config @@ -88,4 +88,3 @@ 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. - diff --git a/docs/api/logger-with-min-level.md b/docs/api/logger-with-min-level.md index e1c77aa..266dcfe 100644 --- a/docs/api/logger-with-min-level.md +++ b/docs/api/logger-with-min-level.md @@ -70,9 +70,3 @@ e.g.: - If callers need richer predicate logic than a simple threshold, `with_filter(...)` should be used instead. -### Notes - -1. This API is the cheapest built-in severity gate. - -2. Use it before adding more complex filtering rules. - diff --git a/docs/api/queue-config-to-json.md b/docs/api/queue-config-to-json.md index b631807..8f3d010 100644 --- a/docs/api/queue-config-to-json.md +++ b/docs/api/queue-config-to-json.md @@ -69,9 +69,3 @@ e.g.: - If callers need direct text output instead of a JSON value, they should use `stringify_queue_config(...)` instead. -### Notes - -1. This helper exports config data, not queue runtime metrics. - -2. Use this API when downstream code expects `JsonValue`. - diff --git a/docs/api/queue-config.md b/docs/api/queue-config.md index 13c063e..b17f08a 100644 --- a/docs/api/queue-config.md +++ b/docs/api/queue-config.md @@ -3,7 +3,7 @@ name: queue-config group: api category: config update-time: 20260512 -description: Build a serializable queue wrapper config for configured synchronous loggers. +description: Create a serializable queue wrapper config for configured synchronous loggers. key-word: - queue - config @@ -77,4 +77,3 @@ 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. - diff --git a/docs/api/sink-config-to-json.md b/docs/api/sink-config-to-json.md index 084a942..e68e0a2 100644 --- a/docs/api/sink-config-to-json.md +++ b/docs/api/sink-config-to-json.md @@ -67,9 +67,3 @@ e.g.: - If file-related fields are unused by the sink kind, they are still exported according to the stable config shape. -### Notes - -1. This API is sink-config export only, not runtime sink inspection. - -2. Use `stringify_sink_config(...)` for direct string output. - diff --git a/docs/api/sink-config.md b/docs/api/sink-config.md index 77a5abd..3ef2b48 100644 --- a/docs/api/sink-config.md +++ b/docs/api/sink-config.md @@ -3,7 +3,7 @@ name: sink-config group: api category: config update-time: 20260512 -description: Build a typed sink configuration for config-driven logger assembly. +description: Create a typed sink configuration for config-driven logger assembly. key-word: - sink - config @@ -91,4 +91,3 @@ 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. - diff --git a/docs/api/stringify-async-logger-build-config.md b/docs/api/stringify-async-logger-build-config.md index b1535b0..22eacf0 100644 --- a/docs/api/stringify-async-logger-build-config.md +++ b/docs/api/stringify-async-logger-build-config.md @@ -73,9 +73,3 @@ e.g.: - If only one layer of config is required, this helper may be broader than necessary. -### Notes - -1. This API exports build config data, not runtime logger diagnostics. - -2. Use `pretty=true` for docs, debugging, and support output. - diff --git a/docs/api/stringify-async-logger-config.md b/docs/api/stringify-async-logger-config.md index 810ff7b..dcad601 100644 --- a/docs/api/stringify-async-logger-config.md +++ b/docs/api/stringify-async-logger-config.md @@ -70,9 +70,3 @@ e.g.: - If invalid constructor inputs were normalized earlier, the resulting text contains the normalized config values. -### Notes - -1. This API is convenient for config snapshots, examples, and tests. - -2. Use `pretty=true` when readability matters. - diff --git a/docs/api/stringify-async-logger-state.md b/docs/api/stringify-async-logger-state.md index f3e4c44..c87d6cb 100644 --- a/docs/api/stringify-async-logger-state.md +++ b/docs/api/stringify-async-logger-state.md @@ -71,9 +71,3 @@ e.g.: - If callers need a JSON value instead of text, they should use `async_logger_state_to_json(...)` instead. -### Notes - -1. This API is the most convenient direct output path for async logger snapshots. - -2. Use `pretty=true` for humans and the default compact mode for machine-oriented logs. - diff --git a/docs/api/stringify-async-runtime-state.md b/docs/api/stringify-async-runtime-state.md index f76c9fd..fa6b5fd 100644 --- a/docs/api/stringify-async-runtime-state.md +++ b/docs/api/stringify-async-runtime-state.md @@ -71,9 +71,3 @@ e.g.: - If more complete async logger diagnostics are required, this helper should be replaced with `stringify_async_logger_state(...)`. -### Notes - -1. This API reports runtime capability state only. - -2. `pretty=true` is more suitable for humans and support output. - diff --git a/docs/api/stringify-logger-config.md b/docs/api/stringify-logger-config.md index d550fe7..5dcc054 100644 --- a/docs/api/stringify-logger-config.md +++ b/docs/api/stringify-logger-config.md @@ -68,9 +68,3 @@ e.g.: - If config contains optional `queue=None`, the output omits that section rather than failing. -### Notes - -1. This API is ideal for generated examples and stored config payloads. - -2. Use `pretty=true` when readability matters. - diff --git a/docs/api/stringify-queue-config.md b/docs/api/stringify-queue-config.md index b573a21..2aff20c 100644 --- a/docs/api/stringify-queue-config.md +++ b/docs/api/stringify-queue-config.md @@ -70,9 +70,3 @@ e.g.: - If queue policy is too aggressive for workload burst size, serialization still succeeds because this helper only exports config. -### Notes - -1. This API is convenient for generated config text and tests. - -2. Use `pretty=true` when the output is intended for humans. - diff --git a/docs/api/stringify-sink-config.md b/docs/api/stringify-sink-config.md index 35004b3..06e6500 100644 --- a/docs/api/stringify-sink-config.md +++ b/docs/api/stringify-sink-config.md @@ -68,9 +68,3 @@ e.g.: - If optional `rotation` is absent, the serialized sink config simply omits that field. -### Notes - -1. This helper is convenient for documentation, examples, and generated config output. - -2. Use `pretty=true` when humans are the primary audience. - diff --git a/docs/api/stringify-text-formatter-config.md b/docs/api/stringify-text-formatter-config.md index a6d76f5..db9053e 100644 --- a/docs/api/stringify-text-formatter-config.md +++ b/docs/api/stringify-text-formatter-config.md @@ -73,9 +73,3 @@ e.g.: - If `style_tags` is empty, the serialized text omits that field rather than forcing an empty object. -### Notes - -1. This helper is useful for config snapshots, examples, and tests. - -2. Use `pretty=true` when readability matters. - diff --git a/docs/api/text-formatter-config-to-json.md b/docs/api/text-formatter-config-to-json.md index aefaa99..a098abf 100644 --- a/docs/api/text-formatter-config-to-json.md +++ b/docs/api/text-formatter-config-to-json.md @@ -69,9 +69,3 @@ e.g.: - If callers need immediate text output rather than a JSON value, they should use `stringify_text_formatter_config(...)` instead. -### Notes - -1. This helper exports formatter configuration, not rendered log output. - -2. Use it when downstream code expects `JsonValue`. - diff --git a/docs/api/text-formatter-config.md b/docs/api/text-formatter-config.md index 7a9f6c6..a87b1f9 100644 --- a/docs/api/text-formatter-config.md +++ b/docs/api/text-formatter-config.md @@ -3,7 +3,7 @@ name: text-formatter-config group: api category: config update-time: 20260512 -description: Build a serializable formatter config object that bridges JSON config and runtime text formatting. +description: Create a serializable formatter config object that bridges JSON config and runtime text formatting. key-word: - formatter - config @@ -93,4 +93,3 @@ 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. -