Improve docs

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

@@ -31,10 +31,10 @@ import kotlin.reflect.KProperty
  * 要获取更多消息相关的信息, 查看 [Message]
  *
  * ### 构造消息链
- * - [buildMessageChain]: 使用构建器
- * - [Message.plus]: 将两个消息相连成为一个消息链
- * - [asMessageChain] 将 [Iterable], [Array] 等类型消息转换为 [MessageChain]
- * - [messageChainOf] 类似 [listOf], 将多个 [Message] 构造为 [MessageChain]
+ * - [buildMessageChain][buildMessageChain]: 使用构建器
+ * - [Message.plus][Message.plus]: 将两个消息相连成为一个消息链
+ * - [asMessageChain][asMessageChain] 将 [Iterable], [Array] 等类型消息转换为 [MessageChain]
+ * - [messageChainOf][messageChainOf] 类似 [listOf], 将多个 [Message] 构造为 [MessageChain]
  *
  * @see get 获取消息链中一个类型的元素, 不存在时返回 `null`
  * @see getOrFail 获取消息链中一个类型的元素, 不存在时抛出异常 [NoSuchElementException]
@@ -63,19 +63,21 @@ public interface MessageChain : Message, List<SingleMessage>, RandomAccess {
     public override val size: Int
 
     /**
-     * 获取第一个类型为 [key] 的 [Message] 实例. 若不存在此实例, 返回 `null`
+     * 获取第一个类型为 [key] 的 [Message] 实例. 若不存在此实例, 返回 `null`.
+     *
+     * 此方法仅适用于 [ConstrainSingle] 的消息类型, 如 [MessageSource]
      *
      * ### Kotlin 使用方法
      * ```
      * val chain: MessageChain = ...
      *
-     * val at = Message[At] // At 为伴生对象
+     * val source = Message[MessageSource] // MessageSource 为伴生对象
      * ```
      *
      * ### Java 使用方法
      * ```java
      * MessageChain chain = ...
-     * chain.first(At.Key)
+     * chain.get(MessageSource.Key)
      * ```
      *
      * @param key 由各个类型消息的伴生对象持有. 如 [MessageSource.Key]

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

@@ -68,7 +68,8 @@ import net.mamoe.mirai.utils.safeCast
 @Serializable(MessageSourceSerializer::class)
 public sealed class MessageSource : Message, MessageMetadata, ConstrainSingle {
     @ExperimentalMessageKey
-    public final override val key: MessageKey<MessageSource> get() = Key
+    public final override val key: MessageKey<MessageSource>
+        get() = Key
 
     /**
      * 所属 [Bot.id]
@@ -76,17 +77,22 @@ public sealed class MessageSource : Message, MessageMetadata, ConstrainSingle {
     public abstract val botId: Long
 
     /**
-     * 消息 ids (序列号). 在获取失败时 (概率很低) 为 `-1`.
-     **
+     * 消息 ids (序列号). 在获取失败时 (概率很低) 为空数组.
+     *
      * ### 值域
      * 值的范围约为 [UShort] 的范围.
      *
      * ### 顺序
-     * 群消息的 ids 由服务器维护. 好友消息的 ids 由 mirai 维护.
-     * 此 ids 不一定从 0 开始.
+     * 群消息的 id 由服务器维护. 好友消息的 id 由 mirai 维护.
+     * 此 id 不一定从 0 开始.
      *
      * - 在同一个群的消息中此值随每条消息递增 1, 但此行为由服务器决定, mirai 不保证自增顺序.
      * - 在好友消息中无法保证每次都递增 1. 也可能会产生大幅跳过的情况.
+     *
+     * ### 多 ID 情况
+     * 对于单条消息, [ids] 为单元素数组. 对于分片 (一种长消息处理机制) 消息, [ids] 将包含多元素.
+     *
+     * [internalIds] 与 [ids] 以数组下标对应.
      */
     public abstract val ids: IntArray
 
@@ -96,6 +102,10 @@ public sealed class MessageSource : Message, MessageMetadata, ConstrainSingle {
      * 值没有顺序, 也可能为 0, 取决于服务器是否提供.
      *
      * 在事件中和在引用中无法保证同一条消息的 [internalIds] 相同.
+     *
+     * [internalIds] 与 [ids] 以数组下标对应.
+     *
+     * @see ids
      */
     public abstract val internalIds: IntArray