Update docs for messages (#1142)

* Update docs for messages * Update docs for messages * Update docs for messages * Update docs for messages * Update docs/Messages.md Co-authored-by: Karlatemp <karlatemp@vip.qq.com> * Update mirai-core-api/src/commonMain/kotlin/message/data/Message.kt Co-authored-by: Karlatemp <karlatemp@vip.qq.com> * Update docs for messages * Update docs for messages * Revert inappropriate changes * Fix doc Co-authored-by: Karlatemp <karlatemp@vip.qq.com>
mamoe · Apr 3, 2021 · cccdb3c · cccdb3c
1 parent ea1f43b
commit cccdb3c
Show file tree

Hide file tree

Showing 32 changed files with 418 additions and 165 deletions.
diff --git a/docs/Messages.md b/docs/Messages.md
@@ -21,7 +21,8 @@
 
 [![](https://mermaid.ink/img/eyJjb2RlIjoiY2xhc3NEaWFncmFtXG5cbmNsYXNzIE1lc3NhZ2VDaGFpblxuTWVzc2FnZUNoYWluIDogTGlzdH5TaW5nbGVNZXNzYWdlflxuXG5NZXNzYWdlPHwtLU1lc3NhZ2VDaGFpblxuTWVzc2FnZTx8LS1TaW5nbGVNZXNzYWdlXG5cbk1lc3NhZ2VDaGFpbiBvLS0gU2luZ2xlTWVzc2FnZVxuXG5TaW5nbGVNZXNzYWdlPHwtLU1lc3NhZ2VDb250ZW50XG5TaW5nbGVNZXNzYWdlPHwtLU1lc3NhZ2VNZXRhZGF0YVxuXG4iLCJtZXJtYWlkIjp7InRoZW1lIjoiZGVmYXVsdCJ9LCJ1cGRhdGVFZGl0b3IiOmZhbHNlfQ)](https://mermaid-js.github.io/mermaid-live-editor/#/edit/eyJjb2RlIjoiY2xhc3NEaWFncmFtXG5cbmNsYXNzIE1lc3NhZ2VDaGFpblxuTWVzc2FnZUNoYWluIDogTGlzdH5TaW5nbGVNZXNzYWdlflxuXG5NZXNzYWdlPHwtLU1lc3NhZ2VDaGFpblxuTWVzc2FnZTx8LS1TaW5nbGVNZXNzYWdlXG5cbk1lc3NhZ2VDaGFpbiBvLS0gU2luZ2xlTWVzc2FnZVxuXG5TaW5nbGVNZXNzYWdlPHwtLU1lc3NhZ2VDb250ZW50XG5TaW5nbGVNZXNzYWdlPHwtLU1lc3NhZ2VNZXRhZGF0YVxuXG4iLCJtZXJtYWlkIjp7InRoZW1lIjoiZGVmYXVsdCJ9LCJ1cGRhdGVFZGl0b3IiOmZhbHNlfQ)
 
-`SingleMessage` 表示单个消息元素，`MessageChain`（消息链） 是 `List<SingleMessage>`。主动发送的消息和从服务器接收消息都是 `MessageChain`。
+`SingleMessage` 表示单个消息元素。  
+`MessageChain`（消息链） 是 `List<SingleMessage>`。主动发送的消息和从服务器接收消息都是 `MessageChain`。
 
 
 > 回到 [目录](#目录)
@@ -53,6 +54,8 @@ Mirai 支持富文本消息。
 
 ## 消息元素
 
+Mirai 支持多种消息类型。
+
 消息拥有三种转换到字符串的表示方式。
 
 | 方法                      | 解释                                                                                          |
@@ -109,6 +112,8 @@ Mirai 支持富文本消息。
 |     [`FileMessage`]      | 文件消息              | `[文件]文件名称`          |          2.5          |
 
 
+> *(1)*: [`ForwardMessage`] 在 2.0 支持发送, 在 2.3 支持接收
+
 
 
 | [`MessageMetadata`] 类型 | 解释         | 最低支持的版本 |
@@ -119,9 +124,11 @@ Mirai 支持富文本消息。
 |  [`RichMessageOrigin`]  | 富文本消息源   |     2.3     |
 
 
-**请打开相关消息类型的源码查看用法。**
+### 用法
 
-> *(1)*: [`ForwardMessage`] 在 2.0 支持发送, 在 2.3 支持接收
+只需要得到各种类型 `Message` 的实例就可以使用，可以直接发送（`Contact.sendMessage`）也可以连接到消息链中（`Message.plus`）。
+
+可在上文表格中找到需要的类型并在源码内文档获取更多实践上的帮助。
 
 > 回到 [目录](#目录)
 
@@ -224,6 +231,7 @@ MessageChain chain = new MessageChainBuilder()
     .build();
 ```
 
+该示例中 `+` 是位于 `MessageChainBuilder` 的 `Message.unaryPlus` 扩展。使用 `+` 和使用 `add` 是相等的。
 
 ### 作为字符串处理消息
 

diff --git a/mirai-core-api/src/commonMain/kotlin/IMirai.kt b/mirai-core-api/src/commonMain/kotlin/IMirai.kt
@@ -68,7 +68,13 @@ public interface IMirai : LowLevelApiAccessor {
     public var Http: HttpClient
 
     /**
-     * 获取 uin
+     * 获取 uin.
+     *
+     * - 用户的 uin 就是用户的 ID (QQ 号码, [User.id]).
+     * - 部分旧群的 uin 需要通过算法计算 [calculateGroupUinByGroupCode]. 新群的 uin 与在客户端能看到的群号码 ([Group.id]) 相同.
+     *
+     * 除了一些偏底层的 API 如 [MessageSourceBuilder.id] 外, mirai 的所有其他 API 都使用在客户端能看到的用户 QQ 号码和群号码 ([Contact.id]). 并会在需要的时候进行合适转换.
+     * 若需要使用 uin, 在特定方法的文档中会标出.
      */
     public fun getUin(contactOrBot: ContactOrBot): Long {
         return if (contactOrBot is Group)
@@ -78,6 +84,7 @@ public interface IMirai : LowLevelApiAccessor {
 
     /**
      * 使用 groupCode 计算 groupUin. 这两个值仅在 mirai 内部协议区分, 一般人使用时无需在意.
+     * @see getUin
      */
     public fun calculateGroupUinByGroupCode(groupCode: Long): Long {
         var left: Long = groupCode / 1000000L
@@ -95,6 +102,7 @@ public interface IMirai : LowLevelApiAccessor {
 
     /**
      * 使用 groupUin 计算 groupCode. 这两个值仅在 mirai 内部协议区分, 一般人使用时无需在意.
+     * @see getUin
      */
     public fun calculateGroupCodeByGroupUin(groupUin: Long): Long {
         var left: Long = groupUin / 1000000L

diff --git a/mirai-core-api/src/commonMain/kotlin/contact/NormalMember.kt b/mirai-core-api/src/commonMain/kotlin/contact/NormalMember.kt
@@ -142,7 +142,7 @@ public interface NormalMember : Member {
 /**
  * 获取非空群名片或昵称.
  * @return 当 [User] 为 [NormalMember] 时返回 [Member.nameCardOrNick], 否则返回 [Member.nick]
- */
+ */ // Java: NormalMemberKt.getNameCardOrNick(user)
 public val User.nameCardOrNick: String
     get() = when (this) {
         is NormalMember -> this.nameCardOrNick

diff --git a/mirai-core-api/src/commonMain/kotlin/event/events/MessageEvent.kt b/mirai-core-api/src/commonMain/kotlin/event/events/MessageEvent.kt
@@ -16,8 +16,6 @@ import net.mamoe.mirai.Bot
 import net.mamoe.mirai.contact.*
 import net.mamoe.mirai.event.AbstractEvent
 import net.mamoe.mirai.event.Event
-import net.mamoe.mirai.event.EventChannel
-import net.mamoe.mirai.event.subscribe
 import net.mamoe.mirai.internal.network.Packet
 import net.mamoe.mirai.message.data.MessageChain
 import net.mamoe.mirai.message.data.MessageSource
@@ -28,9 +26,7 @@ import net.mamoe.mirai.utils.MiraiInternalApi
 
 
 /**
- * 一个 (收到的) 消息事件.
- *
- * 它是一个 [BotEvent], 因此可以被 [监听][EventChannel.subscribe]
+ * 一个消息事件.
  *
  * @see isContextIdenticalWith 判断语境相同
  */
@@ -43,13 +39,13 @@ public interface MessageEvent : Event, Packet, BotPassiveEvent { // TODO: 2021/1
     /**
      * 消息事件主体.
      *
-     * - 对于好友消息, 这个属性为 [Friend] 的实例, 与 [sender] 引用相同;
-     * - 对于临时会话消息, 这个属性为 [Member] 的实例, 与 [sender] 引用相同;
-     * - 对于陌生人消息, 这个属性为 [Stranger] 的实例, 与 [sender] 引用相同
-     * - 对于群消息, 这个属性为 [Group] 的实例, 与 [GroupMessageEvent.group] 引用相同
-     * - 对于其他客户端消息, 这个属性为 [OtherClient] 的实例, 与 [OtherClientMessageEvent.client] 引用相同
+     * - 对于私聊会话, 这个属性与 [sender] 相同;
+     * - 对于群消息, 这个属性为 [Group] 的实例, 与 [GroupMessageEvent.group] 相同.
+     *
+     * 如果在 [GroupMessageEvent] 对 [sender] 发送消息, 将会通过私聊发送给群员, 而不会发送在群内.
+     * 使用 [subject] 作为消息目标则可以确保消息发送到用户所在的场景.
      *
-     * 在回复消息时, 可通过 [subject] 作为回复对象
+     * 在回复消息时, 可通过 [subject] 作为回复对象.
      */
     public val subject: Contact
 
@@ -61,23 +57,24 @@ public interface MessageEvent : Event, Packet, BotPassiveEvent { // TODO: 2021/1
     public val sender: User
 
     /**
-     * 发送人名称
+     * 发送人名称. 由群员发送时为群员名片, 由好友发送时为好友昵称. 使用 [User.nameCardOrNick] 也能得到相同的结果.
      */
     public val senderName: String
 
     /**
      * 消息内容.
      *
-     * 第一个元素一定为 [MessageSource], 存储此消息的发送人, 发送时间, 收信人, 消息 ids 等数据.
-     * 随后的元素为拥有顺序的真实消息内容.
+     * 返回的消息链中一定包含 [MessageSource], 存储此消息的发送人, 发送时间, 收信人, 消息 ids 等数据. 随后的元素为拥有顺序的真实消息内容.
+     *
+     * 详细查看 [MessageChain]
      */
     public val message: MessageChain
 
-    /** 消息发送时间 (由服务器提供, 可能与本地有时差) */
+    /** 消息发送时间戳, 单位为秒. 由服务器提供, 可能与本地有时差. */
     public val time: Int
 
     /**
-     * 消息源. 来自 [message] 的第一个元素,
+     * 消息源. 来自 [message]. 相当于对 [message] 以 [MessageSource] 参数调用 [MessageChain.get].
      */
     public val source: OnlineMessageSource.Incoming get() = message.source as OnlineMessageSource.Incoming
 }
@@ -261,5 +258,8 @@ public class StrangerMessageEvent constructor(
     public override fun toString(): String = "StrangerMessageEvent(sender=${sender.id}, message=$message)"
 }
 
+/**
+ * 消息事件的公共抽象父类, 保留将来使用. 这是内部 API, 请不要使用.
+ */
 @MiraiInternalApi
 public abstract class AbstractMessageEvent : MessageEvent, AbstractEvent()
diff --git a/mirai-core-api/src/commonMain/kotlin/message/code/MiraiCode.kt b/mirai-core-api/src/commonMain/kotlin/message/code/MiraiCode.kt
@@ -20,6 +20,8 @@ import net.mamoe.mirai.utils.safeCast
 
 /**
  * Mirai 码相关操作.
+ *
+ * 可在 GitHub 查看 [详细文档](https://github.com/mamoe/mirai/blob/dev/docs/Messages.md#mirai-%E7%A0%81).
  */
 public object MiraiCode {
     /**

diff --git a/mirai-core-api/src/commonMain/kotlin/message/data/At.kt b/mirai-core-api/src/commonMain/kotlin/message/data/At.kt
@@ -27,6 +27,8 @@ import net.mamoe.mirai.utils.MiraiExperimentalApi
 /**
  * At 一个群成员. 只能发送给一个群.
  *
+ * 使用时直接构造 At 实例即可.
+ *
  * ## mirai 码支持
  * 格式: &#91;mirai:at:*[target]*&#93;
  *

diff --git a/mirai-core-api/src/commonMain/kotlin/message/data/AtAll.kt b/mirai-core-api/src/commonMain/kotlin/message/data/AtAll.kt
@@ -23,6 +23,17 @@ import net.mamoe.mirai.utils.MiraiExperimentalApi
  *
  * 非会员每天只能发送 10 次 [AtAll]. 超出部分会被以普通文字看待.
  *
+ * ## 使用 [AtAll]
+ *
+ * [AtAll] 是单例, 将 [AtAll] 实例[添加][Message.plus]到消息链中即可.
+ * ```
+ * // Kotlin
+ * contact.sendMessage(AtAll + "test")
+ *
+ * // Java
+ * contact.sendMessage(MessageUtils.newChain(AtAll.INSTANCE, new PlainText("test")));
+ * ```
+ *
  * ## mirai 码支持
  * 格式: &#91;mirai:atall&#93;
  *

diff --git a/mirai-core-api/src/commonMain/kotlin/message/data/ConstrainSingle.kt b/mirai-core-api/src/commonMain/kotlin/message/data/ConstrainSingle.kt
@@ -22,8 +22,8 @@ package net.mamoe.mirai.message.data
  *
  * 实现此接口的元素将会在连接时自动处理替换.
  *
- * 要获取有关键的信息, 查看 [MessageKey].
- * 要获取有关约束的处理方式, 查看 [AbstractPolymorphicMessageKey].
+ * - 要获取有关键的信息, 查看 [MessageKey].
+ * - 要获取有关约束的处理方式, 查看 [AbstractPolymorphicMessageKey].
  */
 public interface ConstrainSingle : SingleMessage {
     /**

diff --git a/mirai-core-api/src/commonMain/kotlin/message/data/Dice.kt b/mirai-core-api/src/commonMain/kotlin/message/data/Dice.kt
@@ -25,6 +25,8 @@ import kotlin.random.nextInt
 /**
  * 骰子.
  *
+ * 构造 [Dice] 实例即可使用. 也可以通过 [Dice.random] 获得一个随机点数的实例.
+ *
  * @since 2.5
  */
 @Serializable

diff --git a/mirai-core-api/src/commonMain/kotlin/message/data/Face.kt b/mirai-core-api/src/commonMain/kotlin/message/data/Face.kt
@@ -21,6 +21,8 @@ import net.mamoe.mirai.utils.MiraiExperimentalApi
 /**
  * QQ 自带表情
  *
+ * 使用时通过 [Face.JING_YA] 等静态字段得到 ID 然后构造 [Face] 实例.
+ *
  * ## mirai 码支持
  * 格式: &#91;mirai:face:*[id]*&#93;
  */

diff --git a/mirai-core-api/src/commonMain/kotlin/message/data/FlashImage.kt b/mirai-core-api/src/commonMain/kotlin/message/data/FlashImage.kt
@@ -28,6 +28,10 @@ import net.mamoe.mirai.utils.safeCast
  * - 在 Kotlin 使用类构造器顶层函数 `FlashImage(image)`.
  * - 在 Kotlin 使用扩展 [Image.flash].
  *
+ * ## 获得闪照代表的原图片
+ *
+ * 访问属性 [FlashImage.image]
+ *
  * ## mirai 码支持
  * 格式: &#91;mirai:flash:*[Image.imageId]*&#93;
  *

diff --git a/mirai-core-api/src/commonMain/kotlin/message/data/ForwardMessage.kt b/mirai-core-api/src/commonMain/kotlin/message/data/ForwardMessage.kt
@@ -25,11 +25,22 @@ import net.mamoe.mirai.utils.safeCast
 import net.mamoe.mirai.utils.toLongUnsigned
 
 
-@MiraiExperimentalApi
+/**
+ * 未通过 [DisplayStrategy] 渲染的合并转发消息. [RawForwardMessage] 仅作为一个中间件, 用于 [ForwardMessageBuilder].
+ *
+ * [RawForwardMessage] 可以序列化保存, 也可以被多次[渲染][RawForwardMessage.render]产生不同格式的 [ForwardMessage].
+ */
 @Serializable
+@MiraiExperimentalApi
 public data class RawForwardMessage(
+    /**
+     * 消息列表
+     */
     val nodeList: List<ForwardMessage.Node>
 ) {
+    /**
+     * 渲染这个 [RawForwardMessage] 并产生可以发送的 [ForwardMessage]
+     */
     public fun render(displayStrategy: DisplayStrategy): ForwardMessage = ForwardMessage(
         preview = displayStrategy.generatePreview(this),
         title = displayStrategy.generateTitle(this),
@@ -50,11 +61,9 @@ public data class RawForwardMessage(
  * ### 移动端
  * 在移动客户端将会显示为卡片
  *
- * `<title>`: [DisplayStrategy.generateTitle]
- *
- * `<preview>`: [DisplayStrategy.generatePreview]
- *
- * `<summary>`: [DisplayStrategy.generateSummary]
+ * - `<title>`: [DisplayStrategy.generateTitle]
+ * - `<preview>`: [DisplayStrategy.generatePreview]
+ * - `<summary>`: [DisplayStrategy.generateSummary]
  *
  * ```
  * |-------------------------|
@@ -90,6 +99,7 @@ public data class RawForwardMessage(
  *
  *
  * ## 构造
+ * - 使用构建器 [ForwardMessageBuilder]
  * - 使用 [DSL][buildForwardMessage]
  * - 通过 [MessageEvent] 集合转换: [toForwardMessage]
  *
@@ -113,6 +123,8 @@ public data class ForwardMessage(
 
 
     /**
+     * 合并转发卡片展示策略. 用于 [RawForwardMessage] 的 [渲染][RawForwardMessage.render].
+     *
      * @see ForwardMessage
      */
     public interface DisplayStrategy {
@@ -133,7 +145,6 @@ public data class ForwardMessage(
 
         /**
          * 显示在卡片 body 中, 只会显示 sequence 前四个元素.
-         * Java 用户: 使用 [sequenceOf] (`SequenceKt.sequenceOf`) 或 [asSequence] (`SequenceKt.asSequence`)
          */
         public fun generatePreview(forward: RawForwardMessage): List<String> =
             forward.nodeList.map { it.senderName + ": " + it.messageChain.contentToString() }
@@ -143,6 +154,9 @@ public data class ForwardMessage(
          */
         public fun generateSummary(forward: RawForwardMessage): String = "查看 ${forward.nodeList.size} 条转发消息"
 
+        /**
+         * 默认的, 与官方客户端相似的展示方案.
+         */
         public companion object Default : DisplayStrategy
     }
 
@@ -381,7 +395,7 @@ public annotation class ForwardMessageDsl
  */
 public class ForwardMessageBuilder private constructor(
     /**
-     * 消息语境. 可为 [Group] 或 [User]
+     * 消息语境. 可为 [Group] 或 [User]. 用来确定某 ID 的用户的昵称.
      */
     public val context: Contact,
     private val container: MutableList<ForwardMessage.INode>

diff --git a/mirai-core-api/src/commonMain/kotlin/message/data/Image.kt b/mirai-core-api/src/commonMain/kotlin/message/data/Image.kt
@@ -113,12 +113,9 @@ public interface Image : Message, MessageContent, CodableMessage {
         public const val SERIAL_NAME: String = "Image"
 
         /**
-         * 通过 [Image.imageId] 构造一个 [Image] 以便发送.
-         * 这个图片必须是服务器已经存在的图片.
+         * 通过 [Image.imageId] 构造一个 [Image] 以便发送. 这个图片必须是服务器已经存在的图片.
          * 图片 id 不一定会长时间保存, 因此不建议使用 id 发送图片.
          *
-         * 请查看 `ExternalImageJvm` 获取更多创建 [Image] 的方法
-         *
          * @see Image 获取更多说明
          * @see Image.imageId 获取更多说明
          */
@@ -183,12 +180,9 @@ public interface Image : Message, MessageContent, CodableMessage {
 }
 
 /**
- * 通过 [Image.imageId] 构造一个 [Image] 以便发送.
- * 这个图片必须是服务器已经存在的图片.
+ * 通过 [Image.imageId] 构造一个 [Image] 以便发送. 这个图片必须是服务器已经存在的图片.
  * 图片 id 不一定会长时间保存, 因此不建议使用 id 发送图片.
  *
- * 请查看 `ExternalImageJvm` 获取更多创建 [Image] 的方法
- *
  * @see Image 获取更多说明
  * @see Image.imageId 获取更多说明
  *

diff --git a/mirai-core-api/src/commonMain/kotlin/message/data/MarketFace.kt b/mirai-core-api/src/commonMain/kotlin/message/data/MarketFace.kt
@@ -15,7 +15,7 @@ import net.mamoe.mirai.utils.safeCast
 /**
  * 商城表情
  *
- * 除 [Dice] 可以发送外, 目前不支持直接发送，可保存接收到的来自官方客户端的商城表情然后转发.
+ * 除 [Dice] 可以发送外, 目前不支持直接构造和发送，可保存接收到的来自官方客户端的商城表情然后转发.
  *
  * @see Dice
  */