docs(core): 完善核心框架文档注释

- 为 AbstractContextUtility 类添加日志记录器文档注释
- 为 Architecture 类的 IsReady 属性和待初始化组件集合添加详细说明
- 修改 GitHub Actions workflow 使用 autobuild 模式替代手动构建
- 为 CoroutineScheduler 的 IsCoroutineAlive 方法添加完整文档注释
- 为 EnvironmentBase 类的 Initialize 方法和 Register 方法完善参数说明
- 为 IocContainer 的 OnContextReady 方法添加初始化日志记录器说明
- 为 WaitForEvent 协程指令类添加全面的 XML 文档注释和异常说明

.github/workflows/codeql.yml

@@ -45,10 +45,7 @@ jobs:
         uses: github/codeql-action/init@v4
         with:
           languages: csharp
-          build-mode: manual
+          build-mode: autobuild
-      # 手动构建项目
-      - name: Build
-        run: dotnet build -c Release
 
       # 执行CodeQL代码分析
       # 运行静态分析并生成结果报告

GFramework.Core/architecture/Architecture.cs

@@ -85,10 +85,15 @@ public abstract class Architecture(
 
     private readonly TaskCompletionSource _readyTcs = new(TaskCreationOptions.RunContinuationsAsynchronously);
 
+    /// <summary>
+    ///     获取一个布尔值，指示当前架构是否处于就绪状态。
+    ///     当前架构的阶段等于 ArchitecturePhase.Ready 时返回 true，否则返回 false。
+    /// </summary>
     public bool IsReady => CurrentPhase == ArchitecturePhase.Ready;
 
     /// <summary>
-    ///     待初始化组件的去重集合
+    ///     待初始化组件的去重集合。
+    ///     用于存储需要初始化的组件实例，确保每个组件仅被初始化一次。
     /// </summary>
     private readonly HashSet<IInitializable> _pendingInitializableSet = [];
 

GFramework.Core/coroutine/CoroutineScheduler.cs

@@ -32,11 +32,18 @@ public sealed class CoroutineScheduler(
     /// </summary>
     public int ActiveCoroutineCount { get; private set; }
 
+    /// <summary>
+    ///     检查指定的协程句柄是否仍然存活
+    /// </summary>
+    /// <param name="handle">要检查的协程句柄</param>
+    /// <returns>如果协程仍然存活则返回 true，否则返回 false</returns>
     public bool IsCoroutineAlive(CoroutineHandle handle)
     {
+        // 检查元数据字典中是否包含指定的协程句柄
         return _metadata.ContainsKey(handle);
     }
 
+
     #region Run / Update
 
     /// <summary>

GFramework.Core/coroutine/instructions/WaitForEvent.cs

@@ -15,7 +15,11 @@ using GFramework.Core.Abstractions.coroutine;
 using GFramework.Core.Abstractions.events;
 
 namespace GFramework.Core.coroutine.instructions;
-
+/// <summary>
+///     WaitForEvent 类用于等待特定事件的发生，并提供事件数据和完成状态。
+///     实现了 IYieldInstruction 和 IDisposable 接口，支持协程等待和资源释放。
+/// </summary>
+/// <typeparam name="TEvent">事件类型</typeparam>
 public sealed class WaitForEvent<TEvent> : IYieldInstruction, IDisposable
 {
     private bool _disposed;
@@ -23,60 +27,60 @@ public sealed class WaitForEvent<TEvent> : IYieldInstruction, IDisposable
     private IUnRegister? _unRegister;
 
     /// <summary>
-    ///     初始化等待事件的指令
+    ///     初始化 WaitForEvent 实例，注册事件监听器以等待指定事件。
     /// </summary>
-    /// <param name="eventBus">事件总线实例</param>
+    /// <param name="eventBus">事件总线实例，用于注册和监听事件。</param>
+    /// <exception cref="ArgumentNullException">当 eventBus 为 null 时抛出异常。</exception>
     public WaitForEvent(IEventBus eventBus)
     {
         var eventBus1 = eventBus ?? throw new ArgumentNullException(nameof(eventBus));
 
-        // 注册事件监听器
+        // 注册事件监听器，当事件触发时调用 OnEventTriggered 方法
         _unRegister = eventBus1.Register<TEvent>(OnEventTriggered);
     }
 
     /// <summary>
-    ///     获取接收到的事件数据
+    ///     获取接收到的事件数据。仅在事件触发后可用。
     /// </summary>
     public TEvent? EventData { get; private set; }
 
     /// <summary>
-    ///     释放资源
+    ///     释放 WaitForEvent 实例占用的资源，包括注销事件监听器。
     /// </summary>
     public void Dispose()
     {
         if (_disposed) return;
 
-        // 注销事件注册并清理资源
+        // 注销事件注册并清理资源，防止内存泄漏
         _unRegister?.UnRegister();
         _unRegister = null;
         _disposed = true;
     }
 
     /// <summary>
-    ///     获取等待是否已完成
+    ///     获取等待是否已完成。当事件触发后，此属性将返回 true。
     /// </summary>
     public bool IsDone => _done;
 
     /// <summary>
-    ///     更新方法，用于处理时间更新逻辑
+    ///     更新方法，用于处理时间更新逻辑。通常由协程系统调用。
     /// </summary>
-    /// <param name="deltaTime">时间增量</param>
+    /// <param name="deltaTime">时间增量（秒），表示自上次更新以来经过的时间。</param>
     public void Update(double deltaTime)
     {
-        // 事件的完成由事件回调设置
+        // 如果事件已完成且事件监听器仍存在，则注销监听器以释放资源
-        // 如果已完成，确保注销事件监听器
         if (!_done || _unRegister == null) return;
         _unRegister.UnRegister();
         _unRegister = null;
     }
 
     /// <summary>
-    ///     事件触发时的回调处理
+    ///     事件触发时的回调处理方法。设置事件数据并标记等待完成。
     /// </summary>
-    /// <param name="eventData">事件数据</param>
+    /// <param name="eventData">触发事件时传递的数据。</param>
     private void OnEventTriggered(TEvent eventData)
     {
         EventData = eventData;
         _done = true;
     }
-}
+}

GFramework.Core/environment/EnvironmentBase.cs

@@ -69,15 +69,19 @@ public abstract class EnvironmentBase : ContextAwareBase, IEnvironment
         Register(key, value);
     }
 
