From f558537465d60d844c7d6201fef9b7bd08d16fcb Mon Sep 17 00:00:00 2001
From: Him188 <Him188@mamoe.net>
Date: Sun, 24 May 2020 14:22:17 +0800
Subject: [PATCH] Fix KDoc, close #337

---
 .../net.mamoe.mirai/message/data/Message.kt   | 44 +++++++------------
 .../message/data/MessageChain.kt              |  7 ++-
 2 files changed, 20 insertions(+), 31 deletions(-)

diff --git a/mirai-core/src/commonMain/kotlin/net.mamoe.mirai/message/data/Message.kt b/mirai-core/src/commonMain/kotlin/net.mamoe.mirai/message/data/Message.kt
index 7b2ba67e0..ddb5e707b 100644
--- a/mirai-core/src/commonMain/kotlin/net.mamoe.mirai/message/data/Message.kt
+++ b/mirai-core/src/commonMain/kotlin/net.mamoe.mirai/message/data/Message.kt
@@ -43,22 +43,14 @@ import kotlin.jvm.JvmSynthetic
  * #### 在 Kotlin 使用 [Message]:
  * 这与使用 [String] 的使用非常类似.
  *
- * 比较 [SingleMessage] 与 [String]:
- *  `if(message.contentToString() == "你好") friend.sendMessage(event)`
+ * - 比较 [SingleMessage] 与 [String]:
+ *  `if(message.content == "你好") friend.sendMessage(event)`
  *
- * 连接 [Message] 与 [Message], [String], (使用操作符 [Message.plus]):
+ * - 连接 [Message] 与 [Message], [String], (使用操作符 [Message.plus]):
  *  ```
- *      text = PlainText("Hello ")
- *      qq.sendMessage(text + "world")
+ * val text = PlainText("Hello ") + PlainText("world") + "!"
+ * friend.sendMessage(text)
  *  ```
- *
- * `Message1 + Message2 + Message3`, 类似 [String] 的连接:
- * ```
- *   +----------+   plus  +----------+   plus  +----------+
- *   | Message1 | <------ | Message2 | <------ | Message3 |
- *   +----------+         +----------+         +----------+
- * ```
- *
  * 但注意: 不能 `String + Message`. 只能 `Message + String`
  *
  * #### 实现规范
@@ -76,7 +68,7 @@ import kotlin.jvm.JvmSynthetic
  * @see AtAll 全体成员的引用
  * @see QuoteReply 一条消息的引用
  * @see RichMessage 富文本消息, 如 [XML 和 JSON][ServiceMessage], [小程序][LightApp]
- * @see HummerMessage 一些特殊的消息, 如 [闪照][FlashImage], [戳一戳][PokeMessage]
+ * @see HummerMessage 一些特殊的消息, 如 [闪照][FlashImage], [戳一戳][PokeMessage], [VIP表情][VipFace]
  * @see CustomMessage 自定义消息类型
  *
  * @see MessageChain 消息链(即 `List<Message>`)
@@ -114,10 +106,6 @@ interface Message { // must be interface. Don't consider any changes.
      * val b = PlainText("world!")
      * val c: MessageChain = a + b
      * println(c) // "Hello world!"
-     *
-     * val d = PlainText("world!")
-     * val e = c + d; // PlainText + CombinedMessage
-     * println(c) // "Hello world!"
      * ```
      *
      * @see plus `+` 操作符重载
@@ -131,11 +119,12 @@ interface Message { // must be interface. Don't consider any changes.
      * 在使用消息相关 DSL 和扩展时, 一些内容比较的实现均使用的是 [contentToString] 而不是 [toString]
      *
      * 各个 [SingleMessage] 的转换示例:
-     * [PlainText]: "Hello"
-     * [GroupImage]: "[mirai:image:{01E9451B-70ED-EAE3-B37C-101F1EEBF5B5}.mirai]"
-     * [FriendImage]: "[mirai:image:/f8f1ab55-bf8e-4236-b55e-955848d7069f]"
-     * [PokeMessage]: "[mirai:poke:1,-1]"
-     * [MessageChain]: 无间隔地连接所有元素 (`joinToString("")`)
+     * - [PlainText]: "Hello"
+     * - [GroupImage]: "[mirai:image:{01E9451B-70ED-EAE3-B37C-101F1EEBF5B5}.mirai]"
+     * - [FriendImage]: "[mirai:image:/f8f1ab55-bf8e-4236-b55e-955848d7069f]"
+     * - [PokeMessage]: "[mirai:poke:1,-1]"
+     * - [MessageChain]: 无间隔地连接所有元素 (`joinToString("")`)
+     * - ...
      *
      * @see contentToString 转为最接近官方格式的字符串
      */
@@ -147,10 +136,11 @@ interface Message { // must be interface. Don't consider any changes.
      * 在使用消息相关 DSL 和扩展时, 一些内容比较的实现均使用 [contentToString] 而不是 [toString]
      *
      * 各个 [SingleMessage] 的转换示例:
-     * [PlainText]: "Hello"
-     * [Image]: "\[图片\]"
-     * [PokeMessage]: "\[戳一戳\]"
-     * [MessageChain]: 无间隔地连接所有元素 (`joinToString("", transformer=Message::contentToString)`)
+     * - [PlainText]: "Hello"
+     * - [Image]: "\[图片\]"
+     * - [PokeMessage]: "\[戳一戳\]"
+     * - [MessageChain]: 无间隔地连接所有元素 (`joinToString("", transformer=Message::contentToString)`)
+     * - ...
      *
      * @see toString 得到包含 mirai 消息元素代码的, 易读的字符串
      */
diff --git a/mirai-core/src/commonMain/kotlin/net.mamoe.mirai/message/data/MessageChain.kt b/mirai-core/src/commonMain/kotlin/net.mamoe.mirai/message/data/MessageChain.kt
index d19a181fe..8710f03a6 100644
--- a/mirai-core/src/commonMain/kotlin/net.mamoe.mirai/message/data/MessageChain.kt
+++ b/mirai-core/src/commonMain/kotlin/net.mamoe.mirai/message/data/MessageChain.kt
@@ -14,6 +14,7 @@
 package net.mamoe.mirai.message.data
 
 import net.mamoe.mirai.JavaFriendlyAPI
+import net.mamoe.mirai.message.MessageEvent
 import net.mamoe.mirai.utils.PlannedRemoval
 import kotlin.js.JsName
 import kotlin.jvm.JvmMultifileClass
@@ -25,20 +26,18 @@ import kotlin.reflect.KProperty
 /**
  * 消息链. 空的实现为 [EmptyMessageChain]
  *
- * 在发送消息时必须构造一个消息链, 可通过一系列扩展函数 [asMessageChain] 转换.
- *
  * 要获取更多消息相关的信息, 查看 [Message]
  *
  * ### 构造消息链
  * - [buildMessageChain]: 使用构建器
  * - [Message.plus]: 将两个消息相连成为一个消息链
- * - [asMessageChain] 将 [Iterable], 等类型消息
+ * - [asMessageChain] 将 [Iterable], [Array] 等类型消息转换为 [MessageChain]
  * - [messageChainOf] 类似 [listOf], 将多个 [Message] 构造为 [MessageChain]
  *
  * @see get 获取消息链中一个类型的元素, 不存在时返回 `null`
  * @see getOrFail 获取消息链中一个类型的元素, 不存在时抛出异常 [NoSuchElementException]
  * @see quote 引用这条消息
- * @see recall 撤回这条消息 (
+ * @see recall 撤回这条消息 (仅限来自 [MessageEvent] 的消息)
  *
  * @see buildMessageChain 构造一个 [MessageChain]
  * @see asMessageChain 将单个 [Message] 转换为 [MessageChain]