From 4d2e3def144f76e80b1df5d1d365c85cd2975f96 Mon Sep 17 00:00:00 2001 From: Nanaloveyuki Date: Sun, 14 Jun 2026 01:23:15 +0800 Subject: [PATCH] :memo: align facade overview docs --- docs/api/async-logger-type.md | 7 +++++-- docs/api/configured-logger.md | 5 ++++- docs/api/logger.md | 7 ++++++- 3 files changed, 15 insertions(+), 4 deletions(-) diff --git a/docs/api/async-logger-type.md b/docs/api/async-logger-type.md index 12b8978..c52d70c 100644 --- a/docs/api/async-logger-type.md +++ b/docs/api/async-logger-type.md @@ -55,6 +55,7 @@ Detailed rules explaining key parameters and behaviors - `pending_count`, `dropped_count`, `is_closed`, `is_running`, `has_failed`, and `last_error` are mutable runtime refs that power the higher-level lifecycle and diagnostics helpers. - The sink type parameter is preserved across async composition, which is why helpers such as `with_target(...)`, `with_context_fields(...)`, `with_filter(...)`, and `with_patch(...)` keep returning `AsyncLogger[S]`. - `async_logger(...)` constructs this type as the main asynchronous entry point. +- This root type is also what sits underneath both async facade families: `ApplicationAsyncLogger` is a direct alias over the runtime-sink line, while `LibraryAsyncLogger[S]` is a narrowing wrapper around an `AsyncLogger[S]` value. ### How to Use @@ -93,6 +94,8 @@ e.g.: 1. Use `async_logger(...)`, `build_async_logger(...)`, or `build_async_text_logger(...)` when you need a value of this type. -2. Use `ApplicationAsyncLogger` or `LibraryAsyncLogger[S]` when a more intention-specific async wrapper or alias fits the calling boundary better. +2. Use `ApplicationAsyncLogger` when application code wants the same full async lifecycle and state helper surface under an app-facing alias. -3. Prefer the method helpers such as `state()`, `has_failed()`, `last_error()`, `is_running()`, and `shutdown()` instead of reading these public fields conceptually as if they were a stable manual mutation surface. +3. Use `LibraryAsyncLogger[S]` when a library boundary should intentionally narrow the public async surface and expose broader lifecycle/state helpers only through `to_async_logger()`. + +4. Prefer the method helpers such as `state()`, `has_failed()`, `last_error()`, `is_running()`, and `shutdown()` instead of reading these public fields conceptually as if they were a stable manual mutation surface. diff --git a/docs/api/configured-logger.md b/docs/api/configured-logger.md index a51c543..44fea3e 100644 --- a/docs/api/configured-logger.md +++ b/docs/api/configured-logger.md @@ -33,6 +33,7 @@ Detailed rules explaining key parameters and behaviors - It preserves normal logger methods such as `info(...)`, `warn(...)`, `error(...)`, and the other `Logger` APIs. - It also exposes configured runtime helpers such as `flush()`, `drain()`, `pending_count()`, `dropped_count()`, and file-specific controls when the runtime sink supports them. - Builders such as `build_logger(...)` and `parse_and_build_logger(...)` return this alias as the main sync config-to-runtime result. +- `ApplicationLogger` is another direct alias-oriented name for this same configured runtime surface, while `LibraryLogger[RuntimeSink]` is the narrowing facade variant that intentionally hides these runtime helpers until `to_logger()` is used. ### How to Use @@ -68,4 +69,6 @@ e.g.: 1. Use `build_logger(...)` or `parse_and_build_logger(...)` when you need a value of this type. -2. Use `ApplicationLogger` or `LibraryLogger[RuntimeSink]` when a more intention-specific facade name fits the calling code better. +2. Use `ApplicationLogger` when application code wants the same full configured-runtime helper surface under an app-facing name. + +3. Use `LibraryLogger[RuntimeSink]` when a library boundary should intentionally hide configured-runtime helper methods behind a narrower facade. diff --git a/docs/api/logger.md b/docs/api/logger.md index dba4b99..d7fe768 100644 --- a/docs/api/logger.md +++ b/docs/api/logger.md @@ -38,6 +38,7 @@ Detailed rules explaining key parameters and behaviors - The current fields are `min_level : Level`, `sink : S`, `target : String`, and `timestamp : Bool`. - The sink type parameter is preserved across composition, which is why helpers such as `with_context_fields(...)`, `with_filter(...)`, `with_patch(...)`, and `with_queue(...)` can return more specific logger shapes. - `Logger::new(...)` constructs this type as the main synchronous entry point. +- This root type is also what sits underneath both facade families: `ApplicationLogger` is a direct alias over the configured `Logger[RuntimeSink]` line, while `LibraryLogger[S]` is a narrowing wrapper around a `Logger[S]` value. ### How to Use @@ -74,4 +75,8 @@ e.g.: 1. Use `Logger::new(...)` when you need a value of this type in code. -2. Use `ConfiguredLogger`, `ApplicationLogger`, or `LibraryLogger[S]` when a more intention-specific wrapper or alias fits the calling boundary better. +2. Use `ConfiguredLogger` when config-built runtime helpers should stay directly available on the returned logger value. + +3. Use `ApplicationLogger` when application code wants that same configured-runtime surface under an app-facing alias. + +4. Use `LibraryLogger[S]` when a library boundary should intentionally narrow the public logger surface and expose broader composition only through `to_logger()`.