From 98efbfeead5248829903e42a1b1cbda6d75e9bc5 Mon Sep 17 00:00:00 2001
From: Him188 <Him188@mamoe.net>
Date: Mon, 11 Jan 2021 22:36:48 +0800
Subject: [PATCH] Update docs

---
 docs/Messages.md                              | 10 ++++---
 .../commonMain/kotlin/message/action/Nudge.kt |  5 +++-
 .../kotlin/message/data/PokeMessage.kt        |  3 +++
 .../kotlin/message/data/QuoteReply.kt         | 27 +++++++++----------
 4 files changed, 26 insertions(+), 19 deletions(-)

diff --git a/docs/Messages.md b/docs/Messages.md
index e25737224..7f38276cd 100644
--- a/docs/Messages.md
+++ b/docs/Messages.md
@@ -42,11 +42,11 @@ Mirai 支持富文本消息。各类型消息元素如下文表格所示。
 [`At`]: ../mirai-core-api/src/commonMain/kotlin/message/data/At.kt
 [`AtAll`]: ../mirai-core-api/src/commonMain/kotlin/message/data/AtAll.kt
 [`Face`]: ../mirai-core-api/src/commonMain/kotlin/message/data/Face.kt
-[`PokeMessage`]: ../mirai-core-api/src/commonMain/kotlin/message/data/HummerMessage.kt
-[`VipFace`]: ../mirai-core-api/src/commonMain/kotlin/message/data/HummerMessage.kt
+[`PokeMessage`]: ../mirai-core-api/src/commonMain/kotlin/message/data/PokeMessage.kt
+[`VipFace`]: ../mirai-core-api/src/commonMain/kotlin/message/data/VipFace.kt
 [`Image`]: ../mirai-core-api/src/commonMain/kotlin/message/data/Image.kt
-[`FlashImage`]: ../mirai-core-api/src/commonMain/kotlin/message/data/HummerMessage.kt
-[`MarketFace`]: ../mirai-core-api/src/commonMain/kotlin/message/data/HummerMessage.kt
+[`FlashImage`]: ../mirai-core-api/src/commonMain/kotlin/message/data/FlashImage.kt
+[`MarketFace`]: ../mirai-core-api/src/commonMain/kotlin/message/data/MarketFace.kt
 
 [`MessageSource`]: ../mirai-core-api/src/commonMain/kotlin/message/data/MessageSource.kt
 [`QuoteReply`]: ../mirai-core-api/src/commonMain/kotlin/message/data/QuoteReply.kt
@@ -75,6 +75,8 @@ Mirai 支持富文本消息。各类型消息元素如下文表格所示。
 
 ***注意：内容会首先被转义，详见 [转义规则](#转义规则)***
 
+**请打开相关消息类型的源码查看用法。**
+
 > 回到 [目录](#目录)
 
 ## Mirai 码
diff --git a/mirai-core-api/src/commonMain/kotlin/message/action/Nudge.kt b/mirai-core-api/src/commonMain/kotlin/message/action/Nudge.kt
index b37d29fc5..10a3fd627 100644
--- a/mirai-core-api/src/commonMain/kotlin/message/action/Nudge.kt
+++ b/mirai-core-api/src/commonMain/kotlin/message/action/Nudge.kt
@@ -13,11 +13,14 @@ import net.mamoe.mirai.Bot
 import net.mamoe.mirai.Mirai
 import net.mamoe.mirai.contact.*
 import net.mamoe.mirai.event.events.NudgeEvent
+import net.mamoe.mirai.message.data.PokeMessage
 import net.mamoe.mirai.utils.BotConfiguration
 import net.mamoe.mirai.utils.BotConfiguration.MiraiProtocol
 
 /**
- * 一个 "戳一戳" 消息.
+ * 一个 "戳一戳" 动作.
+ *
+ * 备注: 这类似微信拍一拍. 消息对话框中显示的 "一个手指" 的戳一戳是 [PokeMessage]
  *
  * 仅在手机 QQ 8.4.0 左右版本才受支持. 其他客户端会忽略这些消息.
  *
diff --git a/mirai-core-api/src/commonMain/kotlin/message/data/PokeMessage.kt b/mirai-core-api/src/commonMain/kotlin/message/data/PokeMessage.kt
index 71dc02e7f..7b629d067 100644
--- a/mirai-core-api/src/commonMain/kotlin/message/data/PokeMessage.kt
+++ b/mirai-core-api/src/commonMain/kotlin/message/data/PokeMessage.kt
@@ -11,6 +11,7 @@ package net.mamoe.mirai.message.data
 
 import kotlinx.serialization.SerialName
 import kotlinx.serialization.Serializable
+import net.mamoe.mirai.message.action.Nudge
 import net.mamoe.mirai.message.code.CodableMessage
 import net.mamoe.mirai.message.code.internal.appendStringAsMiraiCode
 import net.mamoe.mirai.utils.MiraiExperimentalApi
@@ -20,6 +21,8 @@ import net.mamoe.mirai.utils.castOrNull
 /**
  * 戳一戳. 可以发送给好友或群.
  *
+ * 备注: 这是消息对话框中显示的 "一个手指" 的戳一戳. 类似微信拍一拍的是 [Nudge].
+ *
  * ## mirai 码支持
  * 格式: &#91;mirai:poke:*[name]*,*[pokeType]*,*[id]*&#93;
  *
diff --git a/mirai-core-api/src/commonMain/kotlin/message/data/QuoteReply.kt b/mirai-core-api/src/commonMain/kotlin/message/data/QuoteReply.kt
index cfbc5abdf..38fa77f3f 100644
--- a/mirai-core-api/src/commonMain/kotlin/message/data/QuoteReply.kt
+++ b/mirai-core-api/src/commonMain/kotlin/message/data/QuoteReply.kt
@@ -15,27 +15,24 @@ package net.mamoe.mirai.message.data
 
 import kotlinx.serialization.SerialName
 import kotlinx.serialization.Serializable
+import net.mamoe.mirai.message.data.MessageSource.Key.quote
 import net.mamoe.mirai.message.data.MessageSource.Key.recall
 import net.mamoe.mirai.utils.safeCast
 
 
 /**
- * 引用回复.
+ * 引用回复. [QuoteReply] 被作为 [MessageMetadata], 因为它不包含实际的消息内容.
  *
  * 支持引用任何一条消息发送给任何人.
  *
- * ### 元数据
- * [QuoteReply] 被作为 [MessageMetadata], 因为它不包含实际的消息内容, 且只能在消息中单独存在.
- *
- * ### [source] 的类型:
- * - 在发送引用回复时, [source] 类型为 [OnlineMessageSource] 或 [OfflineMessageSource]
- * - 在接收引用回复时, [source] 类型一定为 [OfflineMessageSource]
- *
- * ### 原消息内容
  * 引用回复的原消息内容完全由 [source] 中 [MessageSource.originalMessage] 控制, 客户端不会自行寻找原消息.
+ * 可通过 [MessageSource.copyAmend] 修改引用的消息内容.
  *
- * ### 客户端内跳转
- * 客户端在跳转原消息时, 会通过 [MessageSource.ids] 等 metadata
+ * 客户端通过 [MessageSource.ids] 等数据定位源消息, 在修改时使用 [MessageSourceBuilder.metadata] 可以修改定位结果.
+ *
+ * ## 创建引用回复
+ * - 直接构造 [QuoteReply]: `new QuoteReply(source)`
+ * - 在 Kotlin 使用扩展 [MessageSource.quote]
  *
  * @see MessageSource 获取有关消息源的更多信息
  */
@@ -44,9 +41,7 @@ import net.mamoe.mirai.utils.safeCast
 public data class QuoteReply(
     public val source: MessageSource
 ) : Message, MessageMetadata, ConstrainSingle {
-    public companion object Key : AbstractMessageKey<QuoteReply>({ it.safeCast() }) {
-        public const val SERIAL_NAME: String = "QuoteReply"
-    }
+    public constructor(sourceMessage: MessageChain) : this(sourceMessage.getOrFail(MessageSource))
 
     public override val key: MessageKey<QuoteReply> get() = Key
 
@@ -55,6 +50,10 @@ public data class QuoteReply(
 
     public override fun equals(other: Any?): Boolean = other is QuoteReply && other.source == this.source
     public override fun hashCode(): Int = source.hashCode()
+
+    public companion object Key : AbstractMessageKey<QuoteReply>({ it.safeCast() }) {
+        public const val SERIAL_NAME: String = "QuoteReply"
+    }
 }
 
 /**