From 35e87f17614da0bc1caf8df2ec58fe38e1e39f65 Mon Sep 17 00:00:00 2001
From: Nanaloveyuki <miaomiao_159@outlook.com>
Date: Sun, 14 Jun 2026 08:48:22 +0800
Subject: [PATCH] :memo: clarify application runtime helper access

---
 docs/api/application-async-logger.md | 13 +++++++++++++
 docs/api/application-logger.md       | 13 +++++++++++++
 2 files changed, 26 insertions(+)

diff --git a/docs/api/application-async-logger.md b/docs/api/application-async-logger.md
index ae2ccb6..3bda9d0 100644
--- a/docs/api/application-async-logger.md
+++ b/docs/api/application-async-logger.md
@@ -38,6 +38,7 @@ Detailed rules explaining key parameters and behaviors
 - 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.
+- Those helpers remain directly callable on `ApplicationAsyncLogger` itself; callers do not need an unwrap step to reach queue counters, lifecycle state, or `RuntimeSink` file helpers.
 - 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 +70,18 @@ In this example, callers see the app-facing alias instead of the more explicit g
 
 And the inherited async logger target rules stay the same: `log(..., target=...)` can override the target per call, while `info(...)`, `warn(...)`, and `error(...)` continue using the stored target unless code derives another logger first with `with_target(...)` or `child(...)`.
 
+#### When Need Direct Async Runtime Helpers On The Application Alias
+
+When app code should inspect queue or file-backed runtime state without leaving the alias surface:
+```moonbit
+ignore(logger.pending_count())
+ignore(logger.state())
+```
+
+In this example, lifecycle and queue helpers are called directly on `ApplicationAsyncLogger`.
+
+And unlike `LibraryAsyncLogger[@bitlogger.RuntimeSink]`, no `to_async_logger()` unwrap is required first.
+
 #### When Need A One-call Target Override Without Rebuilding The Alias
 
 When app-level async code should keep the same alias value but emit one record under a different target:
diff --git a/docs/api/application-logger.md b/docs/api/application-logger.md
index 10bb754..6bca4ba 100644
--- a/docs/api/application-logger.md
+++ b/docs/api/application-logger.md
@@ -35,6 +35,7 @@ Detailed rules explaining key parameters and behaviors
 - In particular, `log(..., target=...)` can override the target for one call, while severity helpers such as `info(...)`, `warn(...)`, and `error(...)` continue using the stored logger target unless code derives another logger first with `with_target(...)` or `child(...)`.
 - Like the underlying synchronous logger line, `with_context_fields(...)` and `bind(...)` do not preserve the alias spelling. They return a `Logger[ContextSink[RuntimeSink]]` shape because sync shared-field binding extends the sink pipeline instead of storing extra alias-level context metadata.
 - Because this is only an alias, the application-facing type does not hide any configured-runtime helpers or broader logger surface.
+- That means queue, drain, flush, and file runtime helpers remain directly callable on `ApplicationLogger` itself; callers do not need an unwrap step to reach the underlying configured runtime logger behavior.
 - The alias exists to give application boot code a clearer public entry name.
 - Builders such as `build_application_logger(...)` and `parse_and_build_application_logger(...)` return this alias.
 
@@ -64,6 +65,18 @@ In this example, callers see the app-facing alias instead of the lower-level `Co
 
 And the same queue/file/runtime helpers remain directly callable because no narrowing wrapper is added.
 
+#### When Need Direct Runtime Helpers On The Application Alias
+
+When app code should inspect queue state or file controls without leaving the alias surface:
+```moonbit
+ignore(logger.pending_count())
+ignore(logger.flush())
+```
+
+In this example, the runtime helpers are called directly on `ApplicationLogger`.
+
+And unlike `LibraryLogger[RuntimeSink]`, no `to_logger()` unwrap is required first.
+
 And the inherited logger target rules stay the same: `log(..., target=...)` can override the target per call, while `info(...)`, `warn(...)`, and `error(...)` continue using the stored target unless code derives another logger first with `with_target(...)` or `child(...)`.
 
 #### When Need A One-call Target Override Without Rebuilding The Alias