doc(DynamicObject): update documentation (#7756)

* doc: 更新注释文档

* doc: 更新动态类型注释文本

* doc: 更新注释

Author: ArgoZhang

src/BootstrapBlazor/Dynamic/DataTableDynamicContext.cs

@@ -10,14 +10,14 @@
 namespace BootstrapBlazor.Components;
 
 /// <summary>
-/// <para lang="zh">DataTable 动态数据上下文实现类 <see cref="DynamicObjectContext" /></para>
-/// <para lang="en">DataTable 动态data上下文实现类 <see cref="DynamicObjectContext" /></para>
+/// <para lang="zh">DataTable 动态数据上下文实现类 <see cref="DynamicObjectContext"/></para>
+/// <para lang="en">DataTable dynamic data context implementation class <see cref="DynamicObjectContext"/></para>
 /// </summary>
 public class DataTableDynamicContext : DynamicObjectContext
 {
     /// <summary>
     /// <para lang="zh">获得/设置 相关联的 DataTable 实例</para>
-    /// <para lang="en">Gets or sets 相关联的 DataTable instance</para>
+    /// <para lang="en">Gets or sets the associated DataTable instance</para>
     /// </summary>
     [NotNull]
     public DataTable? DataTable { get; set; }
@@ -32,37 +32,45 @@ public class DataTableDynamicContext : DynamicObjectContext
 
     /// <summary>
     /// <para lang="zh">获得/设置 是否启用内部缓存 默认 true 启用</para>
-    /// <para lang="en">Gets or sets whether启用内部缓存 Default is true 启用</para>
+    /// <para lang="en">Gets or sets whether to enable internal caching. Default is true.</para>
     /// </summary>
     public bool UseCache { get; set; } = true;
 
     /// <summary>
     /// <para lang="zh">负责将 DataRow 与 Items 关联起来方便查找提高效率</para>
-    /// <para lang="en">负责将 DataRow 与 Items 关联起来方便查找提高效率</para>
+    /// <para lang="en">Responsible for associating DataRow with Items to facilitate lookup and improve efficiency</para>
     /// </summary>
     private ConcurrentDictionary<Guid, (IDynamicObject DynamicObject, DataRow Row)> Caches { get; } = new();
 
     /// <summary>
     /// <para lang="zh">添加行回调委托</para>
-    /// <para lang="en">添加行回调delegate</para>
+    /// <para lang="en">Add row callback delegate</para>
     /// </summary>
     public Func<IEnumerable<IDynamicObject>, Task>? OnAddAsync { get; set; }
 
     /// <summary>
     /// <para lang="zh">删除行回调委托</para>
-    /// <para lang="en">删除行回调delegate</para>
+    /// <para lang="en">Delete row callback delegate</para>
     /// </summary>
     public Func<IEnumerable<IDynamicObject>, Task<bool>>? OnDeleteAsync { get; set; }
 
     /// <summary>
     /// <para lang="zh">构造函数</para>
-    /// <para lang="en">构造函数</para>
+    /// <para lang="en">Constructor</para>
     /// </summary>
     /// <param name="table"></param>
     /// <param name="addAttributesCallback"></param>
-    /// <param name="invisibleColumns"><para lang="zh">永远不显示的列集合 默认为 null 全部显示</para><para lang="en">永远不display的列collection default is为 null 全部display</para></param>
-    /// <param name="shownColumns"><para lang="zh">显示列集合 默认为 null 全部显示</para><para lang="en">display列collection default is为 null 全部display</para></param>
-    /// <param name="hiddenColumns"><para lang="zh">隐藏列集合 默认为 null 无隐藏列</para><para lang="en">隐藏列collection default is为 null 无隐藏列</para></param>
+    /// <param name="invisibleColumns">
+    ///   <para lang="zh">永远不显示的列集合 默认为 null 全部显示</para>
+    ///   <para lang="en">Collection of columns that are never displayed. Default is null, meaning all columns are displayed.</para>
+    /// </param>
+    /// <param name="shownColumns">
+    ///   <para lang="zh">显示列集合 默认为 null 全部显示</para>
+    ///   <para lang="en">Collection of columns that are always displayed. Default is null, meaning all columns are displayed.</para></param>
+    /// <param name="hiddenColumns">
+    ///   <para lang="zh">隐藏列集合 默认为 null 无隐藏列</para>
+    ///   <para lang="en">Collection of columns that are hidden. Default is null, meaning no columns are hidden.</para>
+    /// </param>
     public DataTableDynamicContext(DataTable table, Action<DataTableDynamicContext, ITableColumn>? addAttributesCallback = null, IEnumerable<string>? invisibleColumns = null, IEnumerable<string>? shownColumns = null, IEnumerable<string>? hiddenColumns = null)
     {
         DataTable = table;
@@ -111,8 +119,7 @@ private static bool GetShownColumns(ITableColumn col, IEnumerable<string>? invis
     }
 
     /// <summary>
-    /// <para lang="zh">GetItems 方法</para>
-    /// <para lang="en">GetItems 方法</para>
+    /// <inheritdoc/>
     /// </summary>
     public override IEnumerable<IDynamicObject> GetItems()
     {
@@ -157,15 +164,10 @@ private List<IDynamicObject> BuildItems()
     }
 
     /// <summary>
-    /// <para lang="zh">GetItems 方法</para>
-    /// <para lang="en">GetItems 方法</para>
+    /// <inheritdoc/>
     /// </summary>
     public override IEnumerable<ITableColumn> GetColumns() => Columns;
 
-    /// <summary>
-    /// <para lang="zh">获得列信息方法</para>
-    /// <para lang="en">Gets列信息方法</para>
-    /// </summary>
     private List<ITableColumn> InternalGetColumns()
     {
         var ret = new List<ITableColumn>();
@@ -177,10 +179,8 @@ private List<ITableColumn> InternalGetColumns()
     }
 
     /// <summary>
-    /// <para lang="zh"></para>
-    /// <para lang="en"></para>
+    /// <inheritdoc/>
     /// </summary>
-    /// <param name="col"></param>
     protected internal override IEnumerable<CustomAttributeBuilder> OnColumnCreating(ITableColumn col)
     {
         AddAttributesCallback?.Invoke(this, col);
@@ -189,10 +189,8 @@ protected internal override IEnumerable<CustomAttributeBuilder> OnColumnCreating
 
     #region Add Save Delete
     /// <summary>
-    /// <para lang="zh">新建方法</para>
-    /// <para lang="en">新建方法</para>
+    /// <inheritdoc/>
     /// </summary>
-    /// <param name="selectedItems"><para lang="zh">当前选中行</para><para lang="en">当前选中行</para></param>
     public override async Task AddAsync(IEnumerable<IDynamicObject> selectedItems)
     {
         if (OnAddAsync != null)
@@ -239,10 +237,8 @@ public override async Task AddAsync(IEnumerable<IDynamicObject> selectedItems)
     }
 
     /// <summary>
-    /// <para lang="zh">删除方法</para>
-    /// <para lang="en">删除方法</para>
+    /// <inheritdoc/>
     /// </summary>
-    /// <param name="items"></param>
     public override async Task<bool> DeleteAsync(IEnumerable<IDynamicObject> items)
     {
         var ret = false;
@@ -284,8 +280,8 @@ public override async Task<bool> DeleteAsync(IEnumerable<IDynamicObject> items)
     }
 
     /// <summary>
-    /// <para lang="zh">动态类型变更回调方法</para>
-    /// <para lang="en">动态type变更callback method</para>
+    /// <para lang="zh">单元格变更回调方法</para>
+    /// <para lang="en">Cell value changed callback method</para>
     /// </summary>
     /// <param name="item"></param>
     /// <param name="column"></param>

src/BootstrapBlazor/Dynamic/DataTableDynamicObject.cs

@@ -9,7 +9,7 @@ namespace BootstrapBlazor.Components;
 
 /// <summary>
 /// <para lang="zh">DataTable 动态类实例</para>
-/// <para lang="en">DataTable 动态类instance</para>
+/// <para lang="en">DataTable dynamic class instance</para>
 /// </summary>
 public class DataTableDynamicObject : DynamicObject
 {
@@ -45,8 +45,6 @@ public class DataTableDynamicObject : DynamicObject
     /// <summary>
     /// <inheritdoc/>
     /// </summary>
-    /// <param name="propertyName"></param>
-    /// <param name="value"></param>
     public override void SetValue(string propertyName, object? value)
     {
         base.SetValue(propertyName, value);

src/BootstrapBlazor/Dynamic/DynamicColumnsObject.cs

@@ -6,25 +6,26 @@
 namespace BootstrapBlazor.Components;
 
 /// <summary>
-/// <para lang="zh">动态列类</para>
-/// <para lang="en">动态列类</para>
+/// <para lang="zh"><see cref="IDynamicColumnsObject"/> 实现类</para>
+/// <para lang="en"><see cref="IDynamicColumnsObject"/> implementation class</para>
 /// </summary>
 public class DynamicColumnsObject : IDynamicColumnsObject
 {
     /// <summary>
-    /// <inheritdoc/>
+    /// <para lang="zh">获得/设置 列集合</para>
+    /// <para lang="en">Gets or sets the column collection</para>
     /// </summary>
     public Dictionary<string, object?> Columns { get; set; }
 
     /// <summary>
     /// <para lang="zh">获得/设置 行主键</para>
-    /// <para lang="en">Gets or sets 行主键</para>
+    /// <para lang="en">Gets or sets the row primary key</para>
     /// </summary>
     public Guid DynamicObjectPrimaryKey { get; set; }
 
     /// <summary>
     /// <para lang="zh">构造函数</para>
-    /// <para lang="en">构造函数</para>
+    /// <para lang="en">Constructor</para>
     /// </summary>
     /// <param name="columnsData"></param>
     public DynamicColumnsObject(Dictionary<string, object?> columnsData)
@@ -34,12 +35,13 @@ public DynamicColumnsObject(Dictionary<string, object?> columnsData)
 
     /// <summary>
     /// <para lang="zh">构造函数</para>
-    /// <para lang="en">构造函数</para>
+    /// <para lang="en">Constructor</para>
     /// </summary>
     public DynamicColumnsObject() : this([]) { }
 
     /// <summary>
-    /// <inheritdoc/>
+    /// <para lang="zh">获得列的值</para>
+    /// <para lang="en">Gets the value of a column</para>
     /// </summary>
     /// <param name="propertyName"></param>
     public virtual object? GetValue(string propertyName)
@@ -48,10 +50,9 @@ public DynamicColumnsObject() : this([]) { }
     }
 
     /// <summary>
-    /// <inheritdoc/>
+    /// <para lang="zh">设置列的值</para>
+    /// <para lang="en">Sets the value of a column</para>
     /// </summary>
-    /// <param name="propertyName"></param>
-    /// <param name="value"></param>
     public virtual void SetValue(string propertyName, object? value)
     {
         Columns[propertyName] = value;

src/BootstrapBlazor/Dynamic/DynamicItemChangedType.cs

@@ -6,20 +6,20 @@
 namespace BootstrapBlazor.Components;
 
 /// <summary>
-/// <para lang="zh">DynamicItemChangedType 类型</para>
-/// <para lang="en">DynamicItemChangedType type</para>
+/// <para lang="zh">DynamicItemChangedType 枚举类型</para>
+/// <para lang="en">DynamicItemChangedType enum type</para>
 /// </summary>
 public enum DynamicItemChangedType
 {
     /// <summary>
     /// <para lang="zh">新建</para>
-    /// <para lang="en">新建</para>
+    /// <para lang="en">Add</para>
     /// </summary>
     Add,
 
     /// <summary>
     /// <para lang="zh">删除</para>
-    /// <para lang="en">删除</para>
+    /// <para lang="en">Delete</para>
     /// </summary>
     Delete
 }

src/BootstrapBlazor/Dynamic/DynamicObject.cs

@@ -6,8 +6,8 @@
 namespace BootstrapBlazor.Components;
 
 /// <summary>
-/// <para lang="zh">动态类型实体类 <see cref="IDynamicObject" /> 实例</para>
-/// <para lang="en">动态type实体类 <see cref="IDynamicObject" /> instance</para>
+/// <para lang="zh"><see cref="IDynamicObject"/> 实现类</para>
+/// <para lang="en"><see cref="IDynamicObject"/> implementation class</para>
 /// </summary>
 public class DynamicObject : IDynamicObject
 {
@@ -19,14 +19,14 @@ public class DynamicObject : IDynamicObject
 
     /// <summary>
     /// <para lang="zh">获得指定属性值方法</para>
-    /// <para lang="en">Gets指定property值方法</para>
+    /// <para lang="en">Gets the value of a specified property</para>
     /// </summary>
     /// <param name="propertyName"></param>
     public virtual object? GetValue(string propertyName) => Utility.GetPropertyValue(this, propertyName);
 
     /// <summary>
     /// <para lang="zh">给指定属性设置值方法</para>
-    /// <para lang="en">给指定propertySets值方法</para>
+    /// <para lang="en">Sets the value of a specified property</para>
     /// </summary>
     /// <param name="propertyName"></param>
     /// <param name="value"></param>

src/BootstrapBlazor/Dynamic/DynamicObjectContext.cs

@@ -10,39 +10,33 @@
 namespace BootstrapBlazor.Components;
 
 /// <summary>
-/// <para lang="zh">动态类型上下文基类 <see cref="IDynamicObjectContext" /></para>
-/// <para lang="en">动态type上下文基类 <see cref="IDynamicObjectContext" /></para>
+/// <para lang="zh"><see cref="IDynamicObjectContext"/> 实现类基类</para>
+/// <para lang="en"><see cref="IDynamicObjectContext"/> base class</para>
 /// </summary>
 public abstract class DynamicObjectContext : IDynamicObjectContext
 {
     /// <summary>
     /// <para lang="zh">获取动态类型各列信息</para>
-    /// <para lang="en">获取动态type各列信息</para>
+    /// <para lang="en">Gets the column information of the dynamic type</para>
     /// </summary>
     public abstract IEnumerable<ITableColumn> GetColumns();
 
     /// <summary>
     /// <para lang="zh">获得动态类数据方法</para>
-    /// <para lang="en">Gets动态类data方法</para>
+    /// <para lang="en">Gets the data of the dynamic type</para>
     /// </summary>
     public abstract IEnumerable<IDynamicObject> GetItems();
 
     /// <summary>
-    /// <para lang="zh"></para>
-    /// <para lang="en"></para>
+    /// <para lang="zh">获取自定义属性构建器缓存</para>
+    /// <para lang="en">Gets the custom attribute builder cache</para>
     /// </summary>
     protected ConcurrentDictionary<string, List<CustomAttributeBuilder>> CustomerAttributeBuilderCache { get; } = new();
 
     /// <summary>
     /// <para lang="zh">添加标签到指定列</para>
-    /// <para lang="en">添加标签到指定列</para>
+    /// <para lang="en">Adds an attribute to the specified column</para>
     /// </summary>
-    /// <param name="columnName"><para lang="zh">指定列名称</para><para lang="en">指定列name</para></param>
-    /// <param name="attributeType"><para lang="zh">Attribute 实例</para><para lang="en">Attribute instance</para></param>
-    /// <param name="types"></param>
-    /// <param name="constructorArgs"></param>
-    /// <param name="propertyInfos"></param>
-    /// <param name="propertyValues"></param>
     public void AddAttribute(string columnName, Type attributeType, Type[] types, object?[] constructorArgs, PropertyInfo[]? propertyInfos = null, object?[]? propertyValues = null)
     {
         var attr = attributeType.GetConstructor(types);
@@ -60,46 +54,47 @@ public void AddAttribute(string columnName, Type attributeType, Type[] types, ob
 
     /// <summary>
     /// <para lang="zh">列创建回调方法 入口参数为 ITableColumn 实例 返回值为 CustomAttributeBuilder 集合</para>
-    /// <para lang="en">列创建callback method 入口参数为 ITableColumn instance 返回值为 CustomAttributeBuilder collection</para>
+    /// <para lang="en">Column creation callback method. The input parameter is an ITableColumn instance, and the return value is a collection of CustomAttributeBuilder.</para>
     /// </summary>
     protected internal virtual IEnumerable<CustomAttributeBuilder> OnColumnCreating(ITableColumn col) => CustomerAttributeBuilderCache.TryGetValue(col.GetFieldName(), out var builders)
         ? builders
         : Enumerable.Empty<CustomAttributeBuilder>();
 
     /// <summary>
     /// <para lang="zh">动态类型新建回调委托</para>
-    /// <para lang="en">动态type新建回调delegate</para>
+    /// <para lang="en">Dynamic type creation callback delegate</para>
     /// </summary>
-    /// <param name="selectedItems"><para lang="zh">当前选中行</para><para lang="en">当前选中行</para></param>
+    /// <param name="selectedItems"><para lang="zh">当前选中行</para><para lang="en">Currently selected rows</para></param>
     public abstract Task AddAsync(IEnumerable<IDynamicObject> selectedItems);
 
     /// <summary>
     /// <para lang="zh">动态类型删除回调委托</para>
-    /// <para lang="en">动态type删除回调delegate</para>
+    /// <para lang="en">Dynamic type deletion callback delegate</para>
     /// </summary>
-    /// <param name="items"></param>
+    /// <param name="items"><para lang="zh">要删除的行</para><para lang="en">Rows to be deleted</para></param>
     public abstract Task<bool> DeleteAsync(IEnumerable<IDynamicObject> items);
 
     /// <summary>
     /// <para lang="zh">动态类型集合变化时回调方法</para>
-    /// <para lang="en">动态typecollection变化时callback method</para>
+    /// <para lang="en">Dynamic type collection change callback method</para>
     /// </summary>
     public Func<IDynamicObject, ITableColumn, object?, Task>? OnValueChanged { get; set; }
 
     /// <summary>
     /// <para lang="zh">动态类型属性值变化时回调方法</para>
-    /// <para lang="en">动态typeproperty值变化时callback method</para>
+    /// <para lang="en">Dynamic type property value change callback method</para>
     /// </summary>
     public Func<DynamicObjectContextArgs, Task>? OnChanged { get; set; }
 
     /// <summary>
     /// <para lang="zh">获得选中行比对回调方法</para>
-    /// <para lang="en">Gets选中行比对callback method</para>
+    /// <para lang="en">Gets the selected row comparison callback method</para>
     /// </summary>
     public Func<IDynamicObject?, IDynamicObject?, bool>? EqualityComparer { get; set; }
 
     /// <summary>
-    /// <inheritdoc/>
+    /// <para lang="zh">过滤回调方法</para>
+    /// <para lang="en">Filter callback method</para>
     /// </summary>
     public Func<QueryPageOptions, IEnumerable<IDynamicObject>, IEnumerable<IDynamicObject>>? OnFilterCallback { get; set; }
 }