Skip to content

Commit 8722fed

Browse files
committed
docs(orm-attribute): 为所有特性类添加双语文档注释
为 GameFrameX.Foundation.Orm.Attribute 项目中的 13 个特性类及其关联枚举添加标准的双语文档注释(中文 + 英文): - AuditTableAttribute 及 AuditLevel 枚举 - IncrementTableAttribute - IncrementSeedAttribute - LogTableAttribute - CacheTableAttribute - SystemTableAttribute - VersionControlAttribute 及 VersionStrategy、ConflictResolution、VersionComparison 枚举 - ConstAttribute - EntityIndexAttribute - SoftDeleteAttribute - PartitionTableAttribute 及 PartitionType、PartitionInterval 枚举 - ReadOnlyTableAttribute 及 ReadOnlyErrorHandling 枚举 - CustomUnifyResultAttribute 遵循规范:summary 只写中文,remarks 写英文翻译,param/returns/value 使用双语格式
1 parent 843d905 commit 8722fed

13 files changed

Lines changed: 726 additions & 418 deletions

GameFrameX.Foundation.Orm.Attribute/AuditTableAttribute.cs

Lines changed: 70 additions & 31 deletions
Original file line numberDiff line numberDiff line change
@@ -34,19 +34,22 @@
3434
namespace GameFrameX.Foundation.Orm.Attribute;
3535

3636
/// <summary>
37-
/// 审计表特性,用于标记实体类对应的数据库表需要进行审计跟踪
37+
/// 审计表特性,用于标记实体类对应的数据库表需要进行审计跟踪
3838
/// </summary>
3939
/// <remarks>
40-
/// 此特性应用于实体类,用于标识该实体对应的数据库表需要进行审计跟踪。
41-
/// 在ORM框架中,当实体类标记了此特性时,框架会自动记录数据的变更历史,
42-
/// 包括创建、更新、删除等操作的详细信息,用于合规性要求和安全审计。
43-
///
44-
/// 审计表通常记录以下信息:
45-
/// - 操作类型(INSERT、UPDATE、DELETE)
46-
/// - 操作时间和操作用户
47-
/// - 变更前后的数据值
48-
/// - 操作来源(IP地址、应用程序等)
49-
/// - 业务上下文信息
40+
/// Audit table attribute for marking entity classes that require audit tracking for their corresponding database tables.
41+
/// When an entity class is marked with this attribute, the ORM framework automatically records data change history,
42+
/// including detailed information about create, update, and delete operations for compliance and security auditing.
43+
/// <para>
44+
/// Audit tables typically record the following information:
45+
/// </para>
46+
/// <list type="bullet">
47+
/// <item><description>Operation type (INSERT, UPDATE, DELETE)</description></item>
48+
/// <item><description>Operation timestamp and user</description></item>
49+
/// <item><description>Before and after data values</description></item>
50+
/// <item><description>Operation source (IP address, application, etc.)</description></item>
51+
/// <item><description>Business context information</description></item>
52+
/// </list>
5053
/// </remarks>
5154
/// <example>
5255
/// <code>
@@ -58,7 +61,7 @@ namespace GameFrameX.Foundation.Orm.Attribute;
5861
/// public decimal Balance { get; set; }
5962
/// public DateTime LastLoginTime { get; set; }
6063
/// }
61-
///
64+
///
6265
/// [AuditTable(AuditLevel = AuditLevel.ChangesOnly)]
6366
/// public class SystemSettings
6467
/// {
@@ -72,74 +75,110 @@ namespace GameFrameX.Foundation.Orm.Attribute;
7275
public sealed class AuditTableAttribute : System.Attribute
7376
{
7477
/// <summary>
75-
/// 获取或设置审计级别
78+
/// 获取或设置审计级别
7679
/// </summary>
77-
/// <value>审计级别,控制审计的详细程度</value>
80+
/// <remarks>
81+
/// Gets or sets the audit level, which controls the level of detail for auditing.
82+
/// </remarks>
83+
/// <value>审计级别,控制审计的详细程度 / Audit level, controls the level of detail for auditing</value>
7884
public AuditLevel AuditLevel { get; set; } = AuditLevel.ChangesOnly;
7985

8086
/// <summary>
81-
/// 获取或设置是否包含用户信息
87+
/// 获取或设置是否包含用户信息
8288
/// </summary>
83-
/// <value>指示是否在审计记录中包含操作用户信息,默认为 true</value>
89+
/// <remarks>
90+
/// Gets or sets whether to include user information in audit records.
91+
/// </remarks>
92+
/// <value>指示是否在审计记录中包含操作用户信息,默认为 <c>true</c> / Indicates whether to include operating user information in audit records, default is <c>true</c></value>
8493
public bool IncludeUserInfo { get; set; } = true;
8594

8695
/// <summary>
87-
/// 获取或设置是否包含IP地址
96+
/// 获取或设置是否包含IP地址
8897
/// </summary>
89-
/// <value>指示是否在审计记录中包含客户端IP地址,默认为 false</value>
98+
/// <remarks>
99+
/// Gets or sets whether to include IP address in audit records.
100+
/// </remarks>
101+
/// <value>指示是否在审计记录中包含客户端IP地址,默认为 <c>false</c> / Indicates whether to include client IP address in audit records, default is <c>false</c></value>
90102
public bool IncludeIpAddress { get; set; } = false;
91103

92104
/// <summary>
93-
/// 获取或设置审计表名称
105+
/// 获取或设置审计表名称
94106
/// </summary>
95-
/// <value>存储审计记录的表名称,如果为空则使用默认命名规则</value>
107+
/// <remarks>
108+
/// Gets or sets the audit table name. If null, the default naming convention is used.
109+
/// </remarks>
110+
/// <value>存储审计记录的表名称,如果为空则使用默认命名规则 / Table name for storing audit records, uses default naming convention if null</value>
96111
public string? AuditTableName { get; set; }
97112

98113
/// <summary>
99-
/// 获取或设置是否启用审计
114+
/// 获取或设置是否启用审计
100115
/// </summary>
101-
/// <value>指示是否启用审计功能,默认为 true</value>
116+
/// <remarks>
117+
/// Gets or sets whether auditing is enabled.
118+
/// </remarks>
119+
/// <value>指示是否启用审计功能,默认为 <c>true</c> / Indicates whether auditing is enabled, default is <c>true</c></value>
102120
public bool Enabled { get; set; } = true;
103121

104122
/// <summary>
105-
/// 初始化 <see cref="AuditTableAttribute"/> 类的新实例
123+
/// 初始化 <see cref="AuditTableAttribute"/> 类的新实例
106124
/// </summary>
125+
/// <remarks>
126+
/// Initializes a new instance of the <see cref="AuditTableAttribute"/> class.
127+
/// </remarks>
107128
public AuditTableAttribute()
108129
{
109130
}
110131

111132
/// <summary>
112-
/// 初始化 <see cref="AuditTableAttribute"/> 类的新实例
133+
/// 初始化 <see cref="AuditTableAttribute"/> 类的新实例
113134
/// </summary>
114-
/// <param name="auditLevel">审计级别</param>
135+
/// <remarks>
136+
/// Initializes a new instance of the <see cref="AuditTableAttribute"/> class with the specified audit level.
137+
/// </remarks>
138+
/// <param name="auditLevel">审计级别 / The audit level</param>
115139
public AuditTableAttribute(AuditLevel auditLevel)
116140
{
117141
AuditLevel = auditLevel;
118142
}
119143
}
120144

121145
/// <summary>
122-
/// 审计级别枚举
146+
/// 审计级别枚举
123147
/// </summary>
148+
/// <remarks>
149+
/// Audit level enumeration.
150+
/// </remarks>
124151
public enum AuditLevel
125152
{
126153
/// <summary>
127-
/// 不进行审计
154+
/// 不进行审计
128155
/// </summary>
156+
/// <remarks>
157+
/// No auditing.
158+
/// </remarks>
129159
None = 0,
130160

131161
/// <summary>
132-
/// 仅审计数据变更
162+
/// 仅审计数据变更
133163
/// </summary>
164+
/// <remarks>
165+
/// Audit data changes only.
166+
/// </remarks>
134167
ChangesOnly = 1,
135168

136169
/// <summary>
137-
/// 审计所有操作(包括查询)
170+
/// 审计所有操作(包括查询)
138171
/// </summary>
172+
/// <remarks>
173+
/// Audit all operations (including queries).
174+
/// </remarks>
139175
Full = 2,
140176

141177
/// <summary>
142-
/// 自定义审计规则
178+
/// 自定义审计规则
143179
/// </summary>
180+
/// <remarks>
181+
/// Custom audit rules.
182+
/// </remarks>
144183
Custom = 3
145-
}
184+
}

GameFrameX.Foundation.Orm.Attribute/CacheTableAttribute.cs

Lines changed: 47 additions & 25 deletions
Original file line numberDiff line numberDiff line change
@@ -34,19 +34,22 @@
3434
namespace GameFrameX.Foundation.Orm.Attribute;
3535

