From 1a2aee4a7c399a4651c71723a472848f365e4375 Mon Sep 17 00:00:00 2001 From: Nanaloveyuki Date: Sun, 14 Jun 2026 10:36:40 +0800 Subject: [PATCH] :memo: clarify application text async sink selection --- docs/api/application-text-async-logger.md | 3 +++ 1 file changed, 3 insertions(+) diff --git a/docs/api/application-text-async-logger.md b/docs/api/application-text-async-logger.md index 3bea964..a12eb19 100644 --- a/docs/api/application-text-async-logger.md +++ b/docs/api/application-text-async-logger.md @@ -39,6 +39,7 @@ Detailed rules explaining key parameters and behaviors - 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(...)`, `logger.sink.kind` also does not decide the runtime sink shape. The builder still constructs `FormattedConsoleSink` from `logger.sink.text_formatter`, even if the config said `Console`, `JsonConsole`, or `File`. - 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. - `build_application_text_async_logger(...)` returns this alias. @@ -102,6 +103,8 @@ e.g.: - If code does not need the concrete text-console sink shape, `ApplicationAsyncLogger` is the broader runtime-sink async alias. +- If the value came from `build_application_text_async_logger(...)`, carrying `logger.sink.kind=File` in the config still does not make this alias file-backed; that builder keeps the formatter-driven text-console path. + - 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