From 82200c61fbf81d9fe2063ad36b496597707e4e58 Mon Sep 17 00:00:00 2001 From: Nanaloveyuki Date: Sun, 14 Jun 2026 07:15:46 +0800 Subject: [PATCH] :memo: align async alias docs --- docs/api/application-async-logger.md | 4 ++++ docs/api/application-text-async-logger.md | 3 +++ 2 files changed, 7 insertions(+) diff --git a/docs/api/application-async-logger.md b/docs/api/application-async-logger.md index b1d106b..8155abd 100644 --- a/docs/api/application-async-logger.md +++ b/docs/api/application-async-logger.md @@ -33,6 +33,8 @@ Detailed rules explaining key parameters and behaviors - It preserves the same async lifecycle helpers such as `run()`, `shutdown()`, `pending_count()`, and `state()`. - Because this is only an alias, methods that are async on `AsyncLogger[@bitlogger.RuntimeSink]` remain async here as well. - The alias therefore keeps the same runtime-sink lifecycle, queue, failure-state, and runtime-dependent post-close semantics already documented on `AsyncLogger[@bitlogger.RuntimeSink]`. +- In the current direct alias coverage, values built through `build_application_async_logger(...)` keep the same serialized state snapshot shape, queue counters, lifecycle flags, failure fields, and runtime-sink helper surface that the underlying runtime-sink async logger exposes directly. +- That includes queued runtime-sink behavior and file-backed runtime helpers when the configured sink path supports them. - The alias exists to give application boot code a clearer public type name for the standard runtime-sink async logger. - Builders such as `build_application_async_logger(...)` and `parse_and_build_application_async_logger(...)` return this alias. @@ -69,6 +71,8 @@ e.g.: - If code needs a narrower public surface than the full async logger API, `LibraryAsyncLogger` is the better facade. +- If callers need queued runtime-sink helpers or file-backed runtime helpers, they remain directly available on this alias because no wrapper layer strips them away. + ### Notes 1. This alias is about naming and public intent, not a different async implementation. diff --git a/docs/api/application-text-async-logger.md b/docs/api/application-text-async-logger.md index ef621b2..3626ff9 100644 --- a/docs/api/application-text-async-logger.md +++ b/docs/api/application-text-async-logger.md @@ -34,6 +34,7 @@ Detailed rules explaining key parameters and behaviors - Because this is only an alias, methods that are async on `AsyncLogger[@bitlogger.FormattedConsoleSink]` remain async here as well. - The alias therefore keeps the same text-console-specific builder and lifecycle semantics already documented on `AsyncLogger[@bitlogger.FormattedConsoleSink]`, including the concrete sink shape plus the same close, queue, and failure-state behavior. - The application-facing type does not hide any async state or lifecycle helpers; queue/backlog/failure inspection remains directly available on this alias just as it is on the underlying `AsyncLogger[@bitlogger.FormattedConsoleSink]`. +- In the current direct alias coverage, values built through `build_application_text_async_logger(...)` keep the same serialized state snapshot shape, formatter behavior, queue counters, lifecycle flags, and failure fields that the underlying text-console async logger exposes directly. - When the value is built through `build_application_text_async_logger(...)`, the direct async counters come from the outer async logger only; any optional sync queue configured on `LoggerConfig.queue` is not carried into this text-specific build path. - When the value is built through `build_application_text_async_logger(...)`, `flush_policy()` still reports the configured async policy, but the text-specific build path keeps the default no-op async flush callback instead of wiring an explicit sink flush step. - The alias exists to give application code a clearer public name when it wants the concrete text-console sink shape explicitly. @@ -74,6 +75,8 @@ e.g.: - If code does not need the concrete text-console sink shape, `ApplicationAsyncLogger` is the broader runtime-sink async alias. +- If callers depend on the concrete formatter or direct text-console helper surface, they remain available on this alias because no wrapper layer narrows them away. + ### Notes 1. This alias is about naming and public intent, not a different async implementation.