From 77d97cef5e99b43230e24ed02248216f0f6a05b4 Mon Sep 17 00:00:00 2001 From: Nanaloveyuki Date: Sun, 14 Jun 2026 00:20:44 +0800 Subject: [PATCH] :memo: align async facade builder docs --- docs/api/build-application-async-logger.md | 7 +++++-- docs/api/build-library-async-logger.md | 1 + docs/api/parse-and-build-application-async-logger.md | 7 +++++-- docs/api/parse-and-build-library-async-logger.md | 1 + 4 files changed, 12 insertions(+), 4 deletions(-) diff --git a/docs/api/build-application-async-logger.md b/docs/api/build-application-async-logger.md index f45e64d..380ecaa 100644 --- a/docs/api/build-application-async-logger.md +++ b/docs/api/build-application-async-logger.md @@ -2,8 +2,8 @@ name: build-application-async-logger group: api category: facade -update-time: 20260520 -description: Build the application-facing async logger facade from an AsyncLoggerBuildConfig. +update-time: 20260614 +description: Build the application-facing async logger facade from an AsyncLoggerBuildConfig through the sync-first async builder path. key-word: - application - async @@ -36,6 +36,7 @@ pub fn build_application_async_logger( Detailed rules explaining key parameters and behaviors - This API delegates to `build_async_logger(...)`. +- That means the embedded `LoggerConfig` is built first through the normal synchronous config path before the outer async layer is applied. - The returned logger keeps the standard async lifecycle and state helper surface. - Use this facade when application code wants a dedicated async app-level entry point. @@ -57,6 +58,8 @@ let logger = build_application_async_logger( In this example, the app-facing async facade is built directly from typed config. +And any configured synchronous runtime sink controls remain available through the returned `RuntimeSink`-backed async logger. + ### Error Case e.g.: diff --git a/docs/api/build-library-async-logger.md b/docs/api/build-library-async-logger.md index 14a873c..73e592b 100644 --- a/docs/api/build-library-async-logger.md +++ b/docs/api/build-library-async-logger.md @@ -36,6 +36,7 @@ pub fn build_library_async_logger( Detailed rules explaining key parameters and behaviors - This API builds the general async runtime logger and then wraps it in the narrower `LibraryAsyncLogger[@bitlogger.RuntimeSink]` facade. +- The embedded `LoggerConfig` still goes through the normal synchronous config path first, so sink shape and any optional synchronous queue layer are already applied before the outer async layer is wrapped and then narrowed. - The result keeps async lifecycle operations such as `run()` and `shutdown()` while narrowing the public shape. - Async state helpers such as `pending_count()`, `dropped_count()`, `state()`, `wait_idle()`, and failure-status inspection remain on the underlying `AsyncLogger`, not on the returned facade itself. - `to_async_logger()` can be used to recover the underlying full async logger. diff --git a/docs/api/parse-and-build-application-async-logger.md b/docs/api/parse-and-build-application-async-logger.md index c5a08ae..fa8334c 100644 --- a/docs/api/parse-and-build-application-async-logger.md +++ b/docs/api/parse-and-build-application-async-logger.md @@ -2,8 +2,8 @@ name: parse-and-build-application-async-logger group: api category: facade -update-time: 20260520 -description: Parse JSON async build config text and build the application-facing async logger facade. +update-time: 20260614 +description: Parse JSON async build config text and build the application-facing async logger facade through the sync-first async builder path. key-word: - application - async @@ -37,6 +37,7 @@ Detailed rules explaining key parameters and behaviors - This API parses async build config text first, then builds the async application facade. - Both the embedded sync logger config and async queue/runtime config are validated by the parser layer. +- The embedded `LoggerConfig` is then built through the normal synchronous config path before the outer async layer is applied. - The returned logger keeps the normal async lifecycle and state helpers. ### How to Use @@ -54,6 +55,8 @@ let logger = parse_and_build_application_async_logger( In this example, text parsing and async logger construction happen in one facade call. +And any configured synchronous runtime sink controls remain available through the returned `RuntimeSink`-backed async logger. + ### Error Case e.g.: diff --git a/docs/api/parse-and-build-library-async-logger.md b/docs/api/parse-and-build-library-async-logger.md index de2ff9e..7fbf880 100644 --- a/docs/api/parse-and-build-library-async-logger.md +++ b/docs/api/parse-and-build-library-async-logger.md @@ -36,6 +36,7 @@ pub fn parse_and_build_library_async_logger( Detailed rules explaining key parameters and behaviors - This API parses async build config text, validates it, builds the async runtime logger, and narrows it to the library facade. +- The embedded `LoggerConfig` still goes through the normal synchronous config path first, so sink shape and any optional synchronous queue layer are already applied before the outer async layer is wrapped and then narrowed. - The resulting facade keeps async lifecycle helpers while exposing a smaller public surface. - Async state helpers such as `pending_count()`, `dropped_count()`, `state()`, `wait_idle()`, and failure-status inspection stay on the underlying `AsyncLogger`, not on the returned facade itself. - `to_async_logger()` can recover the underlying async logger when a wider API is required.