📝 document public config and level aliases

docs/api/async-flush-policy.md

@@ -0,0 +1,71 @@
+---
+name: async-flush-policy
+group: api
+category: async
+update-time: 20260613
+description: Public flush policy alias used by AsyncLoggerConfig and async worker flushing.
+key-word:
+    - async
+    - flush
+    - alias
+    - public
+---
+
+## Async-flush-policy
+
+`AsyncFlushPolicy` is the public enum that defines when an async logger should call its flush function. It is a direct alias to the async model enum used by `AsyncLoggerConfig`, worker execution, and async logger state reporting.
+
+### Interface
+
+```moonbit
+pub type AsyncFlushPolicy = @utils.AsyncFlushPolicy
+```
+
+#### output
+
+- `AsyncFlushPolicy` - Public async flush enum with the variants `Never`, `Batch`, and `Shutdown`.
+
+### Explanation
+
+Detailed rules explaining key parameters and behaviors
+
+- This is a type alias, not a separate lifecycle wrapper.
+- `AsyncFlushPolicy::Never` skips explicit flush calls from the async worker.
+- `AsyncFlushPolicy::Batch` calls the configured flush function after each processed batch.
+- `AsyncFlushPolicy::Shutdown` calls the configured flush function once after the worker loop exits.
+- The current flush policy is also exposed through `AsyncLogger::flush_policy()` and included in `AsyncLoggerState`.
+
+### How to Use
+
+Here are some specific examples provided.
+
+#### When Need Explicit Flush After Every Processed Batch
+
+When buffered sinks should flush incrementally during worker execution:
+```moonbit
+let config = AsyncLoggerConfig::new(flush=AsyncFlushPolicy::Batch)
+```
+
+In this example, each batch run triggers the provided flush callback.
+
+#### When Need One Final Flush During Shutdown
+
+When sink flushing should be deferred until the worker finishes:
+```moonbit
+let config = AsyncLoggerConfig::new(flush=AsyncFlushPolicy::Shutdown)
+```
+
+In this example, flushing happens when the worker loop exits instead of after each batch.
+
+### Error Case
+
+e.g.:
+- If async config text uses unsupported flush policy text, async config parsing raises a failure.
+
+- If a sink never needs explicit flushing, `Batch` or `Shutdown` can add unnecessary work without changing output.
+
+### Notes
+
+1. This policy only affects the async logger path and only matters when the configured sink has a meaningful flush function.
+
+2. `AsyncFlushPolicy::Never` is the default in `AsyncLoggerConfig::new(...)`.