From 47de8dc99a97dd5d83635032e235624da7d1a8b7 Mon Sep 17 00:00:00 2001 From: Nanaloveyuki Date: Sun, 14 Jun 2026 01:20:04 +0800 Subject: [PATCH] :memo: refine library logger entry docs --- docs/api/build-library-logger.md | 9 +++++++-- docs/api/default-library-logger.md | 7 ++++++- docs/api/parse-and-build-library-logger.md | 11 ++++++++--- 3 files changed, 21 insertions(+), 6 deletions(-) diff --git a/docs/api/build-library-logger.md b/docs/api/build-library-logger.md index 0decbb9..e21f44d 100644 --- a/docs/api/build-library-logger.md +++ b/docs/api/build-library-logger.md @@ -3,7 +3,7 @@ name: build-library-logger group: api category: facade update-time: 20260613 -description: Build the library-facing sync logger facade from a LoggerConfig and intentionally hide direct runtime helper methods. +description: Build the library-facing sync logger facade from a LoggerConfig by delegating to the configured runtime logger build path and then wrapping the result. key-word: - library - facade @@ -33,7 +33,8 @@ pub fn build_library_logger(config : LoggerConfig) -> LibraryLogger[RuntimeSink] Detailed rules explaining key parameters and behaviors -- This API builds a configured runtime logger first and then wraps it as `LibraryLogger[RuntimeSink]`. +- This API builds a configured runtime logger first and then wraps that same value as `LibraryLogger[RuntimeSink]`. +- The embedded config still goes through the normal runtime logger build path, including runtime sink selection, optional queue wrapping, and timestamp application. - The facade intentionally exposes a smaller logging surface than the full configured runtime logger. - Queue metrics, flush and drain helpers, and file runtime controls remain on the underlying `ConfiguredLogger`, not on the returned facade itself. - Call `to_logger()` if a caller must recover the underlying full logger object. @@ -64,6 +65,8 @@ ignore(full.pending_count()) In this example, the library facade is unwrapped before using configured runtime helper methods. +And the unwrapped value still carries the same `RuntimeSink` pipeline built from the original config. + ### Error Case e.g.: @@ -76,3 +79,5 @@ e.g.: 1. Prefer this facade when library APIs should not expose the full configured runtime logger type. 2. Use `parse_and_build_library_logger(...)` when starting from JSON text. + +3. Use `to_logger()` when internal code later needs configured-runtime helpers or broader logger composition without changing the public facade type. diff --git a/docs/api/default-library-logger.md b/docs/api/default-library-logger.md index 18ba2b4..5e30f1a 100644 --- a/docs/api/default-library-logger.md +++ b/docs/api/default-library-logger.md @@ -3,7 +3,7 @@ name: default-library-logger group: api category: facade update-time: 20260520 -description: Create the default library-facing console logger facade from shared global defaults. +description: Create the default library-facing console logger facade by wrapping the current shared default logger at call time. key-word: - library - facade @@ -32,6 +32,7 @@ Detailed rules explaining key parameters and behaviors - This API wraps `default_logger()` as a library facade. - Each call reflects the current shared default minimum level and default target at that moment. - The returned value exposes the narrower `LibraryLogger` surface rather than the full `Logger` surface. +- Later changes to shared defaults do not mutate an already-created facade value because the wrapped logger is captured when `default_library_logger()` is called. ### How to Use @@ -49,6 +50,8 @@ if logger.is_enabled(Level::Info) { In this example, the library facade mirrors the current global defaults. +And if the caller later unwraps it with `to_logger()`, the same captured default target and minimum level are still present on the full logger value. + ### Error Case e.g.: @@ -61,3 +64,5 @@ e.g.: 1. Use `to_logger()` if callers need the full sync logger surface. 2. This helper is useful for library-facing APIs that should stay narrower than `Logger`. + +3. Call `default_library_logger()` again after shared default changes if a fresh facade value should reflect the new defaults. diff --git a/docs/api/parse-and-build-library-logger.md b/docs/api/parse-and-build-library-logger.md index ca1b203..7b6fcd3 100644 --- a/docs/api/parse-and-build-library-logger.md +++ b/docs/api/parse-and-build-library-logger.md @@ -3,7 +3,7 @@ name: parse-and-build-library-logger group: api category: facade update-time: 20260613 -description: Parse JSON logger config text and build the library-facing sync logger facade while intentionally hiding direct runtime helper methods. +description: Parse JSON logger config text and build the library-facing sync logger facade by delegating to the configured runtime logger parse-and-build path and then wrapping the result. key-word: - library - facade @@ -13,7 +13,7 @@ key-word: ## Parse-and-build-library-logger -Parse raw JSON config text and build a `LibraryLogger[RuntimeSink]` in one step. This facade is the text-driven library counterpart to `parse_and_build_logger(...)`. +Parse raw JSON config text and build a `LibraryLogger[RuntimeSink]` in one step. This facade is the text-driven library counterpart to `parse_and_build_logger(...)` plus library-surface narrowing. ### Interface @@ -35,7 +35,8 @@ pub fn parse_and_build_library_logger( Detailed rules explaining key parameters and behaviors -- This API parses config text, validates it, builds the configured logger, and wraps it as a library facade. +- This API parses config text, validates it, builds the configured logger through `parse_and_build_logger(...)`, and wraps that same value as a library facade. +- 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 keeps a narrower surface than the underlying configured logger. - 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. @@ -68,6 +69,8 @@ ignore(full.pending_count()) In this example, the caller unwraps the library facade before using configured runtime helper methods. +And the unwrapped value still reflects the same `RuntimeSink` pipeline built from the parsed config text. + ### Error Case e.g.: @@ -82,3 +85,5 @@ e.g.: 1. This is the narrow library-oriented parse-and-build sync entry point. 2. Use `build_library_logger(...)` when the config is already typed. + +3. Use `to_logger()` when internal code later needs configured-runtime helpers or broader logger composition without changing the public facade type.