From 86ff04680beee934d4e0642ae4297acccd3fcb62 Mon Sep 17 00:00:00 2001
From: GeWuYou <95328647+GeWuYou@users.noreply.github.com>
Date: Sat, 11 Apr 2026 07:33:36 +0800
Subject: [PATCH] =?UTF-8?q?docs(config):=20=E6=9B=B4=E6=96=B0=20GodotYamlC?=
 =?UTF-8?q?onfigLoader=20=E5=BC=82=E6=AD=A5=E5=8A=A0=E8=BD=BD=E6=96=B9?=
 =?UTF-8?q?=E6=B3=95=E7=9A=84=E6=96=87=E6=A1=A3=E6=B3=A8=E9=87=8A?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- 添加了详细的 XML 文档注释说明方法功能和参数
- 补充了异常情况的详细说明包括 ArgumentNullException 和 ConfigLoadException
- 添加了关于运行时缓存同步执行原因的技术备注
- 保留了原有的继承特性标记并添加了完整的文档结构
---
 .../Config/GodotYamlConfigLoader.cs           | 23 +++++++++++++++++--
 1 file changed, 21 insertions(+), 2 deletions(-)

diff --git a/GFramework.Godot/Config/GodotYamlConfigLoader.cs b/GFramework.Godot/Config/GodotYamlConfigLoader.cs
index 68943834..5a6b6550 100644
--- a/GFramework.Godot/Config/GodotYamlConfigLoader.cs
+++ b/GFramework.Godot/Config/GodotYamlConfigLoader.cs
@@ -3,7 +3,6 @@ using GFramework.Core.Abstractions.Events;
 using GFramework.Game.Abstractions.Config;
 using GFramework.Game.Config;
 using GFramework.Godot.Extensions;
-using FileAccess = Godot.FileAccess;
 
 namespace GFramework.Godot.Config;
 
@@ -110,13 +109,33 @@ public sealed class GodotYamlConfigLoader : IConfigLoader
     /// </summary>
     public bool CanEnableHotReload => UsesSourceDirectoryDirectly(SourceRootPath);
 
-    /// <inheritdoc />
+    /// <summary>
+    ///     执行 Godot 场景下的配置加载。
+    ///     当源目录无法直接作为普通文件系统目录访问时，加载器会先把显式声明的 YAML 与 schema 文本同步到运行时缓存，
+    ///     再委托底层 <see cref="YamlConfigLoader" /> 完成解析与注册。
+    /// </summary>
+    /// <param name="registry">用于接收配置表的注册表。</param>
+    /// <param name="cancellationToken">取消令牌。</param>
+    /// <returns>表示加载流程的异步任务。</returns>
+    /// <exception cref="ArgumentNullException">当 <paramref name="registry" /> 为 <see langword="null" /> 时抛出。</exception>
+    /// <exception cref="ConfigLoadException">
+    ///     当缓存同步、配置文件读取、schema 读取或底层 YAML 加载失败时抛出。
+    /// </exception>
+    /// <remarks>
+    ///     运行时缓存同步阶段刻意保持同步执行。
+    ///     原因在于默认宿主环境可能需要通过 Godot 的目录和文件访问 API 读取 <c>res://</c> 资源，
+    ///     而这些访问边界目前仅以同步委托形式暴露；同时底层 <see cref="YamlConfigLoader" /> 也要求缓存文件在开始读取前已经完整落盘。
+    ///     这意味着当实例无法直接访问源目录时，调用线程会在进入真正的异步 YAML 解析前承担一次文件系统同步成本。
+    /// </remarks>
     public async Task LoadAsync(IConfigRegistry registry, CancellationToken cancellationToken = default)
     {
         ArgumentNullException.ThrowIfNull(registry);
 
         if (!CanEnableHotReload)
         {
+            // Runtime cache preparation must finish before the underlying loader starts enumerating files.
+            // This step intentionally stays synchronous because the default Godot environment exposes
+            // directory enumeration and file reads through synchronous engine/file-system APIs only.
             SynchronizeRuntimeCache(cancellationToken);
         }