From 5ded4439b0cdaa354bc84ee7fc7717126a991ff0 Mon Sep 17 00:00:00 2001
From: Nanaloveyuki <miaomiao_159@outlook.com>
Date: Sun, 14 Jun 2026 08:08:00 +0800
Subject: [PATCH] :memo: clarify parsed sync target behavior

---
 docs/api/parse-and-build-application-logger.md | 15 +++++++++++++++
 docs/api/parse-and-build-library-logger.md     | 15 +++++++++++++++
 2 files changed, 30 insertions(+)

diff --git a/docs/api/parse-and-build-application-logger.md b/docs/api/parse-and-build-application-logger.md
index 3e43320..2cbc0d1 100644
--- a/docs/api/parse-and-build-application-logger.md
+++ b/docs/api/parse-and-build-application-logger.md
@@ -40,6 +40,7 @@ Detailed rules explaining key parameters and behaviors
 - The parsed config still goes through the normal configured runtime logger build path, including runtime sink selection, optional queue wrapping, and timestamp application.
 - Because the result is only the `ApplicationLogger` alias over `ConfiguredLogger`, this parse-and-build path returns the same underlying configured runtime logger value that `parse_and_build_logger(...)` would produce directly, without hiding any queue, drain, flush, or file runtime helper methods.
 - The returned alias also keeps inherited `Logger` behavior such as `with_target(...)`, `child(...)`, and per-call `target=` overrides on `log(...)`.
+- That means `log(..., target=...)` can override the target for one write, while severity helpers such as `info(...)`, `warn(...)`, and `error(...)` continue to use the stored logger target unless a derived logger was created first with `with_target(...)` or `child(...)`.
 - Use `parse_and_build_library_logger(...)` instead when the same parsed configured logger result should be wrapped and narrowed for a library boundary.
 
 ### How to Use
@@ -61,6 +62,20 @@ And any queue/file/runtime helpers selected by the parsed config remain directly
 
 The returned value also keeps the ordinary logger target semantics because this facade does not wrap or narrow the configured runtime logger result.
 
+#### When Need A Per-call Target Override After JSON Boot
+
+When parsed app configuration should keep the same direct target override behavior as the ordinary configured logger:
+```moonbit
+let logger = parse_and_build_application_logger(raw) catch {
+  err => return
+}
+logger.log(Level::Error, "boom", target="app.audit")
+```
+
+In this example, the emitted record uses `app.audit` for that call.
+
+And later `info(...)`, `warn(...)`, or `error(...)` calls still use the logger's stored target unless code derives another logger first with `with_target(...)` or `child(...)`.
+
 ### Error Case
 
 e.g.:
diff --git a/docs/api/parse-and-build-library-logger.md b/docs/api/parse-and-build-library-logger.md
index 4934c77..eb6f255 100644
--- a/docs/api/parse-and-build-library-logger.md
+++ b/docs/api/parse-and-build-library-logger.md
@@ -39,6 +39,7 @@ Detailed rules explaining key parameters and behaviors
 - The parsed config still goes through the normal configured runtime logger build path, including runtime sink selection, optional queue wrapping, and timestamp application.
 - The returned facade wraps the same underlying `ConfiguredLogger` value that `parse_and_build_logger(...)` would produce directly.
 - The returned facade keeps a narrower surface than the underlying configured logger.
+- The facade still preserves the underlying logger target rules on its exposed write methods: `log(..., target=...)` can override the target for one write, while `info(...)`, `warn(...)`, and `error(...)` continue using the stored logger target unless the facade first derived another logger with `with_target(...)` or `child(...)`.
 - Queue metrics, flush and drain helpers, and file runtime controls stay on the underlying `ConfiguredLogger`, not on the returned facade itself.
 - `to_logger()` can be used to recover the underlying full logger object when necessary.
 - Use this parse/build facade when text-driven construction should preserve the configured runtime logger path but still hide broader runtime helper methods at the package boundary.
@@ -73,6 +74,20 @@ In this example, the caller unwraps the library facade before using runtime-spec
 
 And the unwrapped value still reflects the same `RuntimeSink` pipeline built from the parsed config text.
 
+#### When Need A Per-call Target Override Through The Library Facade
+
+When parsed library configuration should still allow a one-write target override without unwrapping first:
+```moonbit
+let logger = parse_and_build_library_logger(raw) catch {
+  err => return
+}
+logger.log(Level::Error, "boom", target="lib.audit")
+```
+
+In this example, the emitted record uses `lib.audit` for that write.
+
+And later `info(...)`, `warn(...)`, or `error(...)` calls still use the facade's stored target unless code derives another facade first with `with_target(...)` or `child(...)`.
+
 ### Error Case
 
 e.g.: