From 2a9dbdcc0144b943b2257eaa8b3af49d3f7366eb Mon Sep 17 00:00:00 2001 From: Nanaloveyuki Date: Sun, 14 Jun 2026 01:21:42 +0800 Subject: [PATCH] :memo: clarify app logger facade docs --- docs/api/application-logger.md | 7 ++++++- docs/api/build-application-logger.md | 13 +++++++++---- docs/api/parse-and-build-application-logger.md | 11 ++++++++--- 3 files changed, 23 insertions(+), 8 deletions(-) diff --git a/docs/api/application-logger.md b/docs/api/application-logger.md index a6736c7..404c796 100644 --- a/docs/api/application-logger.md +++ b/docs/api/application-logger.md @@ -3,7 +3,7 @@ name: application-logger group: api category: facade update-time: 20260613 -description: Application-facing alias for the configured sync runtime logger surface. +description: Application-facing alias for the configured sync runtime logger surface, preserving the full ConfiguredLogger helper set. key-word: - application - facade @@ -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 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. @@ -58,6 +59,8 @@ fn start(logger : ApplicationLogger) -> Unit { In this example, callers see the app-facing alias instead of the lower-level `ConfiguredLogger` name. +And the same queue/file/runtime helpers remain directly callable because no narrowing wrapper is added. + ### Error Case e.g.: @@ -70,3 +73,5 @@ 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. + +3. 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 5b8270f..08ce3f2 100644 --- a/docs/api/build-application-logger.md +++ b/docs/api/build-application-logger.md @@ -3,7 +3,7 @@ name: build-application-logger group: api category: facade update-time: 20260520 -description: Build the application-facing configured logger facade from a LoggerConfig. +description: Build the application-facing configured logger alias from a LoggerConfig by delegating directly to the normal runtime logger build path. key-word: - application - facade @@ -33,9 +33,10 @@ pub fn build_application_logger(config : LoggerConfig) -> ApplicationLogger { Detailed rules explaining key parameters and behaviors -- This API delegates to `build_logger(...)`. -- The returned value keeps the same public logging, queue, and file runtime helper surface as `ConfiguredLogger`. -- Use this facade when application boot code wants an app-specific entry name without exposing lower-level builder naming in its own code. +- 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. +- 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 @@ -52,6 +53,8 @@ let logger = build_application_logger( In this example, the application facade builds the same configured runtime logger shape as `build_logger(...)`. +And any queue/file/runtime helpers selected by the config remain directly available on the returned alias value. + ### Error Case e.g.: @@ -64,3 +67,5 @@ e.g.: 1. This is a facade API, not a separate runtime implementation. 2. Use `parse_and_build_application_logger(...)` when starting from JSON text. + +3. Use `build_library_logger(...)` instead when the public surface should intentionally hide configured-runtime helper methods. diff --git a/docs/api/parse-and-build-application-logger.md b/docs/api/parse-and-build-application-logger.md index 8fcfb5b..32187ce 100644 --- a/docs/api/parse-and-build-application-logger.md +++ b/docs/api/parse-and-build-application-logger.md @@ -3,7 +3,7 @@ name: parse-and-build-application-logger group: api category: facade update-time: 20260520 -description: Parse JSON logger config text and build the application-facing sync logger facade. +description: Parse JSON logger config text and build the application-facing sync logger alias by delegating directly to the configured runtime logger parse-and-build path. key-word: - application - facade @@ -35,9 +35,10 @@ pub fn parse_and_build_application_logger( Detailed rules explaining key parameters and behaviors -- This API delegates to `parse_and_build_logger(...)`. +- This API delegates to `parse_and_build_logger(...)` directly. - JSON parsing and config validation happen before the logger is built. -- The returned logger keeps the same queue and file helper surface as other configured sync runtime loggers. +- 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 does not hide any queue, drain, flush, or file runtime helper methods. ### How to Use @@ -54,6 +55,8 @@ let logger = parse_and_build_application_logger( In this example, parsing and runtime construction are combined into one facade call. +And any queue/file/runtime helpers selected by the parsed config remain directly available on the returned alias value. + ### Error Case e.g.: @@ -66,3 +69,5 @@ e.g.: 1. Use this facade when application code wants a text-to-runtime entry point. 2. Use `build_application_logger(...)` when the config is already typed as `LoggerConfig`. + +3. Use `parse_and_build_library_logger(...)` instead when text-driven construction should narrow the public sync logger surface for a library boundary.