Skip to content

Commit 9a99188

Browse files
committed
docs: 为集合扩展方法添加英文文档注释
为 CollectionExtensions 类及其所有方法添加英文文档注释,提高代码的可读性和国际化支持。
1 parent 9e2f8e7 commit 9a99188

1 file changed

Lines changed: 83 additions & 62 deletions

File tree

GameFrameX.Foundation.Extensions/CollectionExtensions.cs

Lines changed: 83 additions & 62 deletions
Original file line numberDiff line numberDiff line change
@@ -37,18 +37,24 @@
3737
namespace GameFrameX.Foundation.Extensions;
3838

3939
/// <summary>
40-
/// 提供集合类型的扩展方法
40+
/// 提供集合类型的扩展方法
4141
/// </summary>
42+
/// <remarks>
43+
/// Provides extension methods for collection types.
44+
/// </remarks>
4245
public static class CollectionExtensions
4346
{
4447
#region ICollectionExtensions
4548

4649
/// <summary>
4750
/// 检查集合是否为 null 或空。
4851
/// </summary>
49-
/// <typeparam name="T">集合元素的类型。</typeparam>
50-
/// <param name="self">要检查的集合。</param>
51-
/// <returns>如果集合为 null 或空,则为 true;否则为 false。</returns>
52+
/// <remarks>
53+
/// Checks whether the collection is null or empty.
54+
/// </remarks>
55+
/// <typeparam name="T">集合元素的类型 / The type of elements in the collection.</typeparam>
56+
/// <param name="self">要检查的集合 / The collection to check.</param>
57+
/// <returns>如果集合为 null 或空,则为 true;否则为 false / true if the collection is null or empty; otherwise, false.</returns>
5258
public static bool IsNullOrEmpty<T>(this ICollection<T> self)
5359
{
5460
return self is not { Count: > 0 };
@@ -59,11 +65,14 @@ public static bool IsNullOrEmpty<T>(this ICollection<T> self)
5965
/// <summary>
6066
/// 将一个可枚举集合的元素添加到哈希集合中。
6167
/// </summary>
62-
/// <typeparam name="T">哈希集合元素的类型。</typeparam>
63-
/// <param name="hashSet">要添加元素的哈希集合,不能为 null。</param>
64-
/// <param name="enumerable">要添加的元素的可枚举集合,不能为 null。</param>
65-
/// <exception cref="ArgumentNullException">当 <paramref name="hashSet"/> 或 <paramref name="enumerable"/> 为 null 时抛出</exception>
66-
/// <remarks>此方法会将指定集合中的所有元素添加到目标哈希集合中。如果元素已存在,则会被忽略。</remarks>
68+
/// <remarks>
69+
/// Adds the elements of the specified collection to the <see cref="HashSet{T}"/>.
70+
/// If an element already exists in the set, it will be ignored.
71+
/// </remarks>
72+
/// <typeparam name="T">哈希集合元素的类型 / The type of elements in the hash set.</typeparam>
73+
/// <param name="hashSet">要添加元素的哈希集合,不能为 null / The hash set to add elements to, cannot be null.</param>
74+
/// <param name="enumerable">要添加的元素的可枚举集合,不能为 null / The collection whose elements should be added, cannot be null.</param>
75+
/// <exception cref="ArgumentNullException">当 <paramref name="hashSet"/> 或 <paramref name="enumerable"/> 为 null 时抛出 / Thrown when <paramref name="hashSet"/> or <paramref name="enumerable"/> is null.</exception>
6776
public static void AddRangeValues<T>(this HashSet<T> hashSet, IEnumerable<T> enumerable)
6877
{
6978
ArgumentNullException.ThrowIfNull(hashSet, nameof(hashSet));
@@ -80,17 +89,16 @@ public static void AddRangeValues<T>(this HashSet<T> hashSet, IEnumerable<T> enu
8089
/// <summary>
8190
/// 合并字典中的键值对。如果字典中已存在指定的键,则使用指定的函数对原有值和新值进行合并;否则直接添加键值对。
8291
/// </summary>
83-
/// <typeparam name="TKey">键的类型。</typeparam>
84-
/// <typeparam name="TValue">值的类型。</typeparam>
85-
/// <param name="self">要合并的字典,不能为 null。</param>
86-
/// <param name="key">要添加或合并的键,不能为 null(如果 TKey 是引用类型)。</param>
87-
/// <param name="v">要添加或合并的值。</param>
88-
/// <param name="func">用于合并值的函数,接收两个参数:现有值和新值,返回合并后的结果,不能为 null。</param>
89-
/// <exception cref="ArgumentNullException">当 <paramref name="self"/>、<paramref name="key"/>(如果是引用类型)、<paramref name="v"/>(如果是引用类型)或 <paramref name="func"/> 为 null 时抛出</exception>
9092
/// <remarks>
91-
/// 当键已存在时,将调用提供的合并函数来组合现有值和新值。
92-
/// 当键不存在时,直接将新值添加到字典中。
93+
/// Merges a key/value pair into the dictionary. If the key already exists, the existing value and new value are combined using the specified function; otherwise, the key/value pair is added directly.
9394
/// </remarks>
95+
/// <typeparam name="TKey">键的类型 / The type of the keys in the dictionary.</typeparam>
96+
/// <typeparam name="TValue">值的类型 / The type of the values in the dictionary.</typeparam>
97+
/// <param name="self">要合并的字典,不能为 null / The dictionary to merge into, cannot be null.</param>
98+
/// <param name="key">要添加或合并的键 / The key to add or merge.</param>
99+
/// <param name="v">要添加或合并的值 / The value to add or merge.</param>
100+
/// <param name="func">用于合并值的函数,接收两个参数:现有值和新值,返回合并后的结果,不能为 null / The function to use to merge values if the key exists, cannot be null.</param>
101+
/// <exception cref="ArgumentNullException">当 <paramref name="self"/>、<paramref name="key"/>(如果是引用类型)、<paramref name="v"/>(如果是引用类型)或 <paramref name="func"/> 为 null 时抛出 / Thrown when <paramref name="self"/>, <paramref name="key"/> (if reference type), <paramref name="v"/> (if reference type), or <paramref name="func"/> is null.</exception>
94102
public static void Merge<TKey, TValue>(this Dictionary<TKey, TValue> self, TKey key, TValue v, Func<TValue, TValue, TValue> func)
95103
{
96104
ArgumentNullException.ThrowIfNull(self, nameof(self));
@@ -108,13 +116,16 @@ public static void Merge<TKey, TValue>(this Dictionary<TKey, TValue> self, TKey
108116
/// <summary>
109117
/// 获取指定键的值,如果字典中不存在该键,则使用指定的函数获取值并添加到字典中。
110118
/// </summary>
111-
/// <typeparam name="TKey">键的类型。</typeparam>
112-
/// <typeparam name="TValue">值的类型。</typeparam>
113-
/// <param name="self">要操作的字典,不能为 null。</param>
114-
/// <param name="key">要获取值的键,不能为 null(如果 TKey 是引用类型)。</param>
115-
/// <param name="valueGetter">用于获取值的函数,接收键作为参数并返回对应的值,不能为 null。</param>
116-
/// <returns>指定键的值。如果键不存在,则返回新创建的值。</returns>
117-
/// <exception cref="ArgumentNullException">当 <paramref name="self"/>、<paramref name="key"/>(如果是引用类型)或 <paramref name="valueGetter"/> 为 null 时抛出</exception>
119+
/// <remarks>
120+
/// Gets the value associated with the specified key. If the key does not exist, the value is created using the specified function and added to the dictionary.
121+
/// </remarks>
122+
/// <typeparam name="TKey">键的类型 / The type of the keys in the dictionary.</typeparam>
123+
/// <typeparam name="TValue">值的类型 / The type of the values in the dictionary.</typeparam>
124+
/// <param name="self">要操作的字典,不能为 null / The dictionary to operate on, cannot be null.</param>
125+
/// <param name="key">要获取值的键 / The key whose value to get.</param>
126+
/// <param name="valueGetter">用于获取值的函数,接收键作为参数并返回对应的值,不能为 null / The function to use to generate a value if the key is not found, cannot be null.</param>
127+
/// <returns>指定键的值。如果键不存在,则返回新创建的值 / The value associated with the specified key. If the key does not exist, returns the newly created value.</returns>
128+
/// <exception cref="ArgumentNullException">当 <paramref name="self"/>、<paramref name="key"/>(如果是引用类型)或 <paramref name="valueGetter"/> 为 null 时抛出 / Thrown when <paramref name="self"/>, <paramref name="key"/> (if reference type), or <paramref name="valueGetter"/> is null.</exception>
118129
public static TValue GetOrAddValue<TKey, TValue>(this Dictionary<TKey, TValue> self, TKey key, Func<TKey, TValue> valueGetter)
119130
{
120131
ArgumentNullException.ThrowIfNull(self, nameof(self));
@@ -133,12 +144,15 @@ public static TValue GetOrAddValue<TKey, TValue>(this Dictionary<TKey, TValue> s
133144
/// <summary>
134145
/// 获取指定键的值,如果字典中不存在该键,则使用无参构造函数创建一个新的值并添加到字典中。
135146
/// </summary>
136-
/// <typeparam name="TKey">键的类型。</typeparam>
137-
/// <typeparam name="TValue">值的类型,必须包含无参构造函数。</typeparam>
138-
/// <param name="self">要操作的字典,不能为 null。</param>
139-
/// <param name="key">要获取值的键,不能为 null(如果 TKey 是引用类型)。</param>
140-
/// <returns>指定键的值。如果键不存在,则返回新创建的值。</returns>
141-
/// <exception cref="ArgumentNullException">当 <paramref name="self"/> 或 <paramref name="key"/> 为 null 时抛出</exception>
147+
/// <remarks>
148+
/// Gets the value associated with the specified key. If the key does not exist, a new value is created using the parameterless constructor and added to the dictionary.
149+
/// </remarks>
150+
/// <typeparam name="TKey">键的类型 / The type of the keys in the dictionary.</typeparam>
151+
/// <typeparam name="TValue">值的类型,必须包含无参构造函数 / The type of the values in the dictionary, must have a parameterless constructor.</typeparam>
152+
/// <param name="self">要操作的字典,不能为 null / The dictionary to operate on, cannot be null.</param>
153+
/// <param name="key">要获取值的键 / The key whose value to get.</param>
154+
/// <returns>指定键的值。如果键不存在,则返回新创建的值 / The value associated with the specified key. If the key does not exist, returns the newly created value.</returns>
155+
/// <exception cref="ArgumentNullException">当 <paramref name="self"/> 或 <paramref name="key"/> 为 null 时抛出 / Thrown when <paramref name="self"/> or <paramref name="key"/> is null.</exception>
142156
public static TValue GetOrAddValue<TKey, TValue>(this Dictionary<TKey, TValue> self, TKey key) where TValue : new()
143157
{
144158
return GetOrAddValue(self, key, _ => new TValue());
@@ -147,17 +161,17 @@ public static TValue GetOrAddValue<TKey, TValue>(this Dictionary<TKey, TValue> s
147161
/// <summary>
148162
/// 根据指定条件从字典中移除键值对。
149163
/// </summary>
150-
/// <typeparam name="TKey">键的类型。</typeparam>
151-
/// <typeparam name="TValue">值的类型。</typeparam>
152-
/// <param name="self">要操作的字典,不能为 null。</param>
153-
/// <param name="predict">判断是否移除键值对的条件,接收键和值作为参数,返回true表示需要移除,不能为 null。</param>
154-
/// <returns>移除的键值对数量。</returns>
155-
/// <exception cref="ArgumentNullException">当 <paramref name="self"/> 或 <paramref name="predict"/> 为 null 时抛出</exception>
156164
/// <remarks>
157-
/// 此方法会遍历字典中的所有键值对,对每一对调用predict函数进行判断。
158-
/// 如果predict返回true,则移除该键值对。
159-
/// 为避免在遍历时修改集合导致的异常,此方法会先收集要移除的键,然后统一移除。
165+
/// Removes all key/value pairs from the dictionary that match the specified condition.
166+
/// This method iterates through all key/value pairs and removes those where the predicate returns true.
167+
/// To avoid modifying the collection during iteration, keys to remove are collected first, then removed.
160168
/// </remarks>
169+
/// <typeparam name="TKey">键的类型 / The type of the keys in the dictionary.</typeparam>
170+
/// <typeparam name="TValue">值的类型 / The type of the values in the dictionary.</typeparam>
171+
/// <param name="self">要操作的字典,不能为 null / The dictionary to operate on, cannot be null.</param>
172+
/// <param name="predict">判断是否移除键值对的条件,接收键和值作为参数,返回true表示需要移除,不能为 null / The predicate function to determine which items to remove, cannot be null.</param>
173+
/// <returns>移除的键值对数量 / The number of items removed.</returns>
174+
/// <exception cref="ArgumentNullException">当 <paramref name="self"/> 或 <paramref name="predict"/> 为 null 时抛出 / Thrown when <paramref name="self"/> or <paramref name="predict"/> is null.</exception>
161175
public static int RemoveIf<TKey, TValue>(this Dictionary<TKey, TValue> self, Func<TKey, TValue, bool> predict)
162176
{
163177
ArgumentNullException.ThrowIfNull(self, nameof(self));
@@ -187,12 +201,15 @@ public static int RemoveIf<TKey, TValue>(this Dictionary<TKey, TValue> self, Fun
187201
/// <summary>
188202
/// 从列表中随机获取一个元素。
189203
/// </summary>
190-
/// <typeparam name="T">列表元素的类型。</typeparam>
191-
/// <param name="list">要随机的列表,不能为 null 且不能为空。</param>
192-
/// <returns>随机选择的列表元素。</returns>
193-
/// <exception cref="ArgumentNullException">当 <paramref name="list"/> 为 null 时抛出</exception>
194-
/// <exception cref="ArgumentException">当 <paramref name="list"/> 为空时抛出</exception>
195-
/// <remarks>使用System.Random.Shared来生成随机数,确保线程安全。</remarks>
204+
/// <remarks>
205+
/// Returns a random element from the list.
206+
/// Uses <see cref="System.Random.Shared"/> to generate random numbers, ensuring thread safety.
207+
/// </remarks>
208+
/// <typeparam name="T">列表元素的类型 / The type of elements in the list.</typeparam>
209+
/// <param name="list">要随机的列表,不能为 null 且不能为空 / The list to get a random element from, cannot be null or empty.</param>
210+
/// <returns>随机选择的列表元素 / A random element from the list.</returns>
211+
/// <exception cref="ArgumentNullException">当 <paramref name="list"/> 为 null 时抛出 / Thrown when <paramref name="list"/> is null.</exception>
212+
/// <exception cref="ArgumentException">当 <paramref name="list"/> 为空时抛出 / Thrown when <paramref name="list"/> is empty.</exception>
196213
public static T RandomElement<T>(this List<T> list)
197214
{
198215
ArgumentNullException.ThrowIfNull(list, nameof(list));
@@ -209,12 +226,15 @@ public static T RandomElement<T>(this List<T> list)
209226
/// <summary>
210227
/// 从列表中随机选择一个元素。
211228
/// </summary>
212-
/// <typeparam name="T">列表元素的类型。</typeparam>
213-
/// <param name="list">要从中选择元素的列表,不能为 null 且不能为空。</param>
214-
/// <param name="random">用于生成随机数的 Random 实例,不能为 null。</param>
215-
/// <returns>从列表中随机选择的元素。</returns>
216-
/// <exception cref="ArgumentNullException">当 <paramref name="list"/> 或 <paramref name="random"/> 为 null 时抛出</exception>
217-
/// <exception cref="ArgumentException">当 <paramref name="list"/> 为空时抛出</exception>
229+
/// <remarks>
230+
/// Returns a random element from the list using the specified random number generator.
231+
/// </remarks>
232+
/// <typeparam name="T">列表元素的类型 / The type of elements in the list.</typeparam>
233+
/// <param name="list">要从中选择元素的列表,不能为 null 且不能为空 / The list to get a random element from, cannot be null or empty.</param>
234+
/// <param name="random">用于生成随机数的 Random 实例,不能为 null / The random number generator to use, cannot be null.</param>
235+
/// <returns>从列表中随机选择的元素 / A random element from the list.</returns>
236+
/// <exception cref="ArgumentNullException">当 <paramref name="list"/> 或 <paramref name="random"/> 为 null 时抛出 / Thrown when <paramref name="list"/> or <paramref name="random"/> is null.</exception>
237+
/// <exception cref="ArgumentException">当 <paramref name="list"/> 为空时抛出 / Thrown when <paramref name="list"/> is empty.</exception>
218238
public static T RandomElement<T>(this List<T> list, Random random)
219239
{
220240
ArgumentNullException.ThrowIfNull(list, nameof(list));
@@ -231,13 +251,13 @@ public static T RandomElement<T>(this List<T> list, Random random)
231251
/// <summary>
232252
/// 打乱列表中的元素顺序(洗牌)。
233253
/// </summary>
234-
/// <typeparam name="T">列表元素的类型。</typeparam>
235-
/// <param name="list">要打乱顺序的列表,不能为 null。</param>
236-
/// <exception cref="ArgumentNullException">当 <paramref name="list"/> 为 null 时抛出</exception>
237254
/// <remarks>
238-
/// 使用Fisher-Yates洗牌算法实现列表随机排序。
239-
/// 该方法会直接修改原列表的顺序。
255+
/// Shuffles the elements in the list using the Fisher-Yates algorithm.
256+
/// This method modifies the original list directly.
240257
/// </remarks>
258+
/// <typeparam name="T">列表元素的类型 / The type of elements in the list.</typeparam>
259+
/// <param name="list">要打乱顺序的列表,不能为 null / The list to shuffle, cannot be null.</param>
260+
/// <exception cref="ArgumentNullException">当 <paramref name="list"/> 为 null 时抛出 / Thrown when <paramref name="list"/> is null.</exception>
241261
public static void Shuffle<T>(this List<T> list)
242262
{
243263
ArgumentNullException.ThrowIfNull(list, nameof(list));
@@ -253,13 +273,14 @@ public static void Shuffle<T>(this List<T> list)
253273
/// <summary>
254274
/// 从列表中移除满足条件的所有元素。
255275
/// </summary>
256-
/// <typeparam name="T">列表元素的类型。</typeparam>
257-
/// <param name="list">要操作的列表,不能为 null。</param>
258-
/// <param name="condition">用于判断元素是否满足移除条件的委托,返回true表示需要移除,不能为 null。</param>
259-
/// <exception cref="ArgumentNullException">当 <paramref name="list"/> 或 <paramref name="condition"/> 为 null 时抛出</exception>
260276
/// <remarks>
261-
/// 此方法使用 List{T}.RemoveAll 方法一次性移除所有满足条件的元素。
277+
/// Removes all elements from the list that match the specified condition.
278+
/// This method uses <see cref="List{T}.RemoveAll(Predicate{T})"/> to remove all matching elements at once.
262279
/// </remarks>
280+
/// <typeparam name="T">列表元素的类型 / The type of elements in the list.</typeparam>
281+
/// <param name="list">要操作的列表,不能为 null / The list to operate on, cannot be null.</param>
282+
/// <param name="condition">用于判断元素是否满足移除条件的委托,返回true表示需要移除,不能为 null / The predicate function to determine which items to remove, cannot be null.</param>
283+
/// <exception cref="ArgumentNullException">当 <paramref name="list"/> 或 <paramref name="condition"/> 为 null 时抛出 / Thrown when <paramref name="list"/> or <paramref name="condition"/> is null.</exception>
263284
public static void RemoveIf<T>(this List<T> list, Predicate<T> condition)
264285
{
265286
ArgumentNullException.ThrowIfNull(list, nameof(list));

0 commit comments

Comments
 (0)