📝 document file sink policy rotation methods

docs/api/file-sink-rotation-config.md

@@ -0,0 +1,77 @@
+---
+name: file-sink-rotation-config
+group: api
+category: sink
+update-time: 20260613
+description: Read the current optional rotation configuration from a FileSink.
+key-word:
+    - file
+    - sink
+    - rotation
+    - public
+---
+
+## File-sink-rotation-config
+
+Read the current optional rotation configuration from a `FileSink`. This helper exposes the active direct runtime rotation parameters when rotation is configured.
+
+### Interface
+
+```moonbit
+pub fn FileSink::rotation_config(self : FileSink) -> FileRotation? {
+```
+
+#### input
+
+- `self : FileSink` - File sink whose current rotation config should be inspected.
+
+#### output
+
+- `FileRotation?` - Current rotation config, or `None` if rotation is disabled.
+
+### Explanation
+
+Detailed rules explaining key parameters and behaviors
+
+- This method returns the sink's current optional `FileRotation` value directly.
+- It is more detailed than `rotation_enabled()` because it exposes the actual runtime rotation parameters.
+- A `None` result means the sink currently has no rotation policy.
+- This helper observes current policy state only and does not mutate the sink.
+
+### How to Use
+
+Here are some specific examples provided.
+
+#### When Need Active Rotation Parameters
+
+When support output or runtime checks should show the current direct rotation policy:
+```moonbit
+let rotation = sink.rotation_config()
+```
+
+In this example, callers can inspect the current optional rotation config on the concrete sink.
+
+#### When Branch On Optional Rotation Presence
+
+When code should behave differently for rotating and non-rotating file sinks:
+```moonbit
+match sink.rotation_config() {
+  Some(cfg) => ignore(cfg)
+  None => ()
+}
+```
+
+In this example, the optional return shape reflects whether runtime rotation is configured.
+
+### Error Case
+
+e.g.:
+- If callers only need a boolean answer, `rotation_enabled()` is the simpler API.
+
+- This helper does not report whether a past rotation succeeded; use `rotation_failures()` or `state()` for diagnostics.
+
+### Notes
+
+1. Use this helper when current runtime rotation parameters matter.
+
+2. It pairs naturally with `set_rotation(...)`, `clear_rotation()`, and `set_policy(...)`.

docs/api/file-sink-set-policy.md

@@ -0,0 +1,75 @@
+---
+name: file-sink-set-policy
+group: api
+category: sink
+update-time: 20260613
+description: Apply a bundled runtime file policy update to a FileSink.
+key-word:
+    - file
+    - sink
+    - policy
+    - public
+---
+
+## File-sink-set-policy
+
+Apply a bundled runtime file policy update to a `FileSink`. This helper updates append mode, auto-flush, and rotation together through one policy object on the concrete sink.
+
+### Interface
+
+```moonbit
+pub fn FileSink::set_policy(self : FileSink, policy : FileSinkPolicy) -> Unit {
+```
+
+#### input
+
+- `self : FileSink` - File sink whose runtime file policy should change.
+- `policy : FileSinkPolicy` - Bundled runtime file policy to apply.
+
+### Explanation
+
+Detailed rules explaining key parameters and behaviors
+
+- This method copies `policy.append`, `policy.auto_flush`, and `policy.rotation` onto the sink.
+- It updates the whole runtime file policy in one call instead of changing each field separately.
+- It does not reopen the sink, rotate immediately, or report success with a return value.
+- It is broader than `set_append_mode(...)`, `set_auto_flush(...)`, or `set_rotation(...)` because it applies all policy fields together.
+
+### How to Use
+
+Here are some specific examples provided.
+
+#### When Need Bundled Runtime Policy Changes
+
+When append, flush, and rotation should change together on a direct file sink:
+```moonbit
+sink.set_policy(FileSinkPolicy::new(
+  append=true,
+  auto_flush=false,
+  rotation=Some(file_rotation(2048, max_backups=2)),
+))
+```
+
+In this example, runtime file behavior is updated as one cohesive policy change.
+
+#### When Restore A Policy Snapshot
+
+When a previously captured or computed policy should be reapplied:
+```moonbit
+sink.set_policy(policy)
+```
+
+In this example, callers can restore a whole policy object without splitting it into separate setter calls.
+
+### Error Case
+
+e.g.:
+- If callers only need to change one field, a narrower setter may be clearer.
+
+- This helper does not report past open, write, flush, or rotation failures; inspect the failure counters or `state()` separately when diagnostics matter.
+
+### Notes
+
+1. Use this helper when runtime file policy should be treated as one cohesive object.
+
+2. It pairs naturally with `policy()` and `default_policy()`.

docs/api/index.md

@@ -146,8 +146,10 @@ BitLogger API navigation.
 - [file-sink-path.md](./file-sink-path.md)
 - [file-sink-auto-flush-enabled.md](./file-sink-auto-flush-enabled.md)
 - [file-sink-rotation-enabled.md](./file-sink-rotation-enabled.md)
+- [file-sink-rotation-config.md](./file-sink-rotation-config.md)
 - [file-sink-set-append-mode.md](./file-sink-set-append-mode.md)
 - [file-sink-set-auto-flush.md](./file-sink-set-auto-flush.md)
+- [file-sink-set-policy.md](./file-sink-set-policy.md)
 - [file-sink-clear-rotation.md](./file-sink-clear-rotation.md)
 - [file-sink-set-rotation.md](./file-sink-set-rotation.md)
 - [file-sink-policy-method.md](./file-sink-policy-method.md)