Rewrite XML docs in Simplified Chinese (#17)

* AudioClient and AudioStream * Command & Activity * Working head * Working head * Working head * Working head * wording * Invite and Intimacy * Elements * modules and card * Messages * Fixes tests * Messages - Added `TagUtil` - Changed `Tag<T>` to `Tag<TKey, TValue>` - Adjusted the results of `IUserMessage.Resolve` * Permissinos * Users * More Users * Users and entities * Rest Channels * Update doc * Intimacy remarks * Rest entities * incoming audio * REST * Socket Channels * SocketDMChannel * SocketGuild * Extract LoginAsync and LogoutAsync to IKookClient (#20) * IKookClient * Socket entities * Socket clients * Webhook * Extensions misc * CardMarkup and Commands * Experimental with removing invalid implementations * Missed docs * Fixes EveryoneMention and HereMention tags contain signed zero as value
gehongyan · Aug 24, 2024 · 35583e3 · 35583e3
1 parent e4eaff4
commit 35583e3
Show file tree

Hide file tree

Showing 450 changed files with 8,373 additions and 11,140 deletions.
diff --git a/THIRD-PARTY-NOTICES.txt b/THIRD-PARTY-NOTICES.txt
@@ -126,6 +126,13 @@ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
 OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
 SOFTWARE.
 
+License notice for MassTransit
+------------------------------------
+
+Licensed under the Apache License, Version 2.0.
+Available at
+https://github.com/MassTransit/MassTransit/blob/develop/LICENSE
+
 License notice for Microsoft.NET.Test.Sdk
 ------------------------------------
 

diff --git a/docs/guides/voice/sending-voice.md b/docs/guides/voice/sending-voice.md
@@ -66,7 +66,7 @@ opus 在同一位置），参见 [FFmpeg 的下载页面]，或使用操作系
 
 [IAudioClient]: xref:Kook.Audio.IAudioClient
 [AudioOutStream]: xref:Kook.Audio.AudioOutStream
-[IAudioClient.CreatePCMStream]: xref:Kook.Audio.IAudioClient#Kook_Audio_IAudioClient_CreatePcmStream_Kook_Audio_AudioApplication_System_Int32_System_Int32_System_Int32_
+[IAudioClient.CreatePCMStream]: xref:Kook.Audio.IAudioClient#Kook_Audio_IAudioClient_CreatePcmStream_Kook_Audio_AudioApplication_System_Nullable_System_Int32__System_Int32_System_Int32_
 
 最后，音频需要从 FFmpeg 的标准输出流传输到你的 AudioOutStream 对象中。
 根据你的业务需要，这个步骤中间可能会进行某些处理，但在大多数情况下，使用 [Stream.CopyToAsync] 即可。

diff --git a/docs/quick_reference/http_api/oauth.md b/docs/quick_reference/http_api/oauth.md
@@ -16,10 +16,9 @@ readonly KookRestClient _restClient = null;
 
 POST `/api/oauth2/token`
 
-无公开 API，请使用 `AspNet.Security.OAuth.Kook`，请参考：
+无公开 API。可参考以下类库：
 
-*  NuGet: <https://www.nuget.org/packages/AspNet.Security.OAuth.Kook/>
-*  GitHub: <https://github.com/aspnet-contrib/AspNet.Security.OAuth.Providers>
-*  文档：<https://github.com/aspnet-contrib/AspNet.Security.OAuth.Providers/blob/dev/docs/kook.md>
+- **AspNet.Security.OAuth.Kook**：[NuGet](https://www.nuget.org/packages/AspNet.Security.OAuth.Kook/)，[GitHub](https://github.com/aspnet-contrib/AspNet.Security.OAuth.Providers)，[文档](https://github.com/aspnet-contrib/AspNet.Security.OAuth.Providers/blob/dev/docs/kook.md)
+- **OpenIddict**：[NuGet](https://www.nuget.org/packages/OpenIddict/)，[GitHub](https://github.com/openiddict/openiddict-core)，[文档](https://documentation.openiddict.com/)
 
 [获取 AccessToken]: https://developer.kookapp.cn/doc/http/oauth#获取AccessToken
diff --git a/samples/Kook.Net.Samples.Audio/Modules/MusicModule.cs b/samples/Kook.Net.Samples.Audio/Modules/MusicModule.cs
@@ -17,8 +17,6 @@ public class MusicModule : ModuleBase<SocketCommandContext>
     private readonly MusicService _musicService;
     private readonly IHttpClientFactory _httpClientFactory;
 
-
-
     /// <summary>
     ///     Initializes a new instance of the <see cref="MusicModule"/> class.
     /// </summary>

diff --git a/samples/Kook.Net.Samples.FSharp/Program.fs b/samples/Kook.Net.Samples.FSharp/Program.fs
@@ -7,7 +7,7 @@ open Kook.WebSocket
 // 这是一个使用 Kook.Net 的 F# 简单示例
 // Kook.Net 的所有文档均以 C# 编写，但是 Kook.Net 也支持 F#
 
-// 如果要编写带有命令的机器人，我们建议使用 Kook.Net.Commands 框架
+// 如果要编写带有命令的 Bot，我们建议使用 Kook.Net.Commands 框架
 // 而不是像在这个示例中一样自己处理它们。
 
 // 您可以在以下位置找到使用命令框架的示例：

diff --git a/samples/Kook.Net.Samples.SimpleBot/Program.cs b/samples/Kook.Net.Samples.SimpleBot/Program.cs
@@ -3,7 +3,7 @@
 
 // 这是一个使用 Kook.Net 的 C# 简单示例
 
-// 如果要编写带有命令的机器人，我们建议使用 Kook.Net.Commands 框架
+// 如果要编写带有命令的 Bot，我们建议使用 Kook.Net.Commands 框架
 // 而不是像在这个示例中一样自己处理它们。
 
 // 您可以在以下位置找到使用命令框架的示例：

diff --git a/samples/Kook.Net.Samples.VisualBasic/Program.vb b/samples/Kook.Net.Samples.VisualBasic/Program.vb
@@ -4,7 +4,7 @@ Imports Kook.WebSocket
 ' 这是一个使用 Kook.Net 的 Visual Basic 简单示例
 ' Kook.Net 的所有文档均以 C# 编写，但是 Kook.Net 也支持 Visual Basic
 
-' 如果要编写带有命令的机器人，我们建议使用 Kook.Net.Commands 框架
+' 如果要编写带有命令的 Bot，我们建议使用 Kook.Net.Commands 框架
 ' 而不是像在这个示例中一样自己处理它们。
 
 ' 您可以在以下位置找到使用命令框架的示例：

diff --git a/src/Kook.Net.CardMarkup/CardMarkupSerializer.cs b/src/Kook.Net.CardMarkup/CardMarkupSerializer.cs
@@ -7,20 +7,19 @@
 namespace Kook.CardMarkup;
 
 /// <summary>
-///     Serializer for Card Message XML markup
+///     提供用于从 XML 标记语言创建卡片消息的序列化器。
 /// </summary>
 public static class CardMarkupSerializer
 {
     #region Async
 
     /// <summary>
-    ///     Deserialize a Card Message XML markup file to a <see cref="ICard"/> list.
-    ///     One XML markup file has one card-message element, which can
-    ///     contain multiple card elements.
+    ///     将卡片消息 XML 标记文件反序列化为 <see cref="ICard"/> 列表，每个 XML 文件包含一个 <c>card-message</c>
+    ///     元素，可以包含多个 <c>card</c> 元素。
     /// </summary>
-    /// <param name="file">UTF-8 encoded XML file</param>
-    /// <param name="token">Cancellation token</param>
-    /// <returns><see cref="ICard"/> enumerable</returns>
+    /// <param name="file"> UTF-8 编码的 XML 文件 </param>
+    /// <param name="token"> 取消令牌。 </param>
+    /// <returns> 一个表示异步解析操作的任务。任务的结果包含一个可用于枚举 <see cref="ICard"/> 成员的 <see cref="T:System.Collections.Generic.IEnumerable`1"/>。 </returns>
     public static async Task<IEnumerable<ICard>> DeserializeAsync(FileInfo file, CancellationToken token = default)
     {
 #if NETSTANDARD2_0 || NET462
@@ -32,27 +31,25 @@ public static async Task<IEnumerable<ICard>> DeserializeAsync(FileInfo file, Can
     }
 
     /// <summary>
-    ///     Deserialize a Card Message XML markup text to a <see cref="ICard"/> list.
-    ///     One XML markup file has one card-message element, which can
-    ///     contain multiple card elements.
+    ///     将卡片消息 XML 标记文本反序列化为 <see cref="ICard"/> 列表，每个 XML 文件包含一个 <c>card-message</c>
+    ///     元素，可以包含多个 <c>card</c> 元素。
     /// </summary>
-    /// <param name="xmlText">UTF-8 encoded XML text</param>
-    /// <param name="token">Cancellation token</param>
-    /// <returns><see cref="ICard"/> enumerable</returns>
+    /// <param name="xmlText"> UTF-8 编码的 XML 文本。 </param>
+    /// <param name="token"> 取消令牌。 </param>
+    /// <returns> 一个表示异步解析操作的任务。任务的结果包含一个可用于枚举 <see cref="ICard"/> 成员的 <see cref="T:System.Collections.Generic.IEnumerable`1"/>。 </returns>
     public static async Task<IEnumerable<ICard>> DeserializeAsync(string xmlText, CancellationToken token = default)
     {
         using MemoryStream xmlStream = new(Encoding.UTF8.GetBytes(xmlText));
         return await DeserializeAsync(xmlStream, token);
     }
 
     /// <summary>
-    ///     Deserialize a Card Message XML stream to a <see cref="ICard"/> list.
-    ///     One XML markup file has one card-message element, which can
-    ///     contain multiple card elements.
+    ///     将卡片消息 XML 标记文本流反序列化为 <see cref="ICard"/> 列表，每个 XML 文件包含一个 <c>card-message</c>
+    ///     元素，可以包含多个 <c>card</c> 元素。
     /// </summary>
-    /// <param name="xmlStream">UTF-8 encoded XML stream</param>
-    /// <param name="token">Cancellation token</param>
-    /// <returns><see cref="ICard"/> enumerable</returns>
+    /// <param name="xmlStream"> UTF-8 编码的 XML 流。 </param>
+    /// <param name="token"> 取消令牌。 </param>
+    /// <returns> 一个表示异步解析操作的任务。任务的结果包含一个可用于枚举 <see cref="ICard"/> 成员的 <see cref="T:System.Collections.Generic.IEnumerable`1"/>。 </returns>
     public static async Task<IEnumerable<ICard>> DeserializeAsync(Stream xmlStream, CancellationToken token = default)
     {
         using XmlReader xmlReader = XmlReader.Create(xmlStream, new XmlReaderSettings
@@ -121,38 +118,35 @@ public static async Task<IEnumerable<ICard>> DeserializeAsync(Stream xmlStream,
     #region Sync
 
     /// <summary>
-    ///     Deserialize a Card Message XML markup file to a <see cref="ICard"/> list.
-    ///     One XML markup file has one card-message element, which can
-    ///     contain multiple card elements.
+    ///     将卡片消息 XML 标记文件反序列化为 <see cref="ICard"/> 列表，每个 XML 文件包含一个 <c>card-message</c>
+    ///     元素，可以包含多个 <c>card</c> 元素。
     /// </summary>
-    /// <param name="file">UTF-8 encoded XML file</param>
-    /// <returns><see cref="ICard"/> enumerable</returns>
+    /// <param name="file"> UTF-8 编码的 XML 文件 </param>
+    /// <returns> 一个可用于枚举 <see cref="ICard"/> 成员的 <see cref="T:System.Collections.Generic.IEnumerable`1"/>。 </returns>
     public static IEnumerable<ICard> Deserialize(FileInfo file)
     {
         using FileStream fs = file.OpenRead();
         return Deserialize(fs);
     }
 
     /// <summary>
-    ///     Deserialize a Card Message XML markup text to a <see cref="ICard"/> list.
-    ///     One XML markup file has one card-message element, which can
-    ///     contain multiple card elements.
+    ///     将卡片消息 XML 标记文本反序列化为 <see cref="ICard"/> 列表，每个 XML 文件包含一个 <c>card-message</c>
+    ///     元素，可以包含多个 <c>card</c> 元素。
     /// </summary>
-    /// <param name="xmlText">UTF-8 encoded XML text</param>
-    /// <returns><see cref="ICard"/> enumerable</returns>
+    /// <param name="xmlText"> UTF-8 编码的 XML 文本。 </param>
+    /// <returns> 一个可用于枚举 <see cref="ICard"/> 成员的 <see cref="T:System.Collections.Generic.IEnumerable`1"/>。 </returns>
     public static IEnumerable<ICard> Deserialize(string xmlText)
     {
         using MemoryStream xmlStream = new(Encoding.UTF8.GetBytes(xmlText));
         return Deserialize(xmlStream);
     }
 
     /// <summary>
-    ///     Deserialize a Card Message XML markup file to a <see cref="ICard"/> list.
-    ///     One XML markup file has one card-message element, which can
-    ///     contain multiple card elements.
+    ///     将卡片消息 XML 标记文本流反序列化为 <see cref="ICard"/> 列表，每个 XML 文件包含一个 <c>card-message</c>
+    ///     元素，可以包含多个 <c>card</c> 元素。
     /// </summary>
-    /// <param name="xmlStream">UTF-8 encoded XML stream</param>
-    /// <returns><see cref="ICard"/> enumerable</returns>
+    /// <param name="xmlStream"> UTF-8 编码的 XML 流。 </param>
+    /// <returns> 一个可用于枚举 <see cref="ICard"/> 成员的 <see cref="T:System.Collections.Generic.IEnumerable`1"/>。 </returns>
     public static IEnumerable<ICard> Deserialize(Stream xmlStream)
     {
         using XmlReader xmlReader = XmlReader.Create(xmlStream, new XmlReaderSettings
@@ -220,11 +214,14 @@ public static IEnumerable<ICard> Deserialize(Stream xmlStream)
     #nullable enable
 
     /// <summary>
-    ///     Try to deserialize a Card Message XML markup file to a <see cref="ICard"/> list.
+    ///     尝试将卡片消息 XML 标记文件反序列化为 <see cref="ICard"/> 列表。
     /// </summary>
-    /// <param name="file">UTF-8 encoded XML file</param>
-    /// <param name="cards"><see cref="ICard"/> enumerable, will be null if return value is false</param>
-    /// <returns>True if deserialization is successful, otherwise false</returns>
+    /// <param name="file"> UTF-8 编码的 XML 文件。 </param>
+    /// <param name="cards">
+    ///     如果反序列化操作成功，则为一个可用于枚举 <see cref="ICard"/> 成员的
+    ///     <see cref="T:System.Collections.Generic.IEnumerable`1"/>；否则为 <c>null</c>。
+    /// </param>
+    /// <returns> 如果反序列化操作成功，则为 <c>true</c>；否则为 <c>false</c>。 </returns>
     public static bool TryDeserialize(FileInfo file, [NotNullWhen(true)] out IEnumerable<ICard>? cards)
     {
         try
@@ -240,11 +237,14 @@ public static bool TryDeserialize(FileInfo file, [NotNullWhen(true)] out IEnumer
     }
 
     /// <summary>
-    ///     Try to deserialize a Card Message XML markup file to a <see cref="ICard"/> list.
+    ///     尝试将卡片消息 XML 标记文本反序列化为 <see cref="ICard"/> 列表。
     /// </summary>
-    /// <param name="xmlText">UTF-8 encoded XML text</param>
-    /// <param name="cards"><see cref="ICard"/> enumerable, will be null if return value is false</param>
-    /// <returns>True if deserialization is successful, otherwise false</returns>
+    /// <param name="xmlText"> UTF-8 编码的 XML 文本。 </param>
+    /// <param name="cards">
+    ///     如果反序列化操作成功，则为一个可用于枚举 <see cref="ICard"/> 成员的
+    ///     <see cref="T:System.Collections.Generic.IEnumerable`1"/>；否则为 <c>null</c>。
+    /// </param>
+    /// <returns> 如果反序列化操作成功，则为 <c>true</c>；否则为 <c>false</c>。 </returns>
     public static bool TryDeserialize(string xmlText, [NotNullWhen(true)] out IEnumerable<ICard>? cards)
     {
         try
@@ -260,11 +260,14 @@ public static bool TryDeserialize(string xmlText, [NotNullWhen(true)] out IEnume
     }
 
     /// <summary>
-    ///     Try to deserialize a Card Message XML markup file to a <see cref="ICard"/> list.
+    ///     尝试将卡片消息 XML 标记文本流反序列化为 <see cref="ICard"/> 列表。
     /// </summary>
-    /// <param name="xmlStream">UTF-8 encoded XML stream</param>
-    /// <param name="cards"><see cref="ICard"/> enumerable, will be null if return value is false</param>
-    /// <returns>True if deserialization is successful, otherwise false</returns>
+    /// <param name="xmlStream"> UTF-8 编码的 XML 文本流。 </param>
+    /// <param name="cards">
+    ///     如果反序列化操作成功，则为一个可用于枚举 <see cref="ICard"/> 成员的
+    ///     <see cref="T:System.Collections.Generic.IEnumerable`1"/>；否则为 <c>null</c>。
+    /// </param>
+    /// <returns> 如果反序列化操作成功，则为 <c>true</c>；否则为 <c>false</c>。 </returns>
     public static bool TryDeserialize(Stream xmlStream, [NotNullWhen(true)] out IEnumerable<ICard>? cards)
     {
         try

diff --git a/src/Kook.Net.Commands/Attributes/AliasAttribute.cs b/src/Kook.Net.Commands/Attributes/AliasAttribute.cs
@@ -1,35 +1,32 @@
 namespace Kook.Commands;
 
 /// <summary>
-///     Marks the aliases for a command.
+///     为命令指定别名。
 /// </summary>
 /// <remarks>
-///     This attribute allows a command to have one or multiple aliases. In other words, the base command can have
-///     multiple aliases when triggering the command itself, giving the end-user more freedom of choices when giving
-///     hot-words to trigger the desired command. See the example for a better illustration.
+///     此特性允许命令具有一个或多个别名，在指定命令的基本名称的同时，还可以指定多个别名，以便用户可以使用多个熟悉的词汇来触发相同的命令。
 /// </remarks>
 /// <example>
-///     In the following example, the command can be triggered with the base name, "stats", or either "stat" or
-///     "info".
+///     以下示例中，要调用此命令，除了可以使用基本名称“stats”，还使用“stat”或“info”。
 ///     <code language="cs">
 ///     [Command("stats")]
 ///     [Alias("stat", "info")]
-///     public <c>async</c> Task GetStatsAsync(IUser user)
+///     public async Task GetStatsAsync(IUser user)
 ///     {
-///         // ...pull stats
+///         await ReplyTextAsync($"{user.Username} has 1000 score!");
 ///     }
 ///     </code>
 /// </example>
 [AttributeUsage(AttributeTargets.Class | AttributeTargets.Method)]
 public class AliasAttribute : Attribute
 {
     /// <summary>
-    ///     Gets the aliases which have been defined for the command.
+    ///     获取为命令定义的别名。
     /// </summary>
     public string[] Aliases { get; }
 
     /// <summary>
-    ///     Creates a new <see cref="AliasAttribute" /> with the given aliases.
+    ///     初始化一个 <see cref="AliasAttribute"/> 类的新实例。
     /// </summary>
     public AliasAttribute(params string[] aliases)
     {

diff --git a/src/Kook.Net.Commands/Attributes/CommandAttribute.cs b/src/Kook.Net.Commands/Attributes/CommandAttribute.cs
@@ -1,73 +1,79 @@
 namespace Kook.Commands;
 
 /// <summary>
-///     Marks the execution information for a command.
+///     为命令标记执行信息。
 /// </summary>
 [AttributeUsage(AttributeTargets.Method)]
 public class CommandAttribute : Attribute
 {
     /// <summary>
-    ///     Gets the text that has been set to be recognized as a command.
+    ///     获取此命令的基本名称。
     /// </summary>
+    /// <remarks>
+    ///     <see cref="T:Kook.Commands.NameAttribute"/> 特性重写此属性的值。
+    /// </remarks>
     public string? Text { get; }
 
     /// <summary>
-    ///     Specifies the <see cref="RunMode" /> of the command. This affects how the command is executed.
+    ///     获取或设置命令的运行模式。
     /// </summary>
+    /// <seealso cref="P:Kook.Commands.CommandServiceConfig.DefaultRunMode"/>
     public RunMode RunMode { get; set; } = RunMode.Default;
 
     /// <summary>
-    ///     Indicates whether extra arguments should be ignored for this command.
+    ///     获取或设置是否忽略此命令的额外参数。
     /// </summary>
+    /// <seealso cref="P:Kook.Commands.CommandServiceConfig.IgnoreExtraArgs"/>
     public bool? IgnoreExtraArgs { get; }
 
     /// <summary>
-    ///     Attaches a summary to your command.
+    ///     获取或设置命令的摘要。
     /// </summary>
     /// <remarks>
-    ///     <see cref="Summary"/> overrides the value of this property if present.
+    ///     <see cref="T:Kook.Commands.SummaryAttribute"/> 特性重写此属性的值。
     /// </remarks>
     public string? Summary { get; set; }
 
     /// <summary>
-    ///     Marks the aliases for a command.
+    ///     获取或设置命令的别名。
     /// </summary>
     /// <remarks>
-    ///     <see cref="AliasAttribute"/> extends the base value of this if present.
+    ///     <see cref="T:Kook.Commands.AliasAttribute"/> 特性的值会与此属性的值合并。
     /// </remarks>
     public string?[]? Aliases { get; set; }
 
     /// <summary>
-    ///     Attaches remarks to your commands.
+    ///     获取或设置命令的备注。
     /// </summary>
     /// <remarks>
-    ///     <see cref="RemainderAttribute"/> overrides the value of this property if present.
+    ///     <see cref="T:Kook.Commands.RemainderAttribute"/> 特性重写此属性的值。
     /// </remarks>
     public string? Remarks { get; set; }
 
-    /// <inheritdoc />
+    /// <summary>
+    ///     初始化一个 <see cref="CommandAttribute"/> 类的新实例。
+    /// </summary>
     public CommandAttribute()
     {
     }
 
     /// <summary>
-    ///     Initializes a new <see cref="CommandAttribute" /> attribute with the specified name.
+    ///     初始化一个 <see cref="CommandAttribute"/> 类的新实例。
     /// </summary>
-    /// <param name="text">The name of the command.</param>
+    /// <param name="text"> 命令的基本名称。 </param>
     public CommandAttribute(string text)
     {
         Text = text;
     }
 
     /// <summary>
-    ///     Initializes a new <see cref="CommandAttribute" /> attribute with the specified name
-    ///     and mode of whether to ignore extra arguments.
+    ///     初始化一个 <see cref="CommandAttribute"/> 类的新实例。
     /// </summary>
-    /// <param name="text"> The name of the command. </param>
-    /// <param name="ignoreExtraArgs"> Whether to ignore extra arguments. </param>
-    /// <param name="summary"> The summary of the command. </param>
-    /// <param name="aliases"> The aliases of the command. </param>
-    /// <param name="remarks"> The remarks of the command. </param>
+    /// <param name="text"> 命令的基本名称。 </param>
+    /// <param name="ignoreExtraArgs"> 是否忽略此命令的额外参数。 </param>
+    /// <param name="summary"> 命令的摘要。 </param>
+    /// <param name="aliases"> 命令的别名。 </param>
+    /// <param name="remarks"> 命令的备注。 </param>
     public CommandAttribute(string text, bool ignoreExtraArgs,
         string? summary = null, string?[]? aliases = null, string? remarks = null)
     {