+    /// <summary>
+    ///     抽象方法，用于初始化操作。具体实现由派生类提供。
+    /// </summary>
     public abstract void Initialize();
 
     /// <summary>
     ///     注册键值对到环境值字典中
     /// </summary>
-    /// <param name="key">要注册的键</param>
+    /// <param name="key">要注册的键，作为字典中的唯一标识符</param>
-    /// <param name="value">要注册的值</param>
+    /// <param name="value">要注册的值，与键关联的数据</param>
     protected void Register(string key, object value)
     {
+        // 将键值对添加到Values字典中
         Values[key] = value;
     }
 }

GFramework.Core/ioc/IocContainer.cs

@@ -53,12 +53,17 @@ public class IocContainer : ContextAwareBase, IIocContainer
 
     #region Register
 
+    /// <summary>
+    /// 当上下文准备就绪时调用此方法，用于初始化日志记录器。
+    /// </summary>
     protected override void OnContextReady()
     {
+        // 创建日志记录器实例，并将其赋值给_logger字段
         _logger =
             LoggerFactoryResolver.Provider.CreateLogger(nameof(IocContainer));
     }
 
+
     /// <summary>
     ///     注册单例
     ///     一个类型只允许一个实例

GFramework.Core/utility/AbstractContextUtility.cs

@@ -11,6 +11,9 @@ namespace GFramework.Core.utility;
 /// </summary>
 public abstract class AbstractContextUtility : ContextAwareBase, IContextUtility
 {
+    /// <summary>
+    ///  日志记录器
+    /// </summary>
     protected ILogger Logger = null !;
 
     /// <summary>