docs: rebuild Debug API content

docs/api/XCEngine/Debug/FileLogSink/Flush.md

@@ -1,30 +1,37 @@
 # FileLogSink::Flush
 
-公开方法，详见头文件声明。
+把底层文件缓冲区刷新到磁盘。
 
 ```cpp
 void Flush() override;
 ```
 
-该方法声明于 `XCEngine/Debug/FileLogSink.h`，当前页面用于固定 `FileLogSink` 类目录下的方法级 canonical 路径。
+## 行为说明
 
-**参数：** 无。
+当前实现直接转发到 `Core::FileWriter::Flush()`。如果文件尚未成功打开，`FileWriter` 会返回 `false`，但 `FileLogSink::Flush` 本身不会上报错误。
 
-**返回：** `void` - 无返回值。
+需要注意的是，当前 `FileLogSink::Log` 在每次写入后已经主动调用一次 `Flush`，因此手动调用更多是为了表达语义，而不是补齐缺失步骤。
 
-**示例：**
+## 参数
+
+- 无。
+
+## 返回值
+
+- 无。
+
+## 线程语义
+
+- 通过 `Logger` 使用时通常是串行的。
+
+## 示例
 
 ```cpp
-#include <XCEngine/Debug/FileLogSink.h>
-
-void Example() {
-    XCEngine::Debug::FileLogSink object;
-    // 根据上下文补齐参数后调用 FileLogSink::Flush(...)。
-    (void)object;
-}
+XCEngine::Debug::FileLogSink sink("engine.log");
+sink.Flush();
 ```
 
 ## 相关文档
 
-- [返回类总览](FileLogSink.md)
-- [返回模块目录](../Debug.md)
+- [返回类型总览](FileLogSink.md)
+- [Log](Log.md)