docs(extensions): 为扩展方法添加英文注释以支持国际化

为 ListExtensions、LookupX、NullObject、SpanExtensions、ObjectExtensions 和 ReadOnlySpanExtensions 添加英文 XML 文档注释，使代码库支持多语言文档，便于国际开发者使用和理解 API。

Author: AlianBlank

GameFrameX.Foundation.Extensions/IDictionaryExtensions.cs

@@ -34,18 +34,24 @@
 namespace GameFrameX.Foundation.Extensions;
 
 /// <summary>
-/// 提供List和IEnumerable的扩展方法
+/// 提供 List 和 IEnumerable 的扩展方法。
 /// </summary>
+/// <remarks>
+/// Provides extension methods for List and IEnumerable.
+/// </remarks>
 public static class ListExtensions
 {
     /// <summary>
-    /// 异步遍历List中的每个元素并执行指定操作
+    /// 异步遍历 List 中的每个元素并执行指定操作。
     /// </summary>
-    /// <typeparam name="T">列表元素类型</typeparam>
-    /// <param name="list">要遍历的列表</param>
-    /// <param name="func">要执行的异步操作</param>
-    /// <returns>表示异步操作的任务</returns>
-    /// <exception cref="ArgumentNullException">当list或func为null时抛出</exception>
+    /// <remarks>
+    /// Asynchronically iterates through each element in the list and executes the specified operation.
+    /// </remarks>
+    /// <typeparam name="T">列表元素类型 / The type of list elements.</typeparam>
+    /// <param name="list">要遍历的列表，不能为 <c>null</c> / The list to iterate, cannot be <c>null</c>.</param>
+    /// <param name="func">要执行的异步操作，不能为 <c>null</c> / The asynchronous operation to execute, cannot be <c>null</c>.</param>
+    /// <returns>表示异步操作的任务 / A task representing the asynchronous operation.</returns>
+    /// <exception cref="ArgumentNullException">当 <paramref name="list"/> 或 <paramref name="func"/> 为 <c>null</c> 时抛出 / Thrown when <paramref name="list"/> or <paramref name="func"/> is <c>null</c>.</exception>
     public static async Task ForEachAsync<T>(this List<T> list, Func<T, Task> func)
     {
         ArgumentNullException.ThrowIfNull(list, nameof(list));
@@ -58,13 +64,16 @@ public static async Task ForEachAsync<T>(this List<T> list, Func<T, Task> func)
     }
 
     /// <summary>
-    /// 异步遍历IEnumerable中的每个元素并执行指定操作
+    /// 异步遍历 IEnumerable 中的每个元素并执行指定操作。
     /// </summary>
-    /// <typeparam name="T">集合元素类型</typeparam>
-    /// <param name="source">要遍历的集合</param>
-    /// <param name="action">要执行的异步操作</param>
-    /// <returns>表示异步操作的任务</returns>
-    /// <exception cref="ArgumentNullException">当source或action为null时抛出</exception>
+    /// <remarks>
+    /// Asynchronously iterates through each element in the IEnumerable and executes the specified operation.
+    /// </remarks>
+    /// <typeparam name="T">集合元素类型 / The type of collection elements.</typeparam>
+    /// <param name="source">要遍历的集合，不能为 <c>null</c> / The collection to iterate, cannot be <c>null</c>.</param>
+    /// <param name="action">要执行的异步操作，不能为 <c>null</c> / The asynchronous operation to execute, cannot be <c>null</c>.</param>
+    /// <returns>表示异步操作的任务 / A task representing the asynchronous operation.</returns>
+    /// <exception cref="ArgumentNullException">当 <paramref name="source"/> 或 <paramref name="action"/> 为 <c>null</c> 时抛出 / Thrown when <paramref name="source"/> or <paramref name="action"/> is <c>null</c>.</exception>
     public static async Task ForEachAsync<T>(this IEnumerable<T> source, Func<T, Task> action)
     {
         ArgumentNullException.ThrowIfNull(source, nameof(source));

GameFrameX.Foundation.Extensions/ListExtensions.cs

@@ -38,19 +38,25 @@ namespace GameFrameX.Foundation.Extensions;
 
 /// <summary>
 /// 表示键和元素之间的多对多关系的集合。
-/// 提供了一种高效的方式来存储和检索与特定键关联的多个元素。
 /// </summary>
-/// <typeparam name="TKey">键的泛型类型。</typeparam>
-/// <typeparam name="TElement">元素的泛型类型。</typeparam>
+/// <remarks>
+/// A collection that represents a many-to-many relationship between keys and elements.
+/// Provides an efficient way to store and retrieve multiple elements associated with a specific key.
+/// </remarks>
+/// <typeparam name="TKey">键的泛型类型 / The generic type of keys.</typeparam>
+/// <typeparam name="TElement">元素的泛型类型 / The generic type of elements.</typeparam>
 public class LookupX<TKey, TElement> : IEnumerable<List<TElement>>
 {
     private readonly IDictionary<TKey, List<TElement>> _dictionary;
 
     /// <summary>
     /// 使用指定的字典初始化一个新的 <see cref="LookupX&lt;TKey, TElement&gt;" /> 实例。
     /// </summary>
-    /// <param name="dic">用于存储键和元素列表的字典。不能为 null。</param>
-    /// <exception cref="ArgumentNullException">当 <paramref name="dic"/> 为 null 时抛出。</exception>
+    /// <remarks>
+    /// Initializes a new instance of the <see cref="LookupX&lt;TKey, TElement&gt;" /> class with the specified dictionary.
+    /// </remarks>
+    /// <param name="dic">用于存储键和元素列表的字典，不能为 null / The dictionary used to store keys and element lists, cannot be null.</param>
+    /// <exception cref="ArgumentNullException">当 <paramref name="dic"/> 为 null 时抛出 / Thrown when <paramref name="dic"/> is null.</exception>
     public LookupX(IDictionary<TKey, List<TElement>> dic)
     {
         ArgumentNullException.ThrowIfNull(dic, nameof(dic));
@@ -60,8 +66,11 @@ public LookupX(IDictionary<TKey, List<TElement>> dic)
     /// <summary>
     /// 使用指定的并发字典初始化一个新的 <see cref="LookupX&lt;TKey, TElement&gt;" /> 实例。
     /// </summary>
-    /// <param name="dic">用于存储键和元素列表的并发字典。不能为 null。</param>
-    /// <exception cref="ArgumentNullException">当 <paramref name="dic"/> 为 null 时抛出。</exception>
+    /// <remarks>
+    /// Initializes a new instance of the <see cref="LookupX&lt;TKey, TElement&gt;" /> class with the specified concurrent dictionary.
+    /// </remarks>
+    /// <param name="dic">用于存储键和元素列表的并发字典，不能为 null / The concurrent dictionary used to store keys and element lists, cannot be null.</param>
+    /// <exception cref="ArgumentNullException">当 <paramref name="dic"/> 为 null 时抛出 / Thrown when <paramref name="dic"/> is null.</exception>
     public LookupX(ConcurrentDictionary<TKey, List<TElement>> dic)
     {
         ArgumentNullException.ThrowIfNull(dic, nameof(dic));
@@ -71,7 +80,10 @@ public LookupX(ConcurrentDictionary<TKey, List<TElement>> dic)
     /// <summary>
     /// 获取集合中的键值对数量。
     /// </summary>
-    /// <value>表示集合中包含的键值对的总数。</value>
+    /// <remarks>
+    /// Gets the number of key-value pairs in the collection.
+    /// </remarks>
+    /// <value>表示集合中包含的键值对的总数 / The total number of key-value pairs contained in the collection.</value>
     public int Count
     {
         get { return _dictionary.Count; }
@@ -81,9 +93,13 @@ public int Count
     /// 获取与指定键关联的元素列表。
     /// 如果键不存在，则返回一个空的元素列表。
     /// </summary>
-    /// <param name="key">要查找的键。不能为 null。</param>
-    /// <returns>与指定键关联的元素列表。如果键不存在，返回空列表。</returns>
-    /// <exception cref="ArgumentNullException">当 <paramref name="key"/> 为 null 时抛出。</exception>
+    /// <remarks>
+    /// Gets the list of elements associated with the specified key.
+    /// If the key does not exist, returns an empty element list.
+    /// </remarks>
+    /// <param name="key">要查找的键，不能为 null / The key to look up, cannot be null.</param>
+    /// <returns>与指定键关联的元素列表，如果键不存在，返回空列表 / The list of elements associated with the specified key; returns an empty list if the key does not exist.</returns>
+    /// <exception cref="ArgumentNullException">当 <paramref name="key"/> 为 null 时抛出 / Thrown when <paramref name="key"/> is null.</exception>
     public List<TElement> this[TKey key]
     {
         get
@@ -96,7 +112,10 @@ public List<TElement> this[TKey key]
     /// <summary>
     /// 返回一个枚举器，该枚举器可以遍历集合中的每个元素列表。
     /// </summary>
-    /// <returns>一个 <see cref="IEnumerator{T}"/> 枚举器，用于遍历集合中的每个元素列表。</returns>
+    /// <remarks>
+    /// Returns an enumerator that can iterate through each element list in the collection.
+    /// </remarks>
+    /// <returns>一个 <see cref="IEnumerator{T}"/> 枚举器，用于遍历集合中的每个元素列表 / An <see cref="IEnumerator{T}"/> enumerator for iterating through each element list in the collection.</returns>
     public IEnumerator<List<TElement>> GetEnumerator()
     {
         return _dictionary.Values.GetEnumerator();
@@ -105,7 +124,10 @@ public IEnumerator<List<TElement>> GetEnumerator()
     /// <summary>
     /// 返回一个非泛型枚举器，该枚举器可以遍历集合中的每个元素列表。
     /// </summary>
-    /// <returns>一个 <see cref="IEnumerator"/> 枚举器，用于遍历集合中的每个元素列表。</returns>
+    /// <remarks>
+    /// Returns a non-generic enumerator that can iterate through each element list in the collection.
+    /// </remarks>
+    /// <returns>一个 <see cref="IEnumerator"/> 枚举器，用于遍历集合中的每个元素列表 / An <see cref="IEnumerator"/> enumerator for iterating through each element list in the collection.</returns>
     IEnumerator IEnumerable.GetEnumerator()
     {
         return GetEnumerator();
@@ -114,9 +136,12 @@ IEnumerator IEnumerable.GetEnumerator()
     /// <summary>
     /// 判断集合中是否包含指定的键。
     /// </summary>
-    /// <param name="key">要检查的键。不能为 null。</param>
-    /// <returns>如果集合中包含指定的键，则返回 <c>true</c>；否则返回 <c>false</c>。</returns>
-    /// <exception cref="ArgumentNullException">当 <paramref name="key"/> 为 null 时抛出。</exception>
+    /// <remarks>
+    /// Determines whether the collection contains the specified key.
+    /// </remarks>
+    /// <param name="key">要检查的键，不能为 null / The key to check, cannot be null.</param>
+    /// <returns>如果集合中包含指定的键，则返回 <c>true</c>；否则返回 <c>false</c> / <c>true</c> if the collection contains the specified key; otherwise, <c>false</c>.</returns>
+    /// <exception cref="ArgumentNullException">当 <paramref name="key"/> 为 null 时抛出 / Thrown when <paramref name="key"/> is null.</exception>
     public bool Contains(TKey key)
     {
         ArgumentNullException.ThrowIfNull(key, nameof(key));

GameFrameX.Foundation.Extensions/LookupX.cs

@@ -39,13 +39,19 @@ namespace GameFrameX.Foundation.Extensions;
 /// <summary>
 /// 表示可为空的对象。
 /// </summary>
-/// <typeparam name="T">对象的类型。</typeparam>
+/// <remarks>
+/// Represents an object that can be null.
+/// </remarks>
+/// <typeparam name="T">对象的类型 / The type of the object.</typeparam>
 public readonly record struct NullObject<T> : IComparable, IComparable<T>, IEquatable<NullObject<T>>
 {
     /// <summary>
     /// 初始化一个新的 <see cref="NullObject{T}" /> 实例。
     /// </summary>
-    /// <param name="item">对象的值。</param>
+    /// <remarks>
+    /// Initializes a new instance of the <see cref="NullObject{T}" /> struct.
+    /// </remarks>
+    /// <param name="item">对象的值 / The value of the object.</param>
     public NullObject(T item)
     {
         Item = item;
@@ -54,6 +60,9 @@ public NullObject(T item)
     /// <summary>
     /// 获取一个表示空值的 <see cref="NullObject{T}" /> 实例。
     /// </summary>
+    /// <remarks>
+    /// Gets a <see cref="NullObject{T}" /> instance representing a null value.
+    /// </remarks>
     public static NullObject<T> Null
     {
         get { return new NullObject<T>(); }
@@ -62,14 +71,21 @@ public static NullObject<T> Null
     /// <summary>
     /// 获取对象的值。
     /// </summary>
+    /// <remarks>
+    /// Gets the value of the object.
+    /// </remarks>
+    /// <value>对象的值 / The value of the object.</value>
     public T Item { get; }
 
     /// <summary>
     /// 比较当前对象与另一个对象。
     /// </summary>
-    /// <param name="value">要比较的对象。</param>
-    /// <returns>一个整数，指示当前对象与 <paramref name="value" /> 的相对顺序。</returns>
-    /// <exception cref="ArgumentException">当 Item 为 null 且无法进行比较时抛出。</exception>
+    /// <remarks>
+    /// Compares the current object with another object.
+    /// </remarks>
+    /// <param name="value">要比较的对象 / The object to compare with.</param>
+    /// <returns>一个整数，指示当前对象与 <paramref name="value" /> 的相对顺序 / An integer indicating the relative order of the current object and <paramref name="value" />.</returns>
+    /// <exception cref="ArgumentException">当 Item 为 null 且无法进行比较时抛出 / Thrown when Item is null and cannot be compared.</exception>
     public int CompareTo(object value)
     {
         if (value is null)
@@ -113,9 +129,12 @@ public int CompareTo(object value)
     /// <summary>
     /// 比较当前对象与同一类型的另一个对象。
     /// </summary>
-    /// <param name="other">要比较的对象。</param>
-    /// <returns>一个整数，指示当前对象与 <paramref name="other" /> 的相对顺序。</returns>
-    /// <exception cref="ArgumentException">当 Item 为 null 且无法进行比较时抛出。</exception>
+    /// <remarks>
+    /// Compares the current object with another object of the same type.
+    /// </remarks>
+    /// <param name="other">要比较的对象 / The object to compare with.</param>
+    /// <returns>一个整数，指示当前对象与 <paramref name="other" /> 的相对顺序 / An integer indicating the relative order of the current object and <paramref name="other" />.</returns>
+    /// <exception cref="ArgumentException">当 Item 为 null 且无法进行比较时抛出 / Thrown when Item is null and cannot be compared.</exception>
     public int CompareTo(T other)
     {
         if (Item is null && other is null)
@@ -144,8 +163,11 @@ public int CompareTo(T other)
     /// <summary>
     /// 指示当前对象是否等于同一类型的另一个对象。
     /// </summary>
-    /// <param name="other">一个与此对象进行比较的对象。</param>
-    /// <returns>如果当前对象等于 <paramref name="other" /> 参数，则为 true；否则为 false。</returns>
+    /// <remarks>
+    /// Indicates whether the current object is equal to another object of the same type.
+    /// </remarks>
+    /// <param name="other">一个与此对象进行比较的对象 / An object to compare with this object.</param>
+    /// <returns>如果当前对象等于 <paramref name="other" /> 参数，则为 <c>true</c>；否则为 <c>false</c> / <c>true</c> if the current object equals the <paramref name="other" /> parameter; otherwise, <c>false</c>.</returns>
     public bool Equals(NullObject<T> other)
     {
         return EqualityComparer<T>.Default.Equals(Item, other.Item);
@@ -154,7 +176,10 @@ public bool Equals(NullObject<T> other)
     /// <summary>
     /// 将 <see cref="NullObject{T}" /> 隐式转换为类型 <typeparamref name="T" />。
     /// </summary>
-    /// <param name="nullObject">要转换的 <see cref="NullObject{T}" /> 实例。</param>
+    /// <remarks>
+    /// Implicitly converts a <see cref="NullObject{T}" /> to type <typeparamref name="T" />.
+    /// </remarks>
+    /// <param name="nullObject">要转换的 <see cref="NullObject{T}" /> 实例 / The <see cref="NullObject{T}" /> instance to convert.</param>
     public static implicit operator T(NullObject<T> nullObject)
     {
         return nullObject.Item;
@@ -163,7 +188,10 @@ public static implicit operator T(NullObject<T> nullObject)
     /// <summary>
     /// 将类型 <typeparamref name="T" /> 隐式转换为 <see cref="NullObject{T}" />。
     /// </summary>
-    /// <param name="item">要转换的值。</param>
+    /// <remarks>
+    /// Implicitly converts a value of type <typeparamref name="T" /> to <see cref="NullObject{T}" />.
+    /// </remarks>
+    /// <param name="item">要转换的值 / The value to convert.</param>
     public static implicit operator NullObject<T>(T item)
     {
         return new NullObject<T>(item);
@@ -172,7 +200,10 @@ public static implicit operator NullObject<T>(T item)
     /// <summary>
     /// 返回对象的字符串表示形式。
     /// </summary>
-    /// <returns>对象的字符串表示形式，如果对象为 null，则返回 "NULL"。</returns>
+    /// <remarks>
+    /// Returns the string representation of the object.
+    /// </remarks>
+    /// <returns>对象的字符串表示形式，如果对象为 null，则返回 "NULL" / The string representation of the object, or "NULL" if the object is null.</returns>
     public override string ToString()
     {
         return Item != null ? Item.ToString() : "NULL";
@@ -181,7 +212,10 @@ public override string ToString()
     /// <summary>
     /// 返回当前对象的哈希代码。
     /// </summary>
-    /// <returns>当前对象的哈希代码。</returns>
+    /// <remarks>
+    /// Returns the hash code of the current object.
+    /// </remarks>
+    /// <returns>当前对象的哈希代码 / The hash code of the current object.</returns>
     public override int GetHashCode()
     {
         return EqualityComparer<T>.Default.GetHashCode(Item);