docs: rebuild Debug API content

docs/api/XCEngine/Debug/Logger/Log.md

@@ -1,36 +1,77 @@
 # Logger::Log
 
-公开方法，详见头文件声明。
+构造一条 `LogEntry` 并把它分发给所有已注册 sink。
 
 ```cpp
-void Log(LogLevel level, LogCategory category, const Containers::String& message, const char* file = nullptr, int32_t line = 0, const char* function = nullptr);
+void Log(
+    LogLevel level,
+    LogCategory category,
+    const Containers::String& message,
+    const char* file = nullptr,
+    int32_t line = 0,
+    const char* function = nullptr
+);
 ```
 
-该方法声明于 `XCEngine/Debug/Logger.h`，当前页面用于固定 `Logger` 类目录下的方法级 canonical 路径。
+## 行为说明
 
-**参数：**
-- `level` - 参数语义详见头文件声明。
-- `category` - 参数语义详见头文件声明。
-- `message` - 参数语义详见头文件声明。
-- `file` - 参数语义详见头文件声明。
-- `line` - 参数语义详见头文件声明。
-- `function` - 参数语义详见头文件声明。
+当前实现依次执行以下步骤：
 
-**返回：** `void` - 无返回值。
+1. 如果 `Logger` 尚未初始化，先调用 `Initialize()`。
+2. 如果 `level < m_minimumLevel`，直接丢弃日志。
+3. 如果 category 对应的启用位为关闭状态，直接丢弃日志。
+4. 构造 `LogEntry`，填充：
+   - `level`
+   - `category`
+   - `message`
+   - `file`
+   - `line`
+   - `function`
+   - 当前秒级时间戳
+   - 当前线程哈希值
+5. 在互斥区内遍历所有 sink 并调用其 `Log(entry)`。
 
-**示例：**
+需要注意：
+
+- 如果没有注册任何 sink，日志会被静默丢弃。
+- 当前时间戳粒度是“秒”，不是毫秒或微秒。
+- 当前线程 ID 是哈希结果，不保证与系统线程号一致。
+
+## 参数
+
+- `level` - 日志级别。
+- `category` - 日志分类。
+- `message` - 日志文本。
+- `file` - 可选的源文件路径。
+- `line` - 可选的源码行号。
+- `function` - 可选的函数名。
+
+## 返回值
+
+- 无。
+
+## 线程语义
+
+- sink 分发过程在互斥区内执行。
+- `SetMinimumLevel` 和 `SetCategoryEnabled` 当前无锁，因此在高并发日志期间动态修改配置时要自行承担竞争风险。
+
+## 示例
 
 ```cpp
-#include <XCEngine/Debug/Logger.h>
+using namespace XCEngine::Debug;
 
-void Example() {
-    XCEngine::Debug::Logger object;
-    // 根据上下文补齐参数后调用 Logger::Log(...)。
-    (void)object;
-}
+Logger::Get().Log(
+    LogLevel::Warning,
+    LogCategory::General,
+    "Fallback code path selected",
+    __FILE__,
+    __LINE__,
+    __FUNCTION__
+);
 ```
 
 ## 相关文档
 
-- [返回类总览](Logger.md)
-- [返回模块目录](../Debug.md)
+- [返回类型总览](Logger.md)
+- [Verbose](Verbose.md)
+- [XE_LOG 宏所在类型页](Logger.md)