📝 补充runtime文档

docs/api/configured-logger-file-set-rotation.md

@@ -2,8 +2,8 @@
 name: configured-logger-file-set-rotation
 group: api
 category: runtime
-update-time: 20260512
-description: Update the rotation configuration used by the configured runtime file sink.
+update-time: 20260707
+description: Update the rotation policy used by the configured runtime file sink.
 key-word:
     - logger
     - runtime
@@ -13,21 +13,18 @@ key-word:
 
 ## Configured-logger-file-set-rotation
 
-Update the rotation configuration used by a `ConfiguredLogger` file sink. This helper changes runtime file rotation behavior without rebuilding the logger.
+Update the rotation policy used by a `ConfiguredLogger` file sink.
 
 ### Interface
 
 ```moonbit
-pub fn ConfiguredLogger::file_set_rotation(
-  self : ConfiguredLogger,
-  rotation : FileRotation?,
-) -> Bool {}
+pub fn ConfiguredLogger::file_set_rotation(self : ConfiguredLogger, rotation : FileRotation?) -> Bool {}
 ```
 
 #### input
 
-- `self : ConfiguredLogger` - Config-driven runtime logger whose rotation policy should change.
-- `rotation : FileRotation?` - New rotation config, or `None` to disable rotation.
+- `self : ConfiguredLogger` - Config-driven runtime logger whose file rotation policy should change.
+- `rotation : FileRotation?` - New runtime rotation policy.
 
 #### output
 
@@ -38,41 +35,20 @@ pub fn ConfiguredLogger::file_set_rotation(
 Detailed rules explaining key parameters and behaviors
 
 - File-backed sinks update their runtime rotation policy through the wrapped `RuntimeSink`.
-- Queued file sinks forward the update to the wrapped inner file sink.
-- Passing `None` disables rotation.
+- Queued file sinks forward the update to the wrapped inner file sink only when no queued records are pending.
 - Non-file sinks return `false`.
-
-### How to Use
-
-Here are some specific examples provided.
-
-#### When Need Runtime Rotation Tuning
-
-When a file sink should enable or change rotation dynamically:
-```moonbit
-ignore(logger.file_set_rotation(Some(file_rotation(1024, max_backups=3))))
-```
-
-In this example, runtime rotation behavior is updated without rebuilding the logger.
-
-#### When Need To Disable Rotation
-
-When the file sink should stop rotating:
-```moonbit
-let ok = logger.file_set_rotation(None)
-```
-
-In this example, the runtime file sink has its rotation policy cleared explicitly.
+- This helper changes policy only; it does not itself rotate or flush pending data.
+- If a queued file sink still has pending records, the update is rejected and returns `false` so already queued records are not later written under a different rotation policy than the one they were queued under.
 
 ### Error Case
 
 e.g.:
 - If the configured sink is not file-backed, the method returns `false`.
 
-- If callers only want to remove rotation, `file_clear_rotation()` is the more direct API.
+- If a queued file sink still has pending records, callers should flush or close it first before changing rotation policy.
 
 ### Notes
 
-1. Use this helper when setting a full runtime rotation config.
+1. Use this helper when runtime rotation policy should change without rebuilding the logger.
 
-2. It is useful for operational tuning without rebuilding the logger.
+2. On queued file sinks, clear pending records first so policy mutation does not retroactively affect already queued writes.