doc(Component): comments support both Chinese and English (#7532)

* docs: provided English translations

* docs: manual edit and improvement to the documentation

* docs: wrapped example in code block

Author: peereflits

src/BootstrapBlazor/Components/ContextMenu/ContextMenu.razor.cs

@@ -1,4 +1,4 @@
-// Licensed to the .NET Foundation under one or more agreements.
+// Licensed to the .NET Foundation under one or more agreements.
 // The .NET Foundation licenses this file to you under the Apache 2.0 License
 // See the LICENSE file in the project root for more information.
 // Maintainer: Argo Zhang([email protected]) Website: https://www.blazor.zone
@@ -8,24 +8,28 @@
 namespace BootstrapBlazor.Components;
 
 /// <summary>
-/// ContextMenu 组件
+/// <para lang="zh">ContextMenu 组件</para>
+/// <para lang="en">A component that represents a context menu.</para>
 /// </summary>
 public partial class ContextMenu
 {
     /// <summary>
-    /// 获得/设置 是否显示阴影 默认 true
+    /// <para lang="zh">获得/设置 是否显示阴影 默认 <see langword="true" /></para>
+    /// <para lang="en">Flags whether to show a shadow around the context menu. Default is <see langword="true" />.</para>
     /// </summary>
     [Parameter]
     public bool ShowShadow { get; set; } = true;
 
     /// <summary>
-    /// 获得/设置 弹出前回调方法 默认 null
+    /// <para lang="zh">获得/设置 弹出前回调方法 默认 null</para>
+    /// <para lang="en">Defines the callback that is executed before showing the context menu. Default is <see langword="null" />.</para>
     /// </summary>
     [Parameter]
     public Func<object?, Task>? OnBeforeShowCallback { get; set; }
 
     /// <summary>
-    /// 获得/设置 子组件
+    /// <para lang="zh">获得/设置 子组件</para>
+    /// <para lang="en">The <see cref="RenderFragment"/> that represents the child content.</para>
     /// </summary>
     [Parameter]
     public RenderFragment? ChildContent { get; set; }
@@ -57,21 +61,15 @@ public partial class ContextMenu
 
     private object? _contextItem;
 
-    /// <summary>
     /// <inheritdoc/>
-    /// </summary>
     protected override void OnInitialized()
     {
         base.OnInitialized();
 
         ContextMenuZone.RegisterContextMenu(this);
     }
 
-    /// <summary>
     /// <inheritdoc/>
-    /// </summary>
-    /// <param name="firstRender"></param>
-    /// <returns></returns>
     protected override async Task OnAfterRenderAsync(bool firstRender)
     {
         await base.OnAfterRenderAsync(firstRender);
@@ -84,11 +82,21 @@ protected override async Task OnAfterRenderAsync(bool firstRender)
     }
 
     /// <summary>
-    /// 弹出 ContextMenu
+    /// <para lang="zh">弹出 ContextMenu</para>
+    /// <para lang="en">Shows the <see cref="ContextMenu"/>.</para>
     /// </summary>
-    /// <param name="args"></param>
-    /// <param name="contextItem"></param>
-    /// <returns></returns>
+    /// <param name="args">
+    ///     <para lang="zh">鼠标事件参数</para>
+    ///     <para lang="en">The <see cref="MouseEventArgs"/> that invoked this event.</para>
+    /// </param>
+    /// <param name="contextItem">
+    ///     <para lang="zh">上下文项</para>
+    ///     <para lang="en">Context that is associated with the clicked <see cref="ContextMenuItem"/>.</para>
+    /// </param>
+    /// <returns>
+    ///     <para lang="zh">异步任务</para>
+    ///     <para lang="en">An asynchronous instance of a <see cref="Task"/>.</para>
+    /// </returns>
     internal async Task Show(MouseEventArgs args, object? contextItem)
     {
         _contextItem = contextItem;
@@ -109,14 +117,22 @@ private async Task OnClickItem(ContextMenuItem item)
     }
 
     /// <summary>
-    /// 增加 ContextMenuItem 方法
+    /// <para lang="zh">增加 ContextMenuItem 方法</para>
+    /// <para lang="en">Adds an <paramref name="item"/> to the menu.</para>
     /// </summary>
-    /// <param name="item"></param>
+    /// <param name="item">
+    ///     <para lang="zh">要添加的项</para>
+    ///     <para lang="en">The <see cref="IContextMenuItem"/> to add</para>
+    /// </param>
     internal void AddItem(IContextMenuItem item) => _contextMenuItems.Add(item);
 
     /// <summary>
-    /// 移除 ContextMenuItem 方法
+    /// <para lang="zh">移除 ContextMenuItem 方法</para>
+    /// <para lang="en">Removes an <paramref name="item"/> from the menu.</para>
     /// </summary>
-    /// <param name="item"></param>
+    /// <param name="item">
+    ///     <para lang="zh">要移除的项</para>
+    ///     <para lang="en">The <see cref="IContextMenuItem"/> to remove</para>
+    /// </param>
     internal void RemoveItem(IContextMenuItem item) => _contextMenuItems.Remove(item);
 }

src/BootstrapBlazor/Components/ContextMenu/ContextMenuDivider.cs

@@ -1,4 +1,4 @@
-// Licensed to the .NET Foundation under one or more agreements.
+// Licensed to the .NET Foundation under one or more agreements.
 // The .NET Foundation licenses this file to you under the Apache 2.0 License
 // See the LICENSE file in the project root for more information.
 // Maintainer: Argo Zhang([email protected]) Website: https://www.blazor.zone
@@ -8,36 +8,36 @@
 namespace BootstrapBlazor.Components;
 
 /// <summary>
-/// ContextMenuDivider 组件
+/// <para lang="zh">ContextMenuDivider 组件</para>
+/// <para lang="en">A component that defines a menu item as a divider in a context menu.</para>
 /// </summary>
 public class ContextMenuDivider : Divider, IContextMenuItem, IDisposable
 {
     [CascadingParameter]
     [NotNull]
     private ContextMenu? ContextMenu { get; set; }
 
-    /// <summary>
     /// <inheritdoc/>
-    /// </summary>
     protected override void OnInitialized()
     {
         base.OnInitialized();
 
         ContextMenu.AddItem(this);
     }
 
-    /// <summary>
     /// <inheritdoc/>
-    /// </summary>
-    /// <param name="builder"></param>
     protected override void BuildRenderTree(RenderTreeBuilder builder) { }
 
     private bool disposedValue;
 
     /// <summary>
-    /// 释放资源方法
+    /// <para lang="zh">释放资源方法</para>
+    /// <para lang="en">Method to release resources.</para>
     /// </summary>
-    /// <param name="disposing"></param>
+    /// <param name="disposing">
+    ///     <para lang="zh">是否释放托管资源</para>
+    ///     <para lang="en">Flags whether to release managed resources</para>
+    /// </param>
     protected virtual void Dispose(bool disposing)
     {
         if (!disposedValue)
@@ -50,9 +50,7 @@ protected virtual void Dispose(bool disposing)
         }
     }
 
-    /// <summary>
     /// <inheritdoc/>
-    /// </summary>
     public void Dispose()
     {
         Dispose(disposing: true);

src/BootstrapBlazor/Components/ContextMenu/ContextMenuItem.cs

@@ -1,41 +1,52 @@
-// Licensed to the .NET Foundation under one or more agreements.
+// Licensed to the .NET Foundation under one or more agreements.
 // The .NET Foundation licenses this file to you under the Apache 2.0 License
 // See the LICENSE file in the project root for more information.
 // Maintainer: Argo Zhang([email protected]) Website: https://www.blazor.zone
 
 namespace BootstrapBlazor.Components;
 
 /// <summary>
-/// ContextMenuItem 类
+/// <para lang="zh">ContextMenuItem 类</para>
+/// <para lang="en">A type that represents a menu item in a <see cref="ContextMenu"/>.</para>
 /// </summary>
 public class ContextMenuItem : ComponentBase, IContextMenuItem, IDisposable
 {
     /// <summary>
-    /// 获得/设置 显示文本
+    /// <para lang="zh">获得/设置 显示文本</para>
+    /// <para lang="en">The text to display.</para>
     /// </summary>
     [Parameter]
     public string? Text { get; set; }
 
     /// <summary>
-    /// 获得/设置 图标
+    /// <para lang="zh">获得/设置 图标</para>
+    ///  <para lang="en">The CSS class name that represents an icon (if any)</para>
     /// </summary>
+    /// <example>
+    /// <code>
+    /// Icon="fa-solid fa-bookmark"
+    /// </code> 
+    /// </example>
     [Parameter]
     public string? Icon { get; set; }
 
     /// <summary>
-    /// 获得/设置 是否被禁用 默认 false 优先级低于 <see cref="OnDisabledCallback"/>
+    /// <para lang="zh">获得/设置 是否被禁用 默认 false 优先级低于 <see cref="OnDisabledCallback"/></para>
+    /// <para lang="en">Flags whether the item is disabled. Default is <see langword="false"/>. It has a lower priority than <see cref="OnDisabledCallback"/>.</para>
     /// </summary>
     [Parameter]
     public bool Disabled { get; set; }
 
     /// <summary>
-    /// 获得/设置 是否被禁用回调方法 默认 null 优先级高于 <see cref="Disabled"/>
+    /// <para lang="zh">获得/设置 是否被禁用回调方法 默认 null 优先级高于 <see cref="Disabled"/></para>
+    /// <para lang="en">Defines the callback to determine if the item is disabled. Default is <see langword="null" />. It has a higher priority than <see cref="Disabled"/>.</para>
     /// </summary>
     [Parameter]
     public Func<ContextMenuItem, object?, bool>? OnDisabledCallback { get; set; }
 
     /// <summary>
-    /// 获得/设置 点击回调方法 默认 null
+    /// <para lang="zh">获得/设置 点击回调方法 默认 null</para>
+    /// <para lang="en">Defines the click callback. Default is <see langword="null" />.</para>
     /// </summary>
     [Parameter]
     public Func<ContextMenuItem, object?, Task>? OnClick { get; set; }
@@ -44,9 +55,7 @@ public class ContextMenuItem : ComponentBase, IContextMenuItem, IDisposable
     [NotNull]
     private ContextMenu? ContextMenu { get; set; }
 
-    /// <summary>
     /// <inheritdoc/>
-    /// </summary>
     protected override void OnInitialized()
     {
         base.OnInitialized();
@@ -57,9 +66,10 @@ protected override void OnInitialized()
     private bool disposedValue;
 
     /// <summary>
-    /// 释放资源方法
+    /// <para lang="zh">释放资源方法</para>
+    /// <para lang="en">Method to release resources.</para>
     /// </summary>
-    /// <param name="disposing"></param>
+    /// <param name="disposing"><para lang="zh">是否释放托管资源</para><para lang="en">Whether to release managed resources</para></param>
     protected virtual void Dispose(bool disposing)
     {
         if (!disposedValue)
@@ -72,9 +82,7 @@ protected virtual void Dispose(bool disposing)
         }
     }
 
-    /// <summary>
     /// <inheritdoc/>
-    /// </summary>
     public void Dispose()
     {
         Dispose(disposing: true);

src/BootstrapBlazor/Components/ContextMenu/ContextMenuTrigger.cs

@@ -9,24 +9,25 @@
 namespace BootstrapBlazor.Components;
 
 /// <summary>
-/// ContextMenuTrigger 组件
+/// <para lang="zh">ContextMenuTrigger 组件</para>
+/// <para lang="en">A component that defines a trigger that shows a <see cref="ContextMenu"/>.</para>
 /// </summary>
 public class ContextMenuTrigger : BootstrapComponentBase
 {
-    /// <summary>
-    /// 获得/设置 子组件
-    /// </summary>
+    /// <inheritdoc cref="ContextMenu.ChildContent" />
     [Parameter]
     public RenderFragment? ChildContent { get; set; }
 
     /// <summary>
-    /// 获得/设置 包裹组件 TagName 默认为 div
+    /// <para lang="zh">获得/设置 包裹组件 TagName 默认为 div</para>
+    /// <para lang="en">The HTML tag name to use for the trigger. Default is &lt;div&gt;.</para>
     /// </summary>
     [Parameter]
     public string WrapperTag { get; set; } = "div";
 
     /// <summary>
-    /// 获得/设置 上下文数据
+    /// <para lang="zh">获得/设置 上下文数据</para>
+    /// <para lang="en">Gets or sets the context data.</para>
     /// </summary>
     [Parameter]
     public object? ContextItem { get; set; }
@@ -36,8 +37,8 @@ public class ContextMenuTrigger : BootstrapComponentBase
     private ContextMenuZone? ContextMenuZone { get; set; }
 
     /// <summary>
-    /// The timeout duration for touch events to trigger the context menu (in milliseconds).
-    /// Default is <see cref="ContextMenuOptions.OnTouchDelay"/> milliseconds. Must be greater than 0.
+    /// <para lang="zh">触摸事件触发菜单的超时时间（毫秒）。默认值为 <see cref="ContextMenuOptions.OnTouchDelay"/> 毫秒。必须大于 0。</para>
+    /// <para lang="en">The timeout duration for touch events to trigger the context menu (in milliseconds). Default is <see cref="ContextMenuOptions.OnTouchDelay"/> milliseconds. Must be greater than 0.</para>
     /// </summary>
     [Parameter]
     public int? OnTouchDelay { get; set; }
@@ -49,20 +50,15 @@ public class ContextMenuTrigger : BootstrapComponentBase
         .AddClassFromAttributes(AdditionalAttributes)
         .Build();
 
-    /// <summary>
     /// <inheritdoc/>
-    /// </summary>
     protected override void OnParametersSet()
     {
         base.OnParametersSet();
 
         OnTouchDelay ??= Options.CurrentValue.ContextMenuOptions.OnTouchDelay;
     }
 
-    /// <summary>
     /// <inheritdoc/>
-    /// </summary>
-    /// <param name="builder"></param>
     protected override void BuildRenderTree(RenderTreeBuilder builder)
     {
         builder.OpenElement(0, WrapperTag);
@@ -77,18 +73,21 @@ protected override void BuildRenderTree(RenderTreeBuilder builder)
     }
 
     /// <summary>
-    /// 点击 ContextMenu 菜单项时触发
+    /// <para lang="zh">点击 ContextMenu 菜单项时触发</para>
+    /// <para lang="en">Triggered when a context menu item is clicked.</para>
     /// </summary>
     [DynamicDependency(DynamicallyAccessedMemberTypes.PublicMethods, typeof(MouseEventArgs))]
     public Task OnContextMenu(MouseEventArgs args) => ContextMenuZone.OnContextMenu(args, ContextItem);
 
     /// <summary>
-    /// 是否触摸
+    /// <para lang="zh">是否触摸</para>
+    /// <para lang="en">Indicates whether a touch event is started.</para>
     /// </summary>
     public bool IsTouchStarted { get; private set; }
 
     /// <summary>
-    /// 触摸定时器工作指示
+    /// <para lang="zh">触摸定时器工作指示</para>
+    /// <para lang="en">Indicates whether the touch timer is working.</para>
     /// </summary>
     private bool IsBusy { get; set; }