📝 clarify async backlog docs

docs/api/async-logger-dropped-count.md

@@ -35,6 +35,7 @@ Detailed rules explaining key parameters and behaviors
 
 - The counter increases when overflow policy discards records.
 - The counter can also increase when `close(clear=true)` or `shutdown(clear=true)` abandons queued records.
+- It can also increase when shutdown fallback logic converts remaining pending records into dropped records during a clear-close path.
 - This is a cumulative counter for the lifetime of the logger value.
 - Use this helper when you need a focused loss metric rather than a full `state()` snapshot.
 

docs/api/async-logger-pending-count.md

@@ -2,8 +2,8 @@
 name: async-logger-pending-count
 group: api
 category: async
-update-time: 20260512
-description: Read the current number of queued records that have not yet been drained by the async logger worker.
+update-time: 20260614
+description: Read the current number of queued records that have not yet been drained or cleared from the async logger pipeline.
 key-word:
     - async
     - logger
@@ -35,6 +35,7 @@ Detailed rules explaining key parameters and behaviors
 
 - The count increases when records are accepted into the queue.
 - The count decreases as the worker drains records.
+- The count is also reset to `0` when queued records are abandoned through clear-close paths such as `close(clear=true)`.
 - This is a point-in-time metric and may change immediately after it is read.
 - Use this helper when a single backlog number is enough and a full `state()` snapshot is unnecessary.
 
@@ -67,6 +68,8 @@ In this example, the queue backlog is checked directly.
 e.g.:
 - If the worker is not running, `pending_count()` may stay above `0` until records are drained or cleared.
 
+- If `wait_idle()` returns early because `has_failed()` became `true`, `pending_count()` may still be above `0` until later cleanup or clear-close handling runs.
+
 - If the queue is empty, the method simply returns `0`.
 
 ### Notes
@@ -74,3 +77,5 @@ e.g.:
 1. Use `state()` when you also need dropped counts, failure state, or runtime mode.
 
 2. This helper is useful for lightweight health checks and tests.
+
+3. Pair it with `is_running()` or `has_failed()` when backlog alone is not enough to explain whether the worker is actively draining, stopped, or failed.

docs/api/async-logger-wait-idle.md

@@ -36,6 +36,7 @@ Detailed rules explaining key parameters and behaviors
 - The helper keeps yielding while `pending_count() > 0`.
 - If `has_failed()` becomes `true`, waiting stops early instead of looping forever.
 - This API does not close the logger or stop the worker.
+- A return from `wait_idle()` therefore means either backlog reached `0` or failure interrupted normal drain progress.
 - It is narrower than `shutdown()` and is useful when the logger should continue to be used later.
 
 ### How to Use
@@ -68,8 +69,12 @@ e.g.:
 
 - If the worker was never started, pending records may not drain and callers should not expect idle progress automatically.
 
+- If callers need backlog cleanup after a failure-short-circuit, they still need a later `close(clear=true)` or `shutdown(...)` path.
+
 ### Notes
 
 1. Use this helper when you want a drain barrier without closing the logger.
 
 2. Prefer `shutdown()` when lifecycle completion matters more than continued reuse.
+
+3. Pair it with `pending_count()` or `state()` when you need to distinguish true idleness from an early stop caused by worker failure.