📝 clarify library helper visibility

This commit is contained in:
Nanaloveyuki
2026-06-14 08:50:34 +08:00
parent 35e87f1761
commit 20919618ce
4 changed files with 12 additions and 0 deletions
+3
View File
@@ -37,6 +37,7 @@ Detailed rules explaining key parameters and behaviors
- The embedded config still goes through the normal runtime logger build path, including runtime sink selection, optional queue wrapping, and timestamp application.
- The returned facade wraps the same underlying `ConfiguredLogger` value that `build_logger(...)` would produce directly.
- The facade intentionally exposes a smaller logging surface than the full configured runtime logger.
- In particular, the configured runtime helper surface is preserved rather than rebuilt, but it is intentionally not directly exposed on the returned facade. Queue metrics, flush or drain helpers, and file controls stay behind `to_logger()` instead of disappearing.
- 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 remain on the underlying `ConfiguredLogger`, not on the returned facade itself.
- Call `to_logger()` if a caller must recover the underlying full logger object.
@@ -70,6 +71,8 @@ In this example, the library facade is unwrapped before using runtime-specific h
And the unwrapped value still carries the same `RuntimeSink` pipeline built from the original config.
And unlike `ApplicationLogger`, the narrower builder result does not expose those runtime helpers directly on the facade surface.
#### When Need A Per-call Target Override Through The Library Builder Facade
When typed library config should still build a facade that allows a one-write target override without unwrapping first: