From f636c2df60e231b17490374a087faa518be7bfc9 Mon Sep 17 00:00:00 2001
From: Nanaloveyuki <miaomiao_159@outlook.com>
Date: Sun, 14 Jun 2026 07:24:00 +0800
Subject: [PATCH] :memo: clarify async reshaping helper docs

---
 docs/api/async-logger-child.md               | 3 +++
 docs/api/async-logger-with-context-fields.md | 3 +++
 docs/api/async-logger-with-target.md         | 3 +++
 docs/api/async-logger-with-timestamp.md      | 3 +++
 4 files changed, 12 insertions(+)

diff --git a/docs/api/async-logger-child.md b/docs/api/async-logger-child.md
index edc6154..866290c 100644
--- a/docs/api/async-logger-child.md
+++ b/docs/api/async-logger-child.md
@@ -38,6 +38,7 @@ Detailed rules explaining key parameters and behaviors
 - If the child target is empty, the parent target is preserved.
 - If both are non-empty, they are joined with `.`.
 - Queue settings, sink wiring, and runtime behavior are preserved in the returned logger.
+- In the current direct async coverage, other flags such as `timestamp` and the enabled-level gate are preserved on the derived child logger while the original logger keeps its parent target unchanged.
 
 ### How to Use
 
@@ -76,3 +77,5 @@ e.g.:
 1. This is the preferred API for hierarchical async logger naming.
 
 2. Composition changes the target only and does not rebuild the queue or sink.
+
+3. Use `child("")` when code should keep the current target while still following a target-composition code path.
diff --git a/docs/api/async-logger-with-context-fields.md b/docs/api/async-logger-with-context-fields.md
index f5c327c..aeca02f 100644
--- a/docs/api/async-logger-with-context-fields.md
+++ b/docs/api/async-logger-with-context-fields.md
@@ -41,6 +41,7 @@ Detailed rules explaining key parameters and behaviors
 - When a log call also passes per-record fields, the context fields are placed before those per-call fields.
 - This API returns a new logger value; it does not mutate the original async logger.
 - Unlike synchronous `Logger::with_context_fields(...)`, this async variant stores fields directly on `AsyncLogger` instead of changing the visible sink type.
+- In the current direct async coverage, the original logger keeps its previous `context_fields`, while the derived logger prepends the stored shared fields ahead of per-call fields exactly once when records are built.
 
 ### How to Use
 
@@ -82,3 +83,5 @@ e.g.:
 1. Use this for stable metadata, not highly dynamic event-specific values.
 
 2. This async variant preserves the visible `AsyncLogger[S]` type while still injecting shared fields.
+
+3. Use a fresh derived logger when one code path needs shared metadata and another should stay unchanged.
diff --git a/docs/api/async-logger-with-target.md b/docs/api/async-logger-with-target.md
index fd64ee2..e12a380 100644
--- a/docs/api/async-logger-with-target.md
+++ b/docs/api/async-logger-with-target.md
@@ -38,6 +38,7 @@ Detailed rules explaining key parameters and behaviors
 - This API replaces the default target instead of composing it.
 - Per-call `target?` arguments on `log(...)` can still override the default target.
 - The original logger value is not mutated.
+- In the current direct async coverage, derived loggers keep existing flags such as `timestamp`, while the original logger still retains its previous target.
 
 ### How to Use
 
@@ -76,3 +77,5 @@ e.g.:
 1. Use this API for replacement, not parent-child target composition.
 
 2. It is useful when several subsystems should share one async queue policy.
+
+3. Use it when you want a derived logger value; the original async logger keeps its earlier default target.
diff --git a/docs/api/async-logger-with-timestamp.md b/docs/api/async-logger-with-timestamp.md
index b2e9c75..ddfccf9 100644
--- a/docs/api/async-logger-with-timestamp.md
+++ b/docs/api/async-logger-with-timestamp.md
@@ -38,6 +38,7 @@ Detailed rules explaining key parameters and behaviors
 - When disabled, emitted records use `0UL` as the timestamp value.
 - This setting affects later emitted records only.
 - Queue, batching, and flush behavior are unchanged.
+- In the current direct async coverage, a derived timestamp-enabled logger records non-zero timestamps while the original logger continues emitting `0UL` timestamps when it was left disabled.
 
 ### How to Use
 
@@ -75,3 +76,5 @@ e.g.:
 1. This API controls record creation before enqueue, not formatter display policy.
 
 2. It is useful for tests, deterministic snapshots, and production timing.
+
+3. Use a derived logger value when only one branch should capture timestamps and the base logger should remain deterministic.