3636
/// <summary>
37-
/// 缓存表特性,用于标记实体类对应的数据库表支持缓存策略
37+
/// 缓存表特性,用于标记实体类对应的数据库表支持缓存策略
3838
/// </summary>
3939
/// <remarks>
40-
/// 此特性应用于实体类,用于标识该实体对应的数据库表支持缓存功能。
41-
/// 在ORM框架中,当实体类标记了此特性时,框架会启用相应的缓存策略,
42-
/// 例如查询结果缓存、实体缓存、分布式缓存等,以提高数据访问性能。
43-
///
44-
/// 缓存表通常具有以下特征:
45-
/// - 数据读取频率高,写入频率相对较低
46-
/// - 数据相对稳定,不经常变化
47-
/// - 对查询性能有较高要求
48-
/// - 可以容忍一定程度的数据延迟
49-
/// - 需要考虑缓存失效和更新策略
40+
/// Cache table attribute for marking entity classes whose corresponding database tables support caching strategies.
41+
/// When an entity class is marked with this attribute, the ORM framework enables corresponding caching strategies,
42+
/// such as query result caching, entity caching, and distributed caching to improve data access performance.
43+
/// <para>
44+
/// Cache tables typically have the following characteristics:
45+
/// </para>
46+
/// <list type="bullet">
47+
/// <item><description>High read frequency, relatively low write frequency</description></item>
48+
/// <item><description>Relatively stable data, not frequently changing</description></item>
49+
/// <item><description>High requirements for query performance</description></item>
50+
/// <item><description>Can tolerate some degree of data latency</description></item>
51+
/// <item><description>Need to consider cache invalidation and update strategies</description></item>
52+
/// </list>
5053
/// </remarks>
5154
/// <example>
5255
/// <code>
@@ -58,7 +61,7 @@ namespace GameFrameX.Foundation.Orm.Attribute;
5861
/// public decimal Price { get; set; }
5962
/// public DateTime LastModified { get; set; }
6063
/// }
61-
///
64+
///
6265
/// [CacheTable(CacheType = "Memory", ExpireMinutes = 10)]
6366
/// public class SystemConfiguration
6467
/// {
@@ -72,44 +75,63 @@ namespace GameFrameX.Foundation.Orm.Attribute;
7275
public sealed class CacheTableAttribute : System.Attribute
7376
{
7477
/// <summary>
75-
/// 获取或设置缓存类型
78+
/// 获取或设置缓存类型
7679
/// </summary>
77-
/// <value>缓存类型,如 "Memory"、"Redis"、"Distributed" 等</value>
80+
/// <remarks>
81+
/// Gets or sets the cache type, such as "Memory", "Redis", "Distributed", etc.
82+
/// </remarks>
83+
/// <value>缓存类型,如 "Memory"、"Redis"、"Distributed" 等 / Cache type, such as "Memory", "Redis", "Distributed", etc.</value>
7884
public string CacheType { get; set; } = "Memory";
7985

8086
/// <summary>
81-
/// 获取或设置缓存过期时间(分钟)
87+
/// 获取或设置缓存过期时间(分钟)
8288
/// </summary>
83-
/// <value>缓存过期时间,单位为分钟,默认为30分钟</value>
89+
/// <remarks>
90+
/// Gets or sets the cache expiration time in minutes.
91+
/// </remarks>
92+
/// <value>缓存过期时间,单位为分钟,默认为30分钟 / Cache expiration time in minutes, default is 30 minutes</value>
8493
public int ExpireMinutes { get; set; } = 30;
8594

8695
/// <summary>
87-
/// 获取或设置缓存键前缀
96+
/// 获取或设置缓存键前缀
8897
/// </summary>
89-
/// <value>缓存键的前缀,用于区分不同的缓存数据</value>
98+
/// <remarks>
99+
/// Gets or sets the cache key prefix for distinguishing different cache data.
100+
/// </remarks>
101+
/// <value>缓存键的前缀,用于区分不同的缓存数据 / Prefix for cache keys to distinguish different cache data</value>
90102
public string? KeyPrefix { get; set; }
91103

92104
/// <summary>
93-
/// 获取或设置是否启用缓存
105+
/// 获取或设置是否启用缓存
94106
/// </summary>
95-
/// <value>指示是否启用缓存功能,默认为 true</value>
107+
/// <remarks>
108+
/// Gets or sets whether caching is enabled.
109+
/// </remarks>
110+
/// <value>指示是否启用缓存功能,默认为 <c>true</c> / Indicates whether caching is enabled, default is <c>true</c></value>
96111
public bool Enabled { get; set; } = true;
97112

98113
/// <summary>
99-
/// 初始化 <see cref="CacheTableAttribute"/> 类的新实例
114+
/// 初始化 <see cref="CacheTableAttribute"/> 类的新实例
100115
/// </summary>
116+
/// <remarks>
117+
/// Initializes a new instance of the <see cref="CacheTableAttribute"/> class.
118+
/// </remarks>
101119
public CacheTableAttribute()
102120
{
103121
}
104122

105123
/// <summary>
106-
/// 初始化 <see cref="CacheTableAttribute"/> 类的新实例
124+
/// 初始化 <see cref="CacheTableAttribute"/> 类的新实例
107125
/// </summary>
108-
/// <param name="cacheType">缓存类型</param>
109-
/// <param name="expireMinutes">缓存过期时间(分钟)</param>
126+
/// <remarks>
127+
/// Initializes a new instance of the <see cref="CacheTableAttribute"/> class with the specified cache type and expiration time.
128+
/// </remarks>
129+
/// <param name="cacheType">缓存类型 / Cache type</param>
130+
/// <param name="expireMinutes">缓存过期时间(分钟) / Cache expiration time in minutes</param>
131+
/// <exception cref="ArgumentNullException">当 <paramref name="cacheType"/> 为 <c>null</c> 时抛出 / Thrown when <paramref name="cacheType"/> is <c>null</c></exception>
110132
public CacheTableAttribute(string cacheType, int expireMinutes = 30)
111133
{
112134
CacheType = cacheType ?? throw new ArgumentNullException(nameof(cacheType));
113135
ExpireMinutes = expireMinutes;
114136
}
115-
}
137+
}

