📝 Refine API doc notes and guidance

docs/api/.example.md

@@ -99,16 +99,10 @@ e.g.:
 
 ### Notes
 
-Notes are here.
-
 1. ...
 
 2. ...
 
-3. ...
-
-4. ...
-
 ...
 
 ---

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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`.

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.

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.

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.

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.

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(...)`.

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(...)`.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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`.

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(...)`.

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.

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.

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.

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.

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.