From c6c153cf53f9b091d953eff753afdbb6564ed35b Mon Sep 17 00:00:00 2001 From: Nanaloveyuki Date: Tue, 12 May 2026 13:32:15 +0800 Subject: [PATCH] :memo: Refine API doc notes and guidance --- docs/api/.example.md | 6 ------ docs/api/async-logger-build-config-to-json.md | 5 ----- docs/api/async-logger-config-to-json.md | 5 ----- docs/api/async-logger-config.md | 5 ----- docs/api/async-logger-state-to-json.md | 5 ----- docs/api/async-logger-state.md | 5 ----- docs/api/async-logger.md | 5 ----- docs/api/async-runtime-mode-label.md | 5 ----- docs/api/async-runtime-mode.md | 5 ----- docs/api/async-runtime-state-to-json.md | 5 ----- docs/api/async-runtime-state.md | 5 ----- docs/api/async-runtime-supports-background-worker.md | 5 ----- docs/api/build-async-logger.md | 5 ----- docs/api/build-logger.md | 5 ----- docs/api/fields.md | 5 ----- docs/api/file-rotation.md | 5 ----- docs/api/file-sink.md | 5 ----- docs/api/logger-child.md | 5 ----- docs/api/logger-config-to-json.md | 5 ----- docs/api/logger-config.md | 5 ----- docs/api/logger-new.md | 5 ----- docs/api/logger-with-context-fields.md | 5 ----- docs/api/logger-with-filter.md | 5 ----- docs/api/logger-with-min-level.md | 5 ----- docs/api/logger-with-patch.md | 5 ----- docs/api/logger-with-queue.md | 5 ----- docs/api/logger-with-target.md | 5 ----- docs/api/logger-with-timestamp.md | 5 ----- docs/api/parse-and-build-logger.md | 5 ----- docs/api/parse-async-logger-build-config-text.md | 5 ----- docs/api/parse-logger-config-text.md | 5 ----- docs/api/queue-config-to-json.md | 5 ----- docs/api/queue-config.md | 5 ----- docs/api/sink-config-to-json.md | 5 ----- docs/api/sink-config.md | 5 ----- docs/api/stringify-async-logger-build-config.md | 5 ----- docs/api/stringify-async-logger-config.md | 5 ----- docs/api/stringify-async-logger-state.md | 5 ----- docs/api/stringify-async-runtime-state.md | 5 ----- docs/api/stringify-logger-config.md | 5 ----- docs/api/stringify-queue-config.md | 5 ----- docs/api/stringify-sink-config.md | 5 ----- docs/api/stringify-text-formatter-config.md | 5 ----- docs/api/target-has-prefix.md | 5 ----- docs/api/text-formatter-config-to-json.md | 5 ----- docs/api/text-formatter-config.md | 5 ----- docs/api/text-formatter.md | 5 ----- 47 files changed, 236 deletions(-) diff --git a/docs/api/.example.md b/docs/api/.example.md index 9768e9b..ca42ef0 100644 --- a/docs/api/.example.md +++ b/docs/api/.example.md @@ -99,16 +99,10 @@ e.g.: ### Notes -Notes are here. - 1. ... 2. ... -3. ... - -4. ... - ... --- diff --git a/docs/api/async-logger-build-config-to-json.md b/docs/api/async-logger-build-config-to-json.md index c36284c..138c547 100644 --- a/docs/api/async-logger-build-config-to-json.md +++ b/docs/api/async-logger-build-config-to-json.md @@ -76,12 +76,7 @@ e.g.: ### Notes -Notes are here. - 1. This helper exports complete build settings, not runtime state. 2. It is useful for generated configs, test fixtures, and setup introspection. -3. The output combines `LoggerConfig` and `AsyncLoggerConfig` without flattening them. - -4. This API complements `parse_async_logger_build_config_text(...)` in roundtrip workflows. diff --git a/docs/api/async-logger-config-to-json.md b/docs/api/async-logger-config-to-json.md index 7dc5c2e..4653b31 100644 --- a/docs/api/async-logger-config-to-json.md +++ b/docs/api/async-logger-config-to-json.md @@ -71,12 +71,7 @@ e.g.: ### Notes -Notes are here. - 1. This helper exports config data, not runtime counters or failure state. 2. Use it when downstream code expects `JsonValue`. -3. Pair it with `AsyncLoggerConfig::new(...)` for code-generated config. - -4. The output is suitable for persistence, tests, and generated async setup flows. diff --git a/docs/api/async-logger-config.md b/docs/api/async-logger-config.md index b04d78d..9e99e81 100644 --- a/docs/api/async-logger-config.md +++ b/docs/api/async-logger-config.md @@ -85,12 +85,7 @@ e.g.: ### Notes -Notes are here. - 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. -3. Use `stringify_async_logger_config(...)` when exporting diagnostics or generated config. - -4. This API is reused by `AsyncLoggerBuildConfig` rather than duplicated. diff --git a/docs/api/async-logger-state-to-json.md b/docs/api/async-logger-state-to-json.md index 8f64d08..35778f5 100644 --- a/docs/api/async-logger-state-to-json.md +++ b/docs/api/async-logger-state-to-json.md @@ -70,12 +70,7 @@ e.g.: ### Notes -Notes are here. - 1. Use this API when downstream code wants a JSON value rather than a ready-made string. 2. Pair it with `AsyncLogger::state()` to capture the snapshot first. -3. Prefer `stringify_async_logger_state(...)` when direct string output is enough. - -4. This helper is transport-oriented, not control-oriented. diff --git a/docs/api/async-logger-state.md b/docs/api/async-logger-state.md index 849182d..00d3193 100644 --- a/docs/api/async-logger-state.md +++ b/docs/api/async-logger-state.md @@ -75,12 +75,7 @@ e.g.: ### Notes -Notes are here. - 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. -3. This snapshot is especially useful in cross-target deployments where async behavior differs by backend. - -4. `AsyncLoggerState` is diagnostics-oriented and does not control the logger. diff --git a/docs/api/async-logger.md b/docs/api/async-logger.md index 6271f6a..7ecb893 100644 --- a/docs/api/async-logger.md +++ b/docs/api/async-logger.md @@ -94,12 +94,7 @@ e.g.: ### Notes -Notes are here. - 1. `async_logger(...)` is the async counterpart to `Logger::new(...)`. 2. Use `state()`, `pending_count()`, and `dropped_count()` for runtime diagnostics. -3. Prefer `shutdown()` over raw `close()` in normal graceful shutdown paths. - -4. On cross-target code paths, pair this API with `async_runtime_mode()` or `async_runtime_state()` when behavior differences matter. diff --git a/docs/api/async-runtime-mode-label.md b/docs/api/async-runtime-mode-label.md index f6f17c5..62c029c 100644 --- a/docs/api/async-runtime-mode-label.md +++ b/docs/api/async-runtime-mode-label.md @@ -69,12 +69,7 @@ e.g.: ### Notes -Notes are here. - 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. -3. This API complements `async_runtime_mode()` and `async_runtime_state()`. - -4. Keep downstream consumers aligned with these stable labels rather than inventing local variants. diff --git a/docs/api/async-runtime-mode.md b/docs/api/async-runtime-mode.md index eba90d7..c6d8958 100644 --- a/docs/api/async-runtime-mode.md +++ b/docs/api/async-runtime-mode.md @@ -72,12 +72,7 @@ e.g.: ### Notes -Notes are here. - 1. Use this API for minimal mode branching. 2. Use `async_runtime_state()` when you also want worker support packaged into one object. -3. Use `AsyncLogger::state()` when you need logger instance counters and lifecycle flags too. - -4. The enum is intentionally small to keep capability branching simple. diff --git a/docs/api/async-runtime-state-to-json.md b/docs/api/async-runtime-state-to-json.md index 9336ce3..248c621 100644 --- a/docs/api/async-runtime-state-to-json.md +++ b/docs/api/async-runtime-state-to-json.md @@ -69,12 +69,7 @@ e.g.: ### Notes -Notes are here. - 1. This helper exports runtime capability state, not logger workload state. 2. Use it with `async_runtime_state()` for a fresh snapshot. -3. Prefer `stringify_async_runtime_state(...)` when immediate text output is enough. - -4. The output is useful for environment diagnostics across targets. diff --git a/docs/api/async-runtime-state.md b/docs/api/async-runtime-state.md index 77fd26a..90a1d92 100644 --- a/docs/api/async-runtime-state.md +++ b/docs/api/async-runtime-state.md @@ -72,12 +72,7 @@ e.g.: ### Notes -Notes are here. - 1. Use this API for environment-level diagnostics. 2. Use `AsyncLogger::state()` for logger-instance diagnostics. -3. Serialization helpers make this API suitable for health output and startup logs. - -4. This API is especially valuable in cross-target deployments. diff --git a/docs/api/async-runtime-supports-background-worker.md b/docs/api/async-runtime-supports-background-worker.md index d1dd591..c1fd7d4 100644 --- a/docs/api/async-runtime-supports-background-worker.md +++ b/docs/api/async-runtime-supports-background-worker.md @@ -71,12 +71,7 @@ e.g.: ### Notes -Notes are here. - 1. Use this helper for minimal capability checks. 2. Prefer `async_runtime_state()` when you want the same information in a richer object. -3. Prefer `AsyncLogger::state()` when logger-instance counters matter too. - -4. This helper is intentionally small and should stay cheap to call. diff --git a/docs/api/build-async-logger.md b/docs/api/build-async-logger.md index d8ceec6..5022b28 100644 --- a/docs/api/build-async-logger.md +++ b/docs/api/build-async-logger.md @@ -75,12 +75,7 @@ e.g.: ### Notes -Notes are here. - 1. Prefer this API when applications externalize both sync sink choice and async queue behavior. 2. Use `async_logger(...)` directly when you want explicit code-defined sink wiring. -3. This API is the async counterpart to `build_logger(...)`. - -4. The runtime diagnostics surface remains useful after config-built construction. diff --git a/docs/api/build-logger.md b/docs/api/build-logger.md index b74487b..7261ec9 100644 --- a/docs/api/build-logger.md +++ b/docs/api/build-logger.md @@ -79,12 +79,7 @@ e.g.: ### Notes -Notes are here. - 1. Use this API when config is already typed as `LoggerConfig`. 2. Use `parse_and_build_logger(...)` when the starting point is raw JSON text. -3. `ConfiguredLogger` is still a logger, not a separate opaque runtime object. - -4. This API is the sync runtime builder paired with `build_async_logger(...)` for async use cases. diff --git a/docs/api/fields.md b/docs/api/fields.md index 18a68bb..e0152aa 100644 --- a/docs/api/fields.md +++ b/docs/api/fields.md @@ -70,12 +70,7 @@ e.g.: ### Notes -Notes are here. - 1. Use `field(...)` when only one field is needed. 2. Use `fields(...)` when tuple syntax improves readability. -3. This helper preserves order. - -4. No special deduplication or normalization is performed. diff --git a/docs/api/file-rotation.md b/docs/api/file-rotation.md index 5299b3c..a3ed8e5 100644 --- a/docs/api/file-rotation.md +++ b/docs/api/file-rotation.md @@ -75,12 +75,7 @@ e.g.: ### Notes -Notes are here. - 1. This API defines policy only; it does not open files by itself. 2. Rotation currently focuses on size thresholds rather than time schedules or compression. -3. Use with `file_sink(...)` on native-capable backends only. - -4. Policy values can later be inspected through file sink state helpers. diff --git a/docs/api/file-sink.md b/docs/api/file-sink.md index c920571..650b6aa 100644 --- a/docs/api/file-sink.md +++ b/docs/api/file-sink.md @@ -87,12 +87,7 @@ e.g.: ### Notes -Notes are here. - 1. Always pair this API with `native_files_supported()` in cross-target code. 2. Prefer `state()`, `policy()`, and failure counters when integrating diagnostics. -3. Use `reopen_append()` and `reopen_truncate()` for common recovery flows instead of raw `reopen(...)` where possible. - -4. For config-driven file logging, the mirrored control surface is exposed through `ConfiguredLogger` and `RuntimeSink`. diff --git a/docs/api/logger-child.md b/docs/api/logger-child.md index cd5c9c0..872f2be 100644 --- a/docs/api/logger-child.md +++ b/docs/api/logger-child.md @@ -73,12 +73,7 @@ e.g.: ### Notes -Notes are here. - 1. This is the preferred API for hierarchical logger naming. 2. Composition uses `.` as the separator between parent and child segments. -3. The original logger is not mutated. - -4. This API works well with `with_context_fields(...)` to align target and metadata scopes. diff --git a/docs/api/logger-config-to-json.md b/docs/api/logger-config-to-json.md index b6b5fa1..4a6410b 100644 --- a/docs/api/logger-config-to-json.md +++ b/docs/api/logger-config-to-json.md @@ -69,12 +69,7 @@ e.g.: ### Notes -Notes are here. - 1. Use this API when you need a JSON value instead of text output. 2. Use `stringify_logger_config(...)` for immediate string output. -3. This helper complements `parse_logger_config_text(...)` for roundtrip workflows. - -4. The output is configuration-oriented, not runtime-state-oriented. diff --git a/docs/api/logger-config.md b/docs/api/logger-config.md index e1e9509..247441d 100644 --- a/docs/api/logger-config.md +++ b/docs/api/logger-config.md @@ -85,12 +85,7 @@ e.g.: ### Notes -Notes are here. - 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 `logger_config_to_json(...)` and `stringify_logger_config(...)` for export. - -4. `AsyncLoggerBuildConfig` reuses this type rather than inventing a second sync logger schema. diff --git a/docs/api/logger-new.md b/docs/api/logger-new.md index a21edcb..6732f5a 100644 --- a/docs/api/logger-new.md +++ b/docs/api/logger-new.md @@ -76,12 +76,7 @@ e.g.: ### Notes -Notes are here. - 1. This API is synchronous and does not create buffering or background execution by itself. 2. The returned sink type stays visible in `Logger[S]`, which is useful for typed composition. -3. Prefer `Logger::new(...)` over global helpers when you want explicit control over sink, target, and level. - -4. `Logger::new(...)` is the correct starting point for both public app logging and internal composed sink pipelines. diff --git a/docs/api/logger-with-context-fields.md b/docs/api/logger-with-context-fields.md index cdb3ca8..c5d55f4 100644 --- a/docs/api/logger-with-context-fields.md +++ b/docs/api/logger-with-context-fields.md @@ -77,12 +77,7 @@ e.g.: ### Notes -Notes are here. - 1. Use this for stable metadata, not highly dynamic event-specific values. 2. Prefer `fields([("k", "v")])` when you want a more ergonomic call site. -3. This API composes naturally with `with_filter(...)`, `with_patch(...)`, and `with_queue(...)`. - -4. If you want an alias with the same semantics, use `bind(...)`. diff --git a/docs/api/logger-with-filter.md b/docs/api/logger-with-filter.md index 6b8763e..29c8d75 100644 --- a/docs/api/logger-with-filter.md +++ b/docs/api/logger-with-filter.md @@ -77,12 +77,7 @@ e.g.: ### Notes -Notes are here. - 1. Use this API for selection logic, not record mutation. 2. Prefer helper predicates for readability and reuse. -3. Filtering occurs before sink write, so it is cheaper than post-processing output. - -4. If you need record modification too, combine this API with `with_patch(...)`. diff --git a/docs/api/logger-with-min-level.md b/docs/api/logger-with-min-level.md index 7b8a542..e1c77aa 100644 --- a/docs/api/logger-with-min-level.md +++ b/docs/api/logger-with-min-level.md @@ -72,12 +72,7 @@ e.g.: ### Notes -Notes are here. - 1. This API is the cheapest built-in severity gate. 2. Use it before adding more complex filtering rules. -3. It composes cleanly with target, patch, and context-field helpers. - -4. The original logger is unchanged because a new value is returned. diff --git a/docs/api/logger-with-patch.md b/docs/api/logger-with-patch.md index 7f26ddf..57c6666 100644 --- a/docs/api/logger-with-patch.md +++ b/docs/api/logger-with-patch.md @@ -77,12 +77,7 @@ e.g.: ### Notes -Notes are here. - 1. Use patches for transformation, not filtering decisions. 2. Prefer helper patches such as `prefix_message(...)`, `append_fields(...)`, and `redact_fields(...)` for common cases. -3. Patch composition order matters. - -4. Combine with `with_filter(...)` when both selection and rewriting are required. diff --git a/docs/api/logger-with-queue.md b/docs/api/logger-with-queue.md index 5dfe58b..bb211c8 100644 --- a/docs/api/logger-with-queue.md +++ b/docs/api/logger-with-queue.md @@ -83,12 +83,7 @@ e.g.: ### Notes -Notes are here. - 1. Use this API when you want explicit bounded buffering without `bitlogger_async`. 2. `with_queue(...)` preserves the normal synchronous logger call style. -3. Always define when and where the queue will be drained. - -4. For background queue draining, prefer `bitlogger_async` instead. diff --git a/docs/api/logger-with-target.md b/docs/api/logger-with-target.md index 29dfa1c..b9d4201 100644 --- a/docs/api/logger-with-target.md +++ b/docs/api/logger-with-target.md @@ -75,12 +75,7 @@ e.g.: ### Notes -Notes are here. - 1. Use this API for replacement, not hierarchical composition. 2. It is useful when one sink serves several target namespaces. -3. Per-call `target?` still has higher priority for that one log record. - -4. Pair it with `child(...)` when both replacement and composition are needed in different stages. diff --git a/docs/api/logger-with-timestamp.md b/docs/api/logger-with-timestamp.md index 894f6aa..a5eb73e 100644 --- a/docs/api/logger-with-timestamp.md +++ b/docs/api/logger-with-timestamp.md @@ -72,12 +72,7 @@ e.g.: ### Notes -Notes are here. - 1. This API controls record creation, not formatter display policy. 2. It works well together with text formatters that optionally show timestamps. -3. The helper is useful for tests, deterministic snapshots, and production timing. - -4. The returned logger preserves the same sink, target, and min level settings. diff --git a/docs/api/parse-and-build-logger.md b/docs/api/parse-and-build-logger.md index bf0aafb..d593d02 100644 --- a/docs/api/parse-and-build-logger.md +++ b/docs/api/parse-and-build-logger.md @@ -82,12 +82,7 @@ e.g.: ### Notes -Notes are here. - 1. Use `parse_logger_config_text(...)` first if you want to validate and inspect config separately. 2. Prefer this API for app bootstrapping paths that read config once and then construct the runtime logger. -3. `ConfiguredLogger` keeps queue and file helper methods, so config-driven logging does not lose control surface. - -4. Keep the JSON schema limited to supported built-in sink shapes when designing external config files. diff --git a/docs/api/parse-async-logger-build-config-text.md b/docs/api/parse-async-logger-build-config-text.md index 2eacdd6..c5424ea 100644 --- a/docs/api/parse-async-logger-build-config-text.md +++ b/docs/api/parse-async-logger-build-config-text.md @@ -75,12 +75,7 @@ e.g.: ### Notes -Notes are here. - 1. Use this API when async build config is stored as JSON. 2. Use `AsyncLoggerBuildConfig::new(...)` when assembling config directly in code. -3. Pair this API with `build_async_logger(...)` after validation. - -4. The split `logger` plus `async_config` shape keeps sync and async concerns explicit. diff --git a/docs/api/parse-logger-config-text.md b/docs/api/parse-logger-config-text.md index 82dfb80..a28f5c7 100644 --- a/docs/api/parse-logger-config-text.md +++ b/docs/api/parse-logger-config-text.md @@ -75,12 +75,7 @@ e.g.: ### Notes -Notes are here. - 1. Prefer this API when you need typed config inspection before building. 2. Prefer `parse_and_build_logger(...)` when one-step bootstrapping is enough. -3. Keep external config files aligned with the supported stable schema. - -4. Parsed config remains reusable across multiple runtime builders if needed. diff --git a/docs/api/queue-config-to-json.md b/docs/api/queue-config-to-json.md index ddb3c27..b631807 100644 --- a/docs/api/queue-config-to-json.md +++ b/docs/api/queue-config-to-json.md @@ -71,12 +71,7 @@ e.g.: ### Notes -Notes are here. - 1. This helper exports config data, not queue runtime metrics. 2. Use this API when downstream code expects `JsonValue`. -3. Pair it with `QueueConfig::new(...)` for code-generated config. - -4. The output is suitable for persistence, testing, and generated configuration flows. diff --git a/docs/api/queue-config.md b/docs/api/queue-config.md index e2722ac..13c063e 100644 --- a/docs/api/queue-config.md +++ b/docs/api/queue-config.md @@ -74,12 +74,7 @@ e.g.: ### Notes -Notes are here. - 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. Pair with `stringify_queue_config(...)` when inspecting generated config output. - -4. Queue capacity policy should be chosen based on expected burst size and acceptable loss behavior. diff --git a/docs/api/sink-config-to-json.md b/docs/api/sink-config-to-json.md index 5d4d2c6..084a942 100644 --- a/docs/api/sink-config-to-json.md +++ b/docs/api/sink-config-to-json.md @@ -69,12 +69,7 @@ e.g.: ### Notes -Notes are here. - 1. This API is sink-config export only, not runtime sink inspection. 2. Use `stringify_sink_config(...)` for direct string output. -3. This helper is reused by `logger_config_to_json(...)`. - -4. It is useful for tooling that needs nested config JSON values. diff --git a/docs/api/sink-config.md b/docs/api/sink-config.md index e578d37..77a5abd 100644 --- a/docs/api/sink-config.md +++ b/docs/api/sink-config.md @@ -88,12 +88,7 @@ e.g.: ### Notes -Notes are here. - 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. Prefer `SinkConfig::new(...)` over raw JSON when config is assembled programmatically. - -4. `LoggerConfig` embeds exactly one `SinkConfig` plus an optional outer queue config. diff --git a/docs/api/stringify-async-logger-build-config.md b/docs/api/stringify-async-logger-build-config.md index b10962f..b1535b0 100644 --- a/docs/api/stringify-async-logger-build-config.md +++ b/docs/api/stringify-async-logger-build-config.md @@ -75,12 +75,7 @@ e.g.: ### Notes -Notes are here. - 1. This API exports build config data, not runtime logger diagnostics. 2. Use `pretty=true` for docs, debugging, and support output. -3. Compact mode is better for machine-oriented storage. - -4. This helper is useful when generated async setup should be inspected as one payload. diff --git a/docs/api/stringify-async-logger-config.md b/docs/api/stringify-async-logger-config.md index d902eea..810ff7b 100644 --- a/docs/api/stringify-async-logger-config.md +++ b/docs/api/stringify-async-logger-config.md @@ -72,12 +72,7 @@ e.g.: ### Notes -Notes are here. - 1. This API is convenient for config snapshots, examples, and tests. 2. Use `pretty=true` when readability matters. -3. Compact mode is a better default for machine-oriented output. - -4. This helper exports async config data, not runtime logger state. diff --git a/docs/api/stringify-async-logger-state.md b/docs/api/stringify-async-logger-state.md index b6c128a..f3e4c44 100644 --- a/docs/api/stringify-async-logger-state.md +++ b/docs/api/stringify-async-logger-state.md @@ -73,12 +73,7 @@ e.g.: ### Notes -Notes are here. - 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. -3. Pair with `AsyncLogger::state()` to capture a consistent point-in-time snapshot. - -4. This helper is ideal for startup, shutdown, and failure reporting. diff --git a/docs/api/stringify-async-runtime-state.md b/docs/api/stringify-async-runtime-state.md index 2e10254..f76c9fd 100644 --- a/docs/api/stringify-async-runtime-state.md +++ b/docs/api/stringify-async-runtime-state.md @@ -73,12 +73,7 @@ e.g.: ### Notes -Notes are here. - 1. This API reports runtime capability state only. 2. `pretty=true` is more suitable for humans and support output. -3. The compact default is better for transport and structured logging. - -4. This helper is useful when comparing target-specific async runtime behavior. diff --git a/docs/api/stringify-logger-config.md b/docs/api/stringify-logger-config.md index 6fcb42a..d550fe7 100644 --- a/docs/api/stringify-logger-config.md +++ b/docs/api/stringify-logger-config.md @@ -70,12 +70,7 @@ e.g.: ### Notes -Notes are here. - 1. This API is ideal for generated examples and stored config payloads. 2. Use `pretty=true` when readability matters. -3. Pair with `parse_logger_config_text(...)` for roundtrip validation workflows. - -4. The output describes config, not runtime sink state. diff --git a/docs/api/stringify-queue-config.md b/docs/api/stringify-queue-config.md index 1aa43b2..b573a21 100644 --- a/docs/api/stringify-queue-config.md +++ b/docs/api/stringify-queue-config.md @@ -72,12 +72,7 @@ e.g.: ### Notes -Notes are here. - 1. This API is convenient for generated config text and tests. 2. Use `pretty=true` when the output is intended for humans. -3. The compact default is better for snapshots and transport. - -4. This helper belongs to synchronous configured queue wrapping, not `bitlogger_async`. diff --git a/docs/api/stringify-sink-config.md b/docs/api/stringify-sink-config.md index 37bc661..35004b3 100644 --- a/docs/api/stringify-sink-config.md +++ b/docs/api/stringify-sink-config.md @@ -70,12 +70,7 @@ e.g.: ### Notes -Notes are here. - 1. This helper is convenient for documentation, examples, and generated config output. 2. Use `pretty=true` when humans are the primary audience. -3. The output describes the config schema, not live runtime sink state. - -4. This API pairs naturally with `SinkConfig::new(...)` and `sink_config_to_json(...)`. diff --git a/docs/api/stringify-text-formatter-config.md b/docs/api/stringify-text-formatter-config.md index d96b830..a6d76f5 100644 --- a/docs/api/stringify-text-formatter-config.md +++ b/docs/api/stringify-text-formatter-config.md @@ -75,12 +75,7 @@ e.g.: ### Notes -Notes are here. - 1. This helper is useful for config snapshots, examples, and tests. 2. Use `pretty=true` when readability matters. -3. Compact mode is a better default for machine-oriented output. - -4. This API exports config data, not formatted records. diff --git a/docs/api/target-has-prefix.md b/docs/api/target-has-prefix.md index 827c4ca..e57c7ae 100644 --- a/docs/api/target-has-prefix.md +++ b/docs/api/target-has-prefix.md @@ -75,12 +75,7 @@ e.g.: ### Notes -Notes are here. - 1. This helper is most useful when targets are structured hierarchically. 2. Prefer this helper over ad hoc inline prefix logic for readability. -3. Use `target_is(...)` instead when exact equality is required. - -4. Combine with `message_contains(...)` or field predicates for narrower routing rules. diff --git a/docs/api/text-formatter-config-to-json.md b/docs/api/text-formatter-config-to-json.md index 56d6162..aefaa99 100644 --- a/docs/api/text-formatter-config-to-json.md +++ b/docs/api/text-formatter-config-to-json.md @@ -71,12 +71,7 @@ e.g.: ### Notes -Notes are here. - 1. This helper exports formatter configuration, not rendered log output. 2. Use it when downstream code expects `JsonValue`. -3. Pair it with `TextFormatterConfig::new(...)` for code-generated formatter policies. - -4. The output is compatible with config roundtrip workflows. diff --git a/docs/api/text-formatter-config.md b/docs/api/text-formatter-config.md index 440e3c8..7a9f6c6 100644 --- a/docs/api/text-formatter-config.md +++ b/docs/api/text-formatter-config.md @@ -90,12 +90,7 @@ e.g.: ### Notes -Notes are here. - 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. `to_formatter()` is the key bridge from config to runtime behavior. - -4. This type is central to config-driven text sink assembly. diff --git a/docs/api/text-formatter.md b/docs/api/text-formatter.md index 7abf4c1..3188047 100644 --- a/docs/api/text-formatter.md +++ b/docs/api/text-formatter.md @@ -102,12 +102,7 @@ e.g.: ### Notes -Notes are here. - 1. Prefer `text_formatter(...)` when you want explicit control over readable text output. 2. `TextFormatter` is reusable and should usually be constructed once, then shared. -3. `fields_style_markup` currently affects field values only, not field keys. - -4. Use `TextFormatterConfig` when the formatter must be driven by JSON config rather than code.