Improve docs

mirai-core-api/src/commonMain/kotlin/message/data/Message.kt

@@ -300,28 +300,64 @@ public interface MessageMetadata : SingleMessage {
  * 约束一个 [MessageChain] 中只存在这一种类型的元素. 新元素将会替换旧元素, 保持原顺序.
  *
  * 实现此接口的元素将会在连接时自动处理替换.
+ *
+ * @see AbstractMessageKey
+ * @see AbstractPolymorphicMessageKey
+ *
+ * @see MessageSource
  */
 @ExperimentalMessageKey
 public interface ConstrainSingle : SingleMessage {
     /**
-     * 用于判断是否为同一种元素的 [MessageKey]
+     * 用于判断是否为同一种元素的 [MessageKey]. 使用多态类型 [MessageKey] 最上层的 [MessageKey].
      * @see MessageKey 查看更多信息
      */
     @ExperimentalMessageKey
     public val key: MessageKey<*>
 }
 
+/**
+ * 独立的 [MessageKey] 的实现. '独立' 即 `final`, 不支持多态类型. 适用于作为最顶层的 [MessageKey], 如 [MessageSource].
+ *
+ * @see AbstractPolymorphicMessageKey
+ */
 @ExperimentalMessageKey
 public abstract class AbstractMessageKey<out M : SingleMessage>(
     override val safeCast: (SingleMessage) -> M?,
-) : MessageKey<M> {
-    internal fun tryCast(element: SingleMessage): M? = safeCast(element)
-    internal open fun isSubKey(key: MessageKey<*>): Boolean = key === this
-}
+) : MessageKey<M>
 
+/**
+ * 多态 [MessageKey].
+ *
+ * 示例: [HummerMessage]
+ * ```
+ *               MessageContent
+ *                     ↑
+ *               HummerMessage
+ *                     ↑
+ *        +------------+-------------+
+ *        |            |             |
+ *  PokeMessage     VipFace      FlashImage
+ *
+ * ```
+ *
+ * 当 [连接][Message.plus] 一个 [VipFace] 到一个 [MessageChain] 时,
+ * 由于 [VipFace] 最上层为 [MessageContent], 消息链中第一个 [MessageContent] 会被 (保留顺序地) 替换为 [VipFace], 其他所有 [MessageContent] 都会被删除.
+ *
+ * 如:
+ * ```
+ * val source: MessageSource = ...
+ *
+ * val result = messageChainOf(PlainText("a"), PlainText("b"), source, AtAll) + VipFace.LiuLian
+ * // result 为 [VipFace.LiuLian, source]
+ *
+ * val result = source1 + source2
+ * // result 为 [source2], 总是右侧替换左侧
+ * ```
+ */
 @ExperimentalMessageKey
 public abstract class AbstractPolymorphicMessageKey<out B : SingleMessage, out M : B>(
-    public val baseKey: MessageKey<B>,
+    baseKey: MessageKey<B>,
     safeCast: (SingleMessage) -> M?,
 ) : MessageKey<M>, AbstractMessageKey<M>(safeCast) {
     internal val topmostKey: MessageKey<*> =
@@ -329,7 +365,7 @@ public abstract class AbstractPolymorphicMessageKey<out B : SingleMessage, out M
 }
 
 /**
- * 消息内容
+ * 带内容的消息.
  *
  * @see PlainText 纯文本
  * @see At At 一个群成员.

mirai-core-api/src/commonMain/kotlin/net/mamoe/mirai/message/data/MessageKey.kt

@@ -12,42 +12,39 @@ package net.mamoe.mirai.message.data
 /**
  * 类型 Key. 由伴生对象实现, 表示一个 [Message] 对象的类型.
  *
- * 除 [MessageChain] 外, 每个 [Message] 类型都拥有一个伴生对象 (companion object) 来持有一个 Key
- *
- * 在 [MessageChain.get] 时将会使用到这个 Key 进行判断类型.
+ * 每个 [ConstrainSingle] 类型都拥有一个伴生对象来持有 [MessageKey] 以允许 `val source = chain[MessageSource]` 的用法.
  *
  * #### 用例
  * [MessageChain.get][MessageChain.get]: 允许使用数组访问操作符获取指定类型的消息元素
  * ```
- * val image: Image = chain[Image]
+ * val source: MessageSource = chain[MessageSource]
  * ```
  *
  * @param M 指代持有这个 Key 的消息类型
  */
 @ExperimentalMessageKey
 public interface MessageKey<out M : SingleMessage> {
+    /**
+     * 将一个 [SingleMessage] 强转为 [M] 类型. 在类型不符合时返回 `null`
+     */
     public val safeCast: (SingleMessage) -> M?
 }
 
 @ExperimentalMessageKey
 public fun MessageKey<*>.isInstance(message: SingleMessage): Boolean = this.safeCast(message) != null
 
-@ExperimentalMessageKey
-public tailrec fun <A : SingleMessage, B : SingleMessage> MessageKey<A>.isSubKeyOf(baseKey: MessageKey<B>): Boolean {
-    return when {
-        this === baseKey -> true
-        this is AbstractPolymorphicMessageKey<*, *> -> {
-            this.baseKey.isSubKeyOf(baseKey)
-        }
-        else -> false
-    }
-}
-
+/**
+ * 获取最上层 [MessageKey].
+ *
+ * 当 [this][MessageKey] 为 [AbstractPolymorphicMessageKey]
+ *
+ * 如 [FlashImage], 其 [MessageKey]
+ */
 @ExperimentalMessageKey
 public val <A : SingleMessage> MessageKey<A>.topmostKey: MessageKey<*>
     get() = when (this) {
         is AbstractPolymorphicMessageKey<*, *> -> {
-            this.baseKey.topmostKey
+            this.topmostKey
         }
         else -> this
     }