📝 Align API docs with updated interface template

2026-05-30 15:42:25 +00:00 · 2026-05-12 13:20:36 +08:00
parent 8dbadd5938
commit 4d913aa642
47 changed files with 2228 additions and 406 deletions
@@ -0,0 +1,80 @@
+---
+name: async-runtime-mode-label
+group: api
+category: async
+update-time: 20260512
+description: Convert AsyncRuntimeMode into a stable string label for logs, JSON, and diagnostics.
+key-word:
+    - async
+    - runtime
+    - label
+    - public
+---
+
+## Async-runtime-mode-label
+
+Convert `AsyncRuntimeMode` into a stable string label. This helper is useful when runtime mode should be logged, serialized, or exposed through human-readable diagnostics.
+
+### Interface
+
+```moonbit
+pub fn async_runtime_mode_label(mode : AsyncRuntimeMode) -> String {}
+```
+
+#### input
+
+- `mode : AsyncRuntimeMode` - Runtime mode enum value.
+
+#### output
+
+- `String` - Stable mode label such as `native_worker` or `compatibility`.
+
+### Explanation
+
+Detailed rules explaining key parameters and behaviors
+
+- The returned value is intended for diagnostics and stable output, not just debugging prints.
+- It keeps mode serialization logic in one place.
+- This helper is used by async runtime JSON helpers.
+- Labels are more stable for telemetry and docs than ad hoc manual matching at call sites.
+
+### How to Use
+
+Here are some specific examples provided.
+
+#### When Need A Stable Log Label
+
+When the mode should be included in structured or plain logs:
+```moonbit
+println(async_runtime_mode_label(async_runtime_mode()))
+```
+
+In this example, the label is directly usable in diagnostics.
+
+#### When Build Custom Serialization
+
+When callers want to embed the mode into their own payloads:
+```moonbit
+let label = async_runtime_mode_label(async_runtime_mode())
+```
+
+In this example, code gets a stable string without duplicating enum matching logic.
+
+### Error Case
+
+e.g.:
+- This API assumes a valid `AsyncRuntimeMode` input and does not expose a normal runtime error path.
+
+- If callers need the whole runtime object rather than a string label, use `async_runtime_state()`.
+
+### Notes
+
+Notes are here.
+
+1. Prefer this helper over repeated manual `match` blocks when only a label is needed.
+
+2. The label format is especially useful for JSON and telemetry.
+
+3. This API complements `async_runtime_mode()` and `async_runtime_state()`.
+
+4. Keep downstream consumers aligned with these stable labels rather than inventing local variants.