📝 consolidate logger API and async lifecycle guidance

docs/api/parse-async-logger-config-text.md

@@ -2,8 +2,8 @@
 name: parse-async-logger-config-text
 group: api
 category: async
-update-time: 20260520
-description: Parse JSON text into an AsyncLoggerConfig.
+update-time: 20260614
+description: Parse JSON text into an AsyncLoggerConfig, applying async config defaults and accepted policy aliases.
 key-word:
     - async
     - config
@@ -34,7 +34,11 @@ pub fn parse_async_logger_config_text(input : String) -> AsyncLoggerConfig raise
 Detailed rules explaining key parameters and behaviors
 
 - This helper parses only the async config portion, not the embedded sync `LoggerConfig`.
-- Parsed values follow the same normalization and enum validation rules as other async config helpers.
+- Missing `max_pending`, `overflow`, `max_batch`, `linger_ms`, and `flush` fields fall back to the same defaults used by `AsyncLoggerConfig::new(...)`.
+- Parsed values then flow through `AsyncLoggerConfig::new(...)`, so `max_batch` and `linger_ms` receive the same constructor normalization.
+- Overflow parsing accepts both `DropNewest` and the compatibility alias `DropLatest`.
+- Flush parsing accepts both `Never` and the compatibility alias `None`.
+- The error surface here is the general `Failure` path used by the async config utilities, including malformed JSON, non-object roots, wrong field types, and unsupported enum text.
 - Use this API when async policy comes from config text but sink choice is still assembled elsewhere.
 
 ### How to Use
@@ -52,6 +56,17 @@ let config = parse_async_logger_config_text(
 
 In this example, async queue and flush policy are parsed from text into a typed config object.
 
+#### When Need Alias-friendly Async Policy Parsing
+
+When external config may use compatibility labels:
+```moonbit
+let config = parse_async_logger_config_text(
+  "{\"overflow\":\"DropLatest\",\"flush\":\"None\"}",
+)
+```
+
+In this example, parser aliases are accepted and normalized into the public enum values.
+
 ### Error Case
 
 e.g.:
@@ -59,8 +74,12 @@ e.g.:
 
 - If enum names such as `overflow` or `flush` are unsupported, parsing raises an error.
 
+- If a field is present with the wrong JSON type, parsing raises an error instead of silently coercing it.
+
 ### Notes
 
 1. Use this helper when only async policy is text-driven.
 
 2. Use `parse_async_logger_build_config_text(...)` when both sync logger config and async config come from the same JSON payload.
+
+3. Omitted fields fall back to the default async config values rather than causing a missing-field error.