From f50964f5a99242df7a23923b5f848cdbc5e0479e Mon Sep 17 00:00:00 2001 From: Nanaloveyuki Date: Sun, 14 Jun 2026 01:30:22 +0800 Subject: [PATCH] :memo: clarify async text builder docs --- docs/api/build-application-text-async-logger.md | 7 ++++--- docs/api/build-async-text-logger.md | 3 +++ docs/api/build-library-async-text-logger.md | 3 ++- 3 files changed, 9 insertions(+), 4 deletions(-) diff --git a/docs/api/build-application-text-async-logger.md b/docs/api/build-application-text-async-logger.md index cb6977a..ac9c502 100644 --- a/docs/api/build-application-text-async-logger.md +++ b/docs/api/build-application-text-async-logger.md @@ -3,7 +3,7 @@ name: build-application-text-async-logger group: api category: facade update-time: 20260614 -description: Build the application-facing text-console async logger alias from an AsyncLoggerBuildConfig using the configured text formatter directly. +description: Build the application-facing text-console async logger alias from an AsyncLoggerBuildConfig using the direct concrete text-sink builder path. key-word: - application - async @@ -13,7 +13,7 @@ key-word: ## Build-application-text-async-logger -Build an `ApplicationTextAsyncLogger` from `AsyncLoggerBuildConfig`. This is the application-oriented async alias builder for the text-console runtime sink shape returned by `build_async_text_logger(...)`. +Build an `ApplicationTextAsyncLogger` from `AsyncLoggerBuildConfig`. This is the application-oriented async alias builder for the concrete text-console sink shape returned by `build_async_text_logger(...)`. ### Interface @@ -40,9 +40,10 @@ Detailed rules explaining key parameters and behaviors - The builder always creates a `FormattedConsoleSink` from `config.logger.sink.text_formatter` instead of selecting among sink kinds. - Unlike `build_application_async_logger(...)`, this alias-oriented builder does not go through the full synchronous configured-logger build path first. - It uses the selected text-oriented `LoggerConfig` fields directly and therefore does not apply `LoggerConfig.queue` or preserve sync runtime sink controls. -- Because the result is only the `ApplicationTextAsyncLogger` alias over `AsyncLogger[@bitlogger.FormattedConsoleSink]`, this builder does not hide any async helpers or introduce a wrapper layer. +- Because the result is only the `ApplicationTextAsyncLogger` alias over `AsyncLogger[@bitlogger.FormattedConsoleSink]`, this builder returns the same underlying async logger value as `build_async_text_logger(...)` and does not hide any async helpers or introduce a wrapper layer. - The returned logger keeps the full async lifecycle and state helper surface directly, including helpers such as `run()`, `shutdown()`, `pending_count()`, `dropped_count()`, `state()`, `wait_idle()`, `has_failed()`, and `last_error()`. - It also keeps the same runtime-dependent close/failure semantics as the underlying `AsyncLogger[@bitlogger.FormattedConsoleSink]`. +- Use `build_library_async_text_logger(...)` instead when the next boundary should keep the same concrete text sink type but intentionally narrow the directly exposed async helper surface. ### How to Use diff --git a/docs/api/build-async-text-logger.md b/docs/api/build-async-text-logger.md index 9e7132e..c698f38 100644 --- a/docs/api/build-async-text-logger.md +++ b/docs/api/build-async-text-logger.md @@ -38,6 +38,7 @@ Detailed rules explaining key parameters and behaviors - The returned logger inherits `min_level`, `target`, and timestamp behavior from `config.logger`. - Unlike `build_async_logger(...)`, this helper does not run the full synchronous `build_logger(config.logger)` path first. - That means it uses `config.logger.sink.text_formatter`, `min_level`, `target`, and `timestamp` directly, but it does not apply `LoggerConfig.queue` or preserve other sync runtime sink controls. +- This builder returns the underlying `AsyncLogger[@bitlogger.FormattedConsoleSink]` value directly. `build_application_text_async_logger(...)` only re-exports that same result under the `ApplicationTextAsyncLogger` alias, while `build_library_async_text_logger(...)` wraps the same result in `LibraryAsyncLogger[@bitlogger.FormattedConsoleSink]`. - This helper is best suited to text-console output paths where callers want the concrete formatted sink type instead of `RuntimeSink`. - This async text path follows the same target story as the broader async library: `native / js / wasm / wasm-gc` have stronger local verification, while `llvm` remains experimental and locally unverified in this environment. @@ -73,3 +74,5 @@ e.g.: 2. It is the base builder used by the application and library async text facades. 3. See [target-verification.md](./target-verification.md) for the current local verification matrix. + +4. Use this direct builder when callers should keep the full async helper surface on the concrete text sink type rather than a naming alias or a narrowed library wrapper. diff --git a/docs/api/build-library-async-text-logger.md b/docs/api/build-library-async-text-logger.md index 0a73178..851d0d8 100644 --- a/docs/api/build-library-async-text-logger.md +++ b/docs/api/build-library-async-text-logger.md @@ -39,9 +39,10 @@ Detailed rules explaining key parameters and behaviors - It always produces a concrete `FormattedConsoleSink` from `config.logger.sink.text_formatter` instead of branching on sink kinds. - Unlike `build_library_async_logger(...)`, this facade does not go through the full synchronous configured-logger build path first. - It uses the selected text-oriented `LoggerConfig` fields directly and therefore does not apply `LoggerConfig.queue` or preserve sync runtime sink controls. -- The returned facade still wraps the same underlying async logger behavior, so `run()`, `shutdown()`, failure/reset handling, and runtime-dependent close behavior are unchanged under the narrower public type. +- The returned facade wraps the same underlying `AsyncLogger[@bitlogger.FormattedConsoleSink]` value that `build_async_text_logger(...)` would return directly, so `run()`, `shutdown()`, failure/reset handling, and runtime-dependent close behavior are unchanged under the narrower public type. - Async state helpers such as `pending_count()`, `dropped_count()`, `state()`, `wait_idle()`, and failure-status inspection remain on the underlying `AsyncLogger[@bitlogger.FormattedConsoleSink]`, not on the returned facade itself. - `to_async_logger()` can recover the underlying full async logger if needed. +- Use this builder when the boundary should preserve the concrete text-console sink type while still hiding broader async inspection and helper APIs from downstream callers. ### How to Use