GameFrameX.Foundation.Orm.Attribute/ConstAttribute.cs

Lines changed: 16 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -34,11 +34,12 @@
3434
namespace GameFrameX.Foundation.Orm.Attribute;
3535

3636
/// <summary>
37-
/// 常量特性,用于标记类、方法、属性等为常量定义
37+
/// 常量特性,用于标记类、方法、属性等为常量定义
3838
/// </summary>
3939
/// <remarks>
40-
/// 此特性可以应用于任何目标元素,用于标识该元素包含常量定义或具有常量性质。
41-
/// 在ORM框架中,可以用于标记数据库常量、配置常量等。
40+
/// Constant attribute for marking classes, methods, or properties as constant definitions.
41+
/// This attribute can be applied to any target element to indicate that the element contains constant definitions or has constant nature.
42+
/// In ORM frameworks, it can be used to mark database constants, configuration constants, etc.
4243
/// </remarks>
4344
/// <example>
4445
/// <code>
@@ -47,7 +48,7 @@ namespace GameFrameX.Foundation.Orm.Attribute;
4748
/// {
4849
/// public const string Version = "1.0.0";
4950
/// }
50-
///
51+
///
5152
/// [Const("StatusCode")]
5253
/// public enum UserStatus
5354
/// {
@@ -60,16 +61,22 @@ namespace GameFrameX.Foundation.Orm.Attribute;
6061
public sealed class ConstAttribute : System.Attribute
6162
{
6263
/// <summary>
63-
/// 获取或设置常量的名称
64+
/// 获取或设置常量的名称
6465
/// </summary>
65-
/// <value>常量的名称标识符</value>
66+
/// <remarks>
67+
/// Gets or sets the constant name.
68+
/// </remarks>
69+
/// <value>常量的名称标识符 / Constant name identifier</value>
6670
public string Name { get; set; }
6771

6872
/// <summary>
69-
/// 初始化 <see cref="ConstAttribute"/> 类的新实例
73+
/// 初始化 <see cref="ConstAttribute"/> 类的新实例
7074
/// </summary>
71-
/// <param name="name">常量的名称,用于标识该常量的用途或类型</param>
72-
/// <exception cref="ArgumentNullException">当 <paramref name="name"/> 为 null 时抛出</exception>
75+
/// <remarks>
76+
/// Initializes a new instance of the <see cref="ConstAttribute"/> class with the specified name.
77+
/// </remarks>
78+
/// <param name="name">常量的名称,用于标识该常量的用途或类型 / Constant name for identifying the purpose or type of the constant</param>
79+
/// <exception cref="ArgumentNullException">当 <paramref name="name"/> 为 <c>null</c> 时抛出 / Thrown when <paramref name="name"/> is <c>null</c></exception>
7380
public ConstAttribute(string name)
7481
{
7582
Name = name ?? throw new ArgumentNullException(nameof(name));

0 commit comments

Comments
 (0)