From a9725a8d3365d72b8d1a65d03fc5202d4af04d69 Mon Sep 17 00:00:00 2001
From: Nanaloveyuki <miaomiao_159@outlook.com>
Date: Sat, 13 Jun 2026 21:34:56 +0800
Subject: [PATCH] :memo: document root logger types

---
 docs/api/async-logger-type.md | 92 +++++++++++++++++++++++++++++++++++
 docs/api/index.md             |  2 +
 docs/api/logger.md            | 77 +++++++++++++++++++++++++++++
 3 files changed, 171 insertions(+)
 create mode 100644 docs/api/async-logger-type.md
 create mode 100644 docs/api/logger.md

diff --git a/docs/api/async-logger-type.md b/docs/api/async-logger-type.md
new file mode 100644
index 0000000..40bb960
--- /dev/null
+++ b/docs/api/async-logger-type.md
@@ -0,0 +1,92 @@
+---
+name: async-logger-type
+group: api
+category: async
+update-time: 20260613
+description: Public asynchronous logger root type used for queue-backed sink-preserving logging pipelines.
+key-word:
+    - async
+    - logger
+    - type
+    - public
+---
+
+## Async-logger-type
+
+`AsyncLogger[S]` is the public asynchronous root logger type. It stores a concrete sink type `S` together with queue policy, runtime state counters, and lifecycle flags, then serves as the base value for async composition, worker control, and async write APIs.
+
+### Interface
+
+```moonbit
+pub struct AsyncLogger[S] {
+  min_level : @bitlogger.Level
+  target : String
+  timestamp : Bool
+  overflow : AsyncOverflowPolicy
+  max_batch : Int
+  linger_ms : Int
+  flush_policy : AsyncFlushPolicy
+  sink : S
+  flush_sink : (S) -> Int raise
+  context_fields : Array[@bitlogger.Field]
+  filter : (@bitlogger.Record) -> Bool
+  patch : @bitlogger.RecordPatch
+  queue : @async.Queue[@bitlogger.Record]
+  pending_count : Ref[Int]
+  dropped_count : Ref[Int]
+  is_closed : Ref[Bool]
+  is_running : Ref[Bool]
+  has_failed : Ref[Bool]
+  last_error : Ref[String]
+}
+```
+
+#### output
+
+- `AsyncLogger[S]` - Public queue-backed asynchronous logger value parameterized by the concrete sink type `S`.
+
+### Explanation
+
+Detailed rules explaining key parameters and behaviors
+
+- This is a public root struct, not a type alias.
+- The current fields cover targeting, overflow policy, batching, linger timing, flush policy, the wrapped sink, context/filter/patch behavior, queue state, and worker lifecycle flags.
+- The sink type parameter is preserved across async composition, which is why helpers such as `with_target(...)`, `with_context_fields(...)`, `with_filter(...)`, and `with_patch(...)` keep returning `AsyncLogger[S]`.
+- `async_logger(...)` constructs this type as the main asynchronous entry point.
+
+### How to Use
+
+Here are some specific examples provided.
+
+#### When Need A Typed Root Async Logger Value
+
+When queue-backed logging should begin from a concrete sink-preserving root object:
+```moonbit
+let logger : AsyncLogger[ConsoleSink] = async_logger(console_sink(), target="app.async")
+```
+
+In this example, the root async logger keeps the concrete sink type visible for later typed composition.
+
+#### When Need Worker Control Plus Runtime State
+
+When code should both enqueue logs and inspect async runtime behavior:
+```moonbit
+let logger = async_logger(console_sink(), config=AsyncLoggerConfig::new(max_pending=32))
+ignore(logger.pending_count())
+ignore(logger.state())
+```
+
+In this example, the root type combines queue-backed logging with explicit runtime observability.
+
+### Error Case
+
+e.g.:
+- `AsyncLogger[S]` itself does not have a runtime failure mode.
+
+- Actual enqueue, worker, and flush behavior still depends on the wrapped sink `S`, async runtime support, and the configured queue policy.
+
+### Notes
+
+1. Use `async_logger(...)`, `build_async_logger(...)`, or `build_async_text_logger(...)` when you need a value of this type.
+
+2. Use `ApplicationAsyncLogger` or `LibraryAsyncLogger[S]` when a more intention-specific async wrapper or alias fits the calling boundary better.
diff --git a/docs/api/index.md b/docs/api/index.md
index 2b92f16..88001d1 100644
--- a/docs/api/index.md
+++ b/docs/api/index.md
@@ -21,6 +21,7 @@ BitLogger API navigation.
 
 ## Core logger
 
+- [logger.md](./logger.md)
 - [logger-new.md](./logger-new.md)
 - [logger-with-target.md](./logger-with-target.md)
 - [logger-child.md](./logger-child.md)
@@ -180,6 +181,7 @@ BitLogger API navigation.
 
 ## Async logger
 
+- [async-logger-type.md](./async-logger-type.md)
 - [async-logger.md](./async-logger.md)
 - [async-logger-run.md](./async-logger-run.md)
 - [async-logger-log.md](./async-logger-log.md)
diff --git a/docs/api/logger.md b/docs/api/logger.md
new file mode 100644
index 0000000..dba4b99
--- /dev/null
+++ b/docs/api/logger.md
@@ -0,0 +1,77 @@
+---
+name: logger
+group: api
+category: logging
+update-time: 20260613
+description: Public synchronous logger root type used for typed logging pipelines and sink-preserving composition.
+key-word:
+    - logger
+    - sync
+    - type
+    - public
+---
+
+## Logger
+
+`Logger[S]` is the public synchronous root logger type. It stores a concrete sink type `S` together with minimum level, default target, and timestamp settings, then serves as the base value for typed composition helpers and write APIs.
+
+### Interface
+
+```moonbit
+pub struct Logger[S] {
+  min_level : Level
+  sink : S
+  target : String
+  timestamp : Bool
+}
+```
+
+#### output
+
+- `Logger[S]` - Public synchronous logger value parameterized by the concrete sink type `S`.
+
+### Explanation
+
+Detailed rules explaining key parameters and behaviors
+
+- This is a public root struct, not a type alias.
+- The current fields are `min_level : Level`, `sink : S`, `target : String`, and `timestamp : Bool`.
+- The sink type parameter is preserved across composition, which is why helpers such as `with_context_fields(...)`, `with_filter(...)`, `with_patch(...)`, and `with_queue(...)` can return more specific logger shapes.
+- `Logger::new(...)` constructs this type as the main synchronous entry point.
+
+### How to Use
+
+Here are some specific examples provided.
+
+#### When Need A Typed Root Logger Value
+
+When synchronous logging should begin from a concrete sink-preserving root object:
+```moonbit
+let logger : Logger[ConsoleSink] = Logger::new(console_sink(), target="app")
+```
+
+In this example, the root logger keeps the concrete console sink type visible for later typed composition.
+
+#### When Need To Build A Composed Logging Pipeline
+
+When code should start from one root logger and then derive more specific wrapped forms:
+```moonbit
+let logger = Logger::new(console_sink(), min_level=Level::Info)
+  .with_timestamp()
+  .with_context_fields([field("service", "billing")])
+```
+
+In this example, the root type becomes the stable base for later logging behavior changes.
+
+### Error Case
+
+e.g.:
+- `Logger[S]` itself does not have a runtime failure mode.
+
+- Actual write behavior still depends on the wrapped sink `S`, so sink-specific limitations remain unchanged behind the logger type.
+
+### Notes
+
+1. Use `Logger::new(...)` when you need a value of this type in code.
+
+2. Use `ConfiguredLogger`, `ApplicationLogger`, or `LibraryLogger[S]` when a more intention-specific wrapper or alias fits the calling boundary better.