From 56ba5836806f79176d7b1895fadbdb45a5906d51 Mon Sep 17 00:00:00 2001 From: Nanaloveyuki Date: Sat, 13 Jun 2026 23:37:55 +0800 Subject: [PATCH] :memo: refresh runtime file export docs --- docs/api/file-sink-policy-to-json.md | 7 ++++--- docs/api/file-sink-state-to-json.md | 7 ++++--- docs/api/runtime-file-state-to-json.md | 6 +++--- docs/api/stringify-file-sink-policy.md | 5 +++-- docs/api/stringify-file-sink-state.md | 7 ++++--- docs/api/stringify-runtime-file-state.md | 1 + 6 files changed, 19 insertions(+), 14 deletions(-) diff --git a/docs/api/file-sink-policy-to-json.md b/docs/api/file-sink-policy-to-json.md index e8456e7..666b23d 100644 --- a/docs/api/file-sink-policy-to-json.md +++ b/docs/api/file-sink-policy-to-json.md @@ -37,6 +37,7 @@ Detailed rules explaining key parameters and behaviors - `rotation` is exported as `null` when rotation is disabled. - This helper exports runtime file policy, not current file health counters or availability. - The JSON value is useful for policy snapshots, comparisons, and diagnostics payloads. +- Typical inputs come from `FileSink::policy()`, `RuntimeSink::file_policy()`, or `ConfiguredLogger::file_policy()`. ### How to Use @@ -44,9 +45,9 @@ Here are some specific examples provided. #### When Need Structured Policy Snapshots -When file sink policy should be embedded into a larger JSON payload: +When file policy should be embedded into a larger JSON payload: ```moonbit -let value = file_sink_policy_to_json(sink.policy()) +let value = file_sink_policy_to_json(runtime.file_policy()) ``` In this example, the runtime file policy becomes a reusable structured value. @@ -71,4 +72,4 @@ e.g.: 1. Use this helper when downstream code expects `JsonValue` rather than text. -2. It pairs naturally with `policy()` and `default_policy()` runtime accessors. +2. It pairs naturally with `FileSink::policy()`, `RuntimeSink::file_policy()`, and related default-policy accessors. diff --git a/docs/api/file-sink-state-to-json.md b/docs/api/file-sink-state-to-json.md index ea3a297..da350bc 100644 --- a/docs/api/file-sink-state-to-json.md +++ b/docs/api/file-sink-state-to-json.md @@ -37,6 +37,7 @@ Detailed rules explaining key parameters and behaviors - `rotation` is exported as `null` when rotation is disabled. - This helper exports state snapshots, not mutable runtime control handles. - It is useful when file sink state should be embedded into larger diagnostics payloads. +- Typical inputs come from `FileSink::state()`, `RuntimeSink::file_state()`, or `ConfiguredLogger::file_state()`. ### How to Use @@ -44,9 +45,9 @@ Here are some specific examples provided. #### When Need Structured File Diagnostics -When file sink status should be composed into a larger JSON object: +When file runtime status should be composed into a larger JSON object: ```moonbit -let value = file_sink_state_to_json(sink.state()) +let value = file_sink_state_to_json(runtime.file_state()) ``` In this example, callers receive a structured file-state snapshot instead of plain text. @@ -71,4 +72,4 @@ e.g.: 1. Use this helper when diagnostics consumers expect `JsonValue`. -2. It pairs naturally with `FileSink::state()` and `ConfiguredLogger::file_state()`. +2. It pairs naturally with `FileSink::state()`, `RuntimeSink::file_state()`, and `ConfiguredLogger::file_state()`. diff --git a/docs/api/runtime-file-state-to-json.md b/docs/api/runtime-file-state-to-json.md index f1861f6..fad6674 100644 --- a/docs/api/runtime-file-state-to-json.md +++ b/docs/api/runtime-file-state-to-json.md @@ -13,7 +13,7 @@ key-word: ## Runtime-file-state-to-json -Convert `RuntimeFileState` into a `JsonValue`. This helper exports both file sink status and outer queue metrics for queued file runtime diagnostics. +Convert `RuntimeFileState` into a `JsonValue`. This helper exports both file sink status and queue metrics for combined runtime file diagnostics. ### Interface @@ -36,7 +36,7 @@ Detailed rules explaining key parameters and behaviors - The output includes `file`, `queued`, `pending_count`, and `dropped_count`. - `file` is itself exported as a nested file sink state object. - This helper is richer than `file_sink_state_to_json(...)` because it also carries queue wrapping context. -- It is useful for `ConfiguredLogger::file_runtime_state()` and similar queued-file diagnostics flows. +- It is useful for `RuntimeSink::file_runtime_state()`, `ConfiguredLogger::file_runtime_state()`, and similar queued-file diagnostics flows. ### How to Use @@ -71,4 +71,4 @@ e.g.: 1. Use this helper when file and queue runtime context should stay together. -2. It is especially useful for configured queued file loggers. +2. It is especially useful for queued file runtime paths, whether accessed directly or through configured loggers. diff --git a/docs/api/stringify-file-sink-policy.md b/docs/api/stringify-file-sink-policy.md index 6bb3ba0..74c53af 100644 --- a/docs/api/stringify-file-sink-policy.md +++ b/docs/api/stringify-file-sink-policy.md @@ -38,6 +38,7 @@ Detailed rules explaining key parameters and behaviors - `pretty=true` returns indented JSON for human inspection. - This helper builds on top of `file_sink_policy_to_json(...)`. - The output is suited for support dumps, policy snapshots, and generated diagnostics text. +- Typical inputs come from `FileSink::policy()`, `RuntimeSink::file_policy()`, or `ConfiguredLogger::file_policy()`. ### How to Use @@ -47,7 +48,7 @@ Here are some specific examples provided. When current file policy should be printed for diagnostics: ```moonbit -println(stringify_file_sink_policy(sink.policy(), pretty=true)) +println(stringify_file_sink_policy(runtime.file_policy(), pretty=true)) ``` In this example, the runtime file policy is rendered in readable JSON. @@ -56,7 +57,7 @@ In this example, the runtime file policy is rendered in readable JSON. When a file policy snapshot should stay small: ```moonbit -let text = stringify_file_sink_policy(sink.policy()) +let text = stringify_file_sink_policy(runtime.file_policy()) ``` In this example, compact JSON is produced without extra formatting logic. diff --git a/docs/api/stringify-file-sink-state.md b/docs/api/stringify-file-sink-state.md index 38d03f9..cf8f731 100644 --- a/docs/api/stringify-file-sink-state.md +++ b/docs/api/stringify-file-sink-state.md @@ -38,6 +38,7 @@ Detailed rules explaining key parameters and behaviors - `pretty=true` returns indented JSON for human diagnostics. - This helper builds on top of `file_sink_state_to_json(...)`. - The output is well-suited for support dumps, incident reports, and log snapshots. +- Typical inputs come from `FileSink::state()`, `RuntimeSink::file_state()`, or `ConfiguredLogger::file_state()`. ### How to Use @@ -45,9 +46,9 @@ Here are some specific examples provided. #### When Need Human-readable File Diagnostics -When file sink status should be printed for operators: +When file runtime status should be printed for operators: ```moonbit -println(stringify_file_sink_state(sink.state(), pretty=true)) +println(stringify_file_sink_state(runtime.file_state(), pretty=true)) ``` In this example, the full file-state snapshot is rendered in readable JSON. @@ -56,7 +57,7 @@ In this example, the full file-state snapshot is rendered in readable JSON. When a snapshot should stay small: ```moonbit -let text = stringify_file_sink_state(sink.state()) +let text = stringify_file_sink_state(runtime.file_state()) ``` In this example, compact JSON is returned without extra formatting logic. diff --git a/docs/api/stringify-runtime-file-state.md b/docs/api/stringify-runtime-file-state.md index 315e231..5c8998a 100644 --- a/docs/api/stringify-runtime-file-state.md +++ b/docs/api/stringify-runtime-file-state.md @@ -38,6 +38,7 @@ Detailed rules explaining key parameters and behaviors - `pretty=true` returns indented JSON for human diagnostics. - This helper builds on top of `runtime_file_state_to_json(...)`. - The output is useful when queued file runtime state should be printed directly during support or incident handling. +- Typical inputs come from `RuntimeSink::file_runtime_state()` or `ConfiguredLogger::file_runtime_state()`. ### How to Use