From 9c1787e700d3e8101b33e020c994675c8301980a Mon Sep 17 00:00:00 2001 From: Nanaloveyuki Date: Sun, 14 Jun 2026 07:41:51 +0800 Subject: [PATCH] :memo: clarify application logger alias behavior --- docs/api/application-logger.md | 9 +++++++-- docs/api/build-application-logger.md | 3 +++ docs/api/parse-and-build-application-logger.md | 3 +++ 3 files changed, 13 insertions(+), 2 deletions(-) diff --git a/docs/api/application-logger.md b/docs/api/application-logger.md index 404c796..88454a0 100644 --- a/docs/api/application-logger.md +++ b/docs/api/application-logger.md @@ -31,6 +31,7 @@ Detailed rules explaining key parameters and behaviors - This alias does not introduce a new runtime type or wrapper layer. - It preserves the same logging, queue, and file helper APIs exposed by `ConfiguredLogger`. +- Because `ConfiguredLogger` is itself `Logger[RuntimeSink]`, the alias also keeps ordinary logger composition and write behavior such as `with_target(...)`, `child(...)`, and `log(..., target=...)`. - Because this is only an alias, the application-facing type does not hide any configured-runtime helpers or broader logger surface. - 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. @@ -61,6 +62,8 @@ 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. +And the inherited logger target rules stay the same: `log(..., target=...)` can override the target per call, while `with_target(...)` and `child(...)` derive new logger values with changed default targets. + ### Error Case e.g.: @@ -72,6 +75,8 @@ e.g.: 1. This alias is about naming and public intent, not a different runtime implementation. -2. Use `build_application_logger(...)` or `parse_and_build_application_logger(...)` for the usual construction paths. +2. Inherited `Logger` behavior stays unchanged on this alias, including target overrides on `log(...)` and derived target composition through `with_target(...)` and `child(...)`. -3. Use `LibraryLogger` instead when a library boundary should intentionally hide configured-runtime helper methods behind a narrower facade. +3. Use `build_application_logger(...)` or `parse_and_build_application_logger(...)` for the usual construction paths. + +4. Use `LibraryLogger` instead when a library boundary should intentionally hide configured-runtime helper methods behind a narrower facade. diff --git a/docs/api/build-application-logger.md b/docs/api/build-application-logger.md index 08ce3f2..e511016 100644 --- a/docs/api/build-application-logger.md +++ b/docs/api/build-application-logger.md @@ -36,6 +36,7 @@ Detailed rules explaining key parameters and behaviors - This API delegates to `build_logger(...)` directly. - The embedded config still goes through the normal 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 builder does not hide 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(...)`. - Use this alias-oriented entrypoint when application boot code wants an app-specific name without changing the underlying configured runtime logger surface. ### How to Use @@ -55,6 +56,8 @@ In this example, the application facade builds the same configured runtime logge And any queue/file/runtime helpers selected by the config remain directly available on the returned alias value. +The returned value also keeps the ordinary logger target semantics because the facade does not wrap or narrow the underlying `ConfiguredLogger`. + ### Error Case e.g.: diff --git a/docs/api/parse-and-build-application-logger.md b/docs/api/parse-and-build-application-logger.md index a237885..3e43320 100644 --- a/docs/api/parse-and-build-application-logger.md +++ b/docs/api/parse-and-build-application-logger.md @@ -39,6 +39,7 @@ Detailed rules explaining key parameters and behaviors - JSON parsing and config validation happen before the logger is built. - 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(...)`. - 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 @@ -58,6 +59,8 @@ In this example, parsing and runtime construction are combined into one facade c And any queue/file/runtime helpers selected by the parsed config remain directly available on the returned alias value. +The returned value also keeps the ordinary logger target semantics because this facade does not wrap or narrow the configured runtime logger result. + ### Error Case e.g.: