Skip to content

Commit 81ff20c

Browse files
AlianBlankAlianBlank
committed
docs(options): 为 Options 项目添加双语文档注释
更新以下组件的双语文档注释： - CommandLineArgumentConverter：命令行参数转换器 - OptionsProvider：选项提供者 - OptionsBuilder：选项构建器（静态类 + 泛型类） - OptionsDebugger：选项调试器 - BoolArgumentFormat：布尔参数格式枚举 - OptionAttribute：选项特性 - FlagOptionAttribute：标志选项特性 - EnvironmentVariableAttribute：环境变量特性 - GrafanaLokiLabelTagAttribute：Grafana Loki 标签特性 遵循规范：summary 只写中文，remarks 写英文翻译，param/returns/typeparam 使用双语格式
1 parent 8722fed commit 81ff20c

9 files changed

Lines changed: 405 additions & 158 deletions

‎GameFrameX.Foundation.Options/Attributes/EnvironmentVariableAttribute.cs‎

Lines changed: 28 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -34,22 +34,45 @@
3434
namespace GameFrameX.Foundation.Options.Attributes;
3535

3636
/// <summary>
37-
/// 表示从环境变量中获取值的特性
37+
/// 表示从环境变量中获取值的特性。
3838
/// </summary>
39+
/// <remarks>
40+
/// Attribute indicating that a property's value should be retrieved from an environment variable.
41+
/// Apply this attribute to properties to bind them to specific environment variables.
42+
/// </remarks>
43+
/// <example>
44+
/// <code>
45+
/// public class MyOptions
46+
/// {
47+
/// [EnvironmentVariable("DATABASE_URL")]
48+
/// public string DatabaseUrl { get; set; }
49+
///
50+
/// [EnvironmentVariable("API_KEY")]
51+
/// public string ApiKey { get; set; }
52+
/// }
53+
/// </code>
54+
/// </example>
3955
[AttributeUsage(AttributeTargets.Property)]
4056
public class EnvironmentVariableAttribute : Attribute
4157
{
4258
/// <summary>
43-
/// 获取环境变量名称
59+
/// 获取环境变量名称。
4460
/// </summary>
61+
/// <remarks>
62+
/// Gets the environment variable name.
63+
/// </remarks>
64+
/// <value>环境变量名称 / Environment variable name</value>
4565
public string Name { get; }
4666

4767
/// <summary>
48-
/// 使用指定的环境变量名称初始化 <see cref="EnvironmentVariableAttribute"/> 类的新实例
68+
/// 使用指定的环境变量名称初始化 <see cref="EnvironmentVariableAttribute"/> 类的新实例。
4969
/// </summary>
50-
/// <param name="name">环境变量名称</param>
70+
/// <remarks>
71+
/// Initializes a new instance of the <see cref="EnvironmentVariableAttribute"/> class with the specified environment variable name.
72+
/// </remarks>
73+
/// <param name="name">环境变量名称 / Environment variable name</param>
5174
public EnvironmentVariableAttribute(string name)
5275
{
5376
Name = name;
5477
}
55-
}
78+
}

‎GameFrameX.Foundation.Options/Attributes/FlagOptionAttribute.cs‎

Lines changed: 29 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -34,25 +34,49 @@
3434
namespace GameFrameX.Foundation.Options.Attributes;
3535

3636
/// <summary>
37-
/// 表示一个布尔标志选项的特性，存在即为true，不存在即为false
37+
/// 表示一个布尔标志选项的特性，存在即为 <c>true</c>，不存在即为 <c>false</c>。
3838
/// </summary>
39+
/// <remarks>
40+
/// Attribute representing a boolean flag option. Presence means <c>true</c>, absence means <c>false</c>.
41+
/// This attribute inherits from <see cref="OptionAttribute"/> and automatically sets the default value to <c>false</c>.
42+
/// </remarks>
43+
/// <example>
44+
/// <code>
45+
/// public class MyOptions
46+
/// {
47+
/// [FlagOption("verbose")]
48+
/// public bool Verbose { get; set; }
49+
///
50+
/// [FlagOption("debug")]
51+
/// public bool Debug { get; set; }
52+
/// }
53+
/// </code>
54+
/// </example>
3955
[AttributeUsage(AttributeTargets.Property)]
4056
public class FlagOptionAttribute : OptionAttribute
4157
{
4258
/// <summary>
43-
/// 初始化 <see cref="FlagOptionAttribute"/> 类的新实例
59+
/// 初始化 <see cref="FlagOptionAttribute"/> 类的新实例。
4460
/// </summary>
61+
/// <remarks>
62+
/// Initializes a new instance of the <see cref="FlagOptionAttribute"/> class.
63+
/// The default value is automatically set to <c>false</c>.
64+
/// </remarks>
4565
public FlagOptionAttribute()
4666
{
4767
DefaultValue = false;
4868
}
4969

5070
/// <summary>
51-
/// 使用指定的长名称初始化 <see cref="FlagOptionAttribute"/> 类的新实例
71+
/// 使用指定的长名称初始化 <see cref="FlagOptionAttribute"/> 类的新实例。
5272
/// </summary>
53-
/// <param name="longName">选项的长名称</param>
73+
/// <remarks>
74+
/// Initializes a new instance of the <see cref="FlagOptionAttribute"/> class with the specified long name.
75+
/// The default value is automatically set to <c>false</c>.
76+
/// </remarks>
77+
/// <param name="longName">选项的长名称 / Long name of the option</param>
5478
public FlagOptionAttribute(string longName) : base(longName)
5579
{
5680
DefaultValue = false;
5781
}
58-
}
82+
}

‎GameFrameX.Foundation.Options/Attributes/GrafanaLokiLabelTagAttribute.cs‎

Lines changed: 18 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -34,9 +34,25 @@
3434
namespace GameFrameX.Foundation.Options.Attributes;
3535

3636
/// <summary>
37-
/// Grafana Loki 标签,用于将属性标记为 Grafana Loki 标签
37+
/// Grafana Loki 标签特性，用于将属性标记为 Grafana Loki 标签。
3838
/// </summary>
39+
/// <remarks>
40+
/// Grafana Loki label attribute for marking properties as Grafana Loki labels.
41+
/// Properties marked with this attribute will be treated as labels when logging to Grafana Loki.
42+
/// </remarks>
43+
/// <example>
44+
/// <code>
45+
/// public class LogOptions
46+
/// {
47+
/// [GrafanaLokiLabelTag]
48+
/// public string ServiceName { get; set; }
49+
///
50+
/// [GrafanaLokiLabelTag]
51+
/// public string Environment { get; set; }
52+
/// }
53+
/// </code>
54+
/// </example>
3955
[AttributeUsage(AttributeTargets.Property)]
4056
public sealed class GrafanaLokiLabelTagAttribute : Attribute
4157
{
42-
}
58+
}

‎GameFrameX.Foundation.Options/Attributes/OptionAttribute.cs‎

Lines changed: 52 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -34,50 +34,92 @@
3434
namespace GameFrameX.Foundation.Options.Attributes;
3535

3636
/// <summary>
37-
/// 表示一个命令行选项的特性
37+
/// 表示一个命令行选项的特性。
3838
/// </summary>
39+
/// <remarks>
40+
/// Attribute representing a command-line option.
41+
/// Apply this attribute to properties to mark them as command-line options.
42+
/// </remarks>
43+
/// <example>
44+
/// <code>
45+
/// public class MyOptions
46+
/// {
47+
/// [Option("server", Required = true, Description = "Server address")]
48+
/// public string Server { get; set; }
49+
///
50+
/// [Option("port", DefaultValue = 8080)]
51+
/// public int Port { get; set; }
52+
/// }
53+
/// </code>
54+
/// </example>
3955
[AttributeUsage(AttributeTargets.Property)]
4056
[System.Diagnostics.DebuggerDisplay("LongName = {LongName}, Required = {Required}, DefaultValue = {DefaultValue}")]
4157
public class OptionAttribute : Attribute
4258
{
4359
/// <summary>
44-
/// 获取或设置选项的长名称
60+
/// 获取或设置选项的长名称。
4561
/// </summary>
62+
/// <remarks>
63+
/// Gets or sets the long name of the option.
64+
/// </remarks>
65+
/// <value>选项的长名称（如 "verbose"） / Long name of the option (e.g., "verbose")</value>
4666
public string LongName { get; set; }
4767

4868
/// <summary>
49-
/// 获取或设置选项的默认值
69+
/// 获取或设置选项的默认值。
5070
/// </summary>
71+
/// <remarks>
72+
/// Gets or sets the default value of the option.
73+
/// </remarks>
74+
/// <value>选项的默认值 / Default value of the option</value>
5175
public object DefaultValue { get; set; }
5276

5377
/// <summary>
54-
/// 获取或设置选项的描述
78+
/// 获取或设置选项的描述。
5579
/// </summary>
80+
/// <remarks>
81+
/// Gets or sets the description of the option.
82+
/// </remarks>
83+
/// <value>选项的描述信息 / Description of the option</value>
5684
public string Description { get; set; }
5785

5886
/// <summary>
59-
/// 获取或设置选项是否必需
87+
/// 获取或设置选项是否必需。
6088
/// </summary>
89+
/// <remarks>
90+
/// Gets or sets whether the option is required.
91+
/// </remarks>
92+
/// <value>如果为 <c>true</c> 则选项必需；否则为可选 / <c>true</c> if the option is required; otherwise optional</value>
6193
public bool Required { get; set; }
6294

6395
/// <summary>
64-
/// 获取或设置环境变量名称
96+
/// 获取或设置环境变量名称。
6597
/// </summary>
98+
/// <remarks>
99+
/// Gets or sets the environment variable name for this option.
100+
/// </remarks>
101+
/// <value>关联的环境变量名称 / Associated environment variable name</value>
66102
public string EnvironmentVariable { get; set; }
67103

68104
/// <summary>
69-
/// 初始化 <see cref="OptionAttribute"/> 类的新实例
105+
/// 初始化 <see cref="OptionAttribute"/> 类的新实例。
70106
/// </summary>
107+
/// <remarks>
108+
/// Initializes a new instance of the <see cref="OptionAttribute"/> class.
109+
/// </remarks>
71110
public OptionAttribute()
72111
{
73112
}
74113

75114
/// <summary>
76-
/// 使用指定的长名称初始化 <see cref="OptionAttribute"/> 类的新实例
115+
/// 使用指定的长名称初始化 <see cref="OptionAttribute"/> 类的新实例。
77116
/// </summary>
78-
/// <param name="longName">选项的长名称</param>
117+
/// <remarks>
118+
/// Initializes a new instance of the <see cref="OptionAttribute"/> class with the specified long name.
119+
/// </remarks>
120+
/// <param name="longName">选项的长名称 / Long name of the option</param>
79121
public OptionAttribute(string longName)
80122
{
81123
LongName = longName;
82124
}
83-
}
125+
}

‎GameFrameX.Foundation.Options/BoolArgumentFormat.cs‎

Lines changed: 18 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,4 @@
1-
// ==========================================================================================
1+
// ==========================================================================================
22
// GameFrameX 组织及其衍生项目的版权、商标、专利及其他相关权利
33
// GameFrameX organization and its derivative projects' copyrights, trademarks, patents, and related rights
44
// 均受中华人民共和国及相关国际法律法规保护。
@@ -34,22 +34,34 @@
3434
namespace GameFrameX.Foundation.Options;
3535

3636
/// <summary>
37-
/// Bool类型参数的格式选项
37+
/// 布尔类型参数的格式选项。
3838
/// </summary>
39+
/// <remarks>
40+
/// Format options for boolean type arguments.
41+
/// </remarks>
3942
public enum BoolArgumentFormat
4043
{
4144
/// <summary>
42-
/// 标志格式：存在即为true，不存在即为false（如：--verbose）
45+
/// 标志格式：存在即为 <c>true</c>，不存在即为 <c>false</c>（如：--verbose）。
4346
/// </summary>
47+
/// <remarks>
48+
/// Flag format: presence means <c>true</c>, absence means <c>false</c> (e.g., --verbose).
49+
/// </remarks>
4450
Flag,
4551

4652
/// <summary>
47-
/// 键值对格式：明确指定true/false值（如：--verbose=true）
53+
/// 键值对格式：明确指定 <c>true</c>/<c>false</c> 值（如：--verbose=true）。
4854
/// </summary>
55+
/// <remarks>
56+
/// Key-value format: explicitly specifies <c>true</c>/<c>false</c> value (e.g., --verbose=true).
57+
/// </remarks>
4958
KeyValue,
5059

5160
/// <summary>
52-
/// 分离格式：键和值分开（如：--verbose true）
61+
/// 分离格式：键和值分开（如：--verbose true）。
5362
/// </summary>
63+
/// <remarks>
64+
/// Separated format: key and value are separated (e.g., --verbose true).
65+
/// </remarks>
5466
Separated
55-
}
67+
}

‎GameFrameX.Foundation.Options/CommandLineArgumentConverter.cs‎

Lines changed: 30 additions & 13 deletions
Original file line numberDiff line numberDiff line change
@@ -34,26 +34,40 @@
3434
namespace GameFrameX.Foundation.Options;
3535

3636
/// <summary>
37-
/// 命令行参数转换器
37+
/// 命令行参数转换器。
3838
/// </summary>
39+
/// <remarks>
40+
/// Command-line argument converter for transforming and standardizing command-line arguments.
41+
/// </remarks>
3942
public sealed class CommandLineArgumentConverter
4043
{
4144
/// <summary>
42-
/// 布尔参数格式
45+
/// 获取或设置布尔参数格式。
4346
/// </summary>
47+
/// <remarks>
48+
/// Gets or sets the boolean argument format.
49+
/// </remarks>
50+
/// <value>布尔参数格式 / Boolean argument format</value>
4451
public BoolArgumentFormat BoolFormat { get; set; } = BoolArgumentFormat.Flag;
4552

4653
/// <summary>
47-
/// 是否确保键有前缀
54+
/// 获取或设置是否确保键有前缀。
4855
/// </summary>
56+
/// <remarks>
57+
/// Gets or sets whether to ensure all keys have prefixes.
58+
/// </remarks>
59+
/// <value>指示是否确保键有前缀，默认为 <c>true</c> / Indicates whether to ensure keys have prefixes, default is <c>true</c></value>
4960
public bool EnsurePrefixedKeys { get; set; } = true;
5061

5162
/// <summary>
52-
/// 将参数列表转换为命令行字符串
63+
/// 将参数列表转换为命令行字符串。
5364
/// </summary>
54-
/// <param name="args">参数列表</param>
55-
/// <returns>格式化的命令行字符串</returns>
56-
/// <exception cref="ArgumentNullException">如果参数列表为 null</exception>
65+
/// <remarks>
66+
/// Converts a list of arguments to a command-line string.
67+
/// </remarks>
68+
/// <param name="args">参数列表 / List of arguments</param>
69+
/// <returns>格式化的命令行字符串 / Formatted command-line string</returns>
70+
/// <exception cref="ArgumentNullException">当 <paramref name="args"/> 为 <c>null</c> 时抛出 / Thrown when <paramref name="args"/> is <c>null</c></exception>
5771
public string ToCommandLineString(List<string> args)
5872
{
5973
if (args == null)
@@ -113,10 +127,13 @@ public string ToCommandLineString(List<string> args)
113127
}
114128

115129
/// <summary>
116-
/// 将命令行参数转换为标准格式
130+
/// 将命令行参数转换为标准格式。
117131
/// </summary>
118-
/// <param name="args">命令行参数</param>
119-
/// <returns>标准格式的参数列表</returns>
132+
/// <remarks>
133+
/// Converts command-line arguments to standard format.
134+
/// </remarks>
135+
/// <param name="args">命令行参数 / Command-line arguments</param>
136+
/// <returns>标准格式的参数列表 / Standardized argument list</returns>
120137
public List<string> ConvertToStandardFormat(string[] args)
121138
{
122139
try
@@ -132,7 +149,7 @@ public List<string> ConvertToStandardFormat(string[] args)
132149
for (int i = 0; i < args.Length; i++)
133150
{
134151
var arg = args[i];
135-
152+
136153
// 如果参数为null，跳过
137154
if (arg == null)
138155
{
@@ -192,15 +209,15 @@ public List<string> ConvertToStandardFormat(string[] args)
192209
if (i < args.Length - 1)
193210
{
194211
var nextArg = args[i + 1];
195-
212+
196213
// 如果下一个参数是null，则当前参数被视为布尔标志（没有值）
197214
if (nextArg == null)
198215
{
199216
i++; // 跳过null参数
200217
// 不添加值，当前参数将被视为布尔标志
201218
continue;
202219
}
203-
220+
204221
// 如果下一个参数不是选项（不以-开头），则作为当前参数的值
205222
if (!nextArg.StartsWith("-"))
206223
{

0 commit comments

Comments
 (0)