From ba72a021a81721fe7a78c2689d4d0f995235fbcb Mon Sep 17 00:00:00 2001 From: Nanaloveyuki Date: Sun, 14 Jun 2026 01:28:23 +0800 Subject: [PATCH] :memo: align async logger root docs --- docs/api/async-logger.md | 5 +++++ docs/api/build-async-logger.md | 5 +++++ 2 files changed, 10 insertions(+) diff --git a/docs/api/async-logger.md b/docs/api/async-logger.md index 098ff80..12bbadb 100644 --- a/docs/api/async-logger.md +++ b/docs/api/async-logger.md @@ -44,7 +44,10 @@ pub fn[S] async_logger( Detailed rules explaining key parameters and behaviors - `async_logger(...)` only builds the logger. Actual background draining is started by `run()`. +- `async_logger(...)` returns the full `AsyncLogger[S]` surface directly. It is therefore the underlying constructor used by both application-facing async aliases and the narrower `LibraryAsyncLogger[S]` wrapper line. - The constructed logger starts with `is_closed=false`, `is_running=false`, `has_failed=false`, `last_error=""`, and zeroed pending/dropped counters. +- `ApplicationAsyncLogger` and `ApplicationTextAsyncLogger` are only alias names over concrete `AsyncLogger[...]` shapes, so they keep the same lifecycle, queue, failure, and state helpers without adding a wrapper layer. +- `LibraryAsyncLogger[S]` wraps an `AsyncLogger[S]` value instead of aliasing it. That library facade preserves queue-backed logging behavior, but it narrows the directly exposed helper surface until callers recover the full logger with `to_async_logger()`. - In non-native targets, the implementation uses compatibility behavior while keeping the same public surface. - `src-async` is designed for `native / llvm / js / wasm / wasm-gc`, but current release-facing local verification is stronger for `native / js / wasm / wasm-gc` than for `llvm`. - `llvm` should currently be read as experimental and locally unverified in this environment rather than as a stable checked target. @@ -108,3 +111,5 @@ e.g.: 4. See [target-verification.md](./target-verification.md) for the current local verification matrix. 5. Pair this constructor with `run()` and `shutdown()` when you need the full worker lifecycle rather than just a configured async logger value. + +6. Choose the facade name based on boundary intent: use `AsyncLogger[S]` for the full surface, `ApplicationAsyncLogger` or `ApplicationTextAsyncLogger` for application-facing alias names, and `LibraryAsyncLogger[S]` when a package boundary should intentionally narrow what downstream code can call directly. diff --git a/docs/api/build-async-logger.md b/docs/api/build-async-logger.md index 8913300..7113a21 100644 --- a/docs/api/build-async-logger.md +++ b/docs/api/build-async-logger.md @@ -38,6 +38,9 @@ Detailed rules explaining key parameters and behaviors - The resulting async logger inherits `min_level`, `target`, and timestamp behavior from the built synchronous logger. - File, formatter, and any configured synchronous queue choices all come from config rather than direct code-side sink wiring. - The returned sink type is `RuntimeSink`, which keeps configured control helpers available where relevant. +- This builder returns the underlying `AsyncLogger[@bitlogger.RuntimeSink]` value directly. `build_application_async_logger(...)` only re-exports the same result under the `ApplicationAsyncLogger` alias, while `build_library_async_logger(...)` wraps the same result in `LibraryAsyncLogger[@bitlogger.RuntimeSink]`. +- Because this path starts from `build_logger(config.logger)`, it preserves the broader runtime-sink build path, including sync-side queue decoration when `LoggerConfig.queue` is present. +- Use `build_async_text_logger(...)` instead when you want the direct text-console async builder path with `FormattedConsoleSink` and without the sync runtime-sink construction layer. - The `src-async` library is designed to compile on `native / llvm / js / wasm / wasm-gc`, but runtime mode differs by backend. - Current local release-facing verification is explicit for `native / js / wasm / wasm-gc`. - `llvm` remains experimental and did not complete local verification in this environment. @@ -89,3 +92,5 @@ e.g.: 3. Library portability is broader than example portability: a runnable `async fn main` example may still be target-limited even when the async library itself compiles for that backend. 4. See [target-verification.md](./target-verification.md) for the current verification boundary. + +5. If the next boundary is library-facing rather than application-facing, build here and then narrow with `build_library_async_logger(...)` instead of documenting the broader runtime helper surface directly.