Improve buildMessageSource and update docs

docs/Messages.md

@@ -38,7 +38,7 @@
 
 Mirai 支持富文本消息。各类型消息元素如下文表格所示。
 
-[`PlainText`]: ../mirai-core-api/src/commonMain/kotlin/message/data/At.kt
+[`PlainText`]: ../mirai-core-api/src/commonMain/kotlin/message/data/PlainText.kt
 [`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

mirai-core-api/src/commonMain/kotlin/IMirai.kt

@@ -146,7 +146,9 @@ public interface IMirai : LowLevelApiAccessor {
     public suspend fun queryImageUrl(bot: Bot, image: Image): String
 
     /**
-     * 构造一个 [OfflineMessageSource]
+     * 构造一个 [OfflineMessageSource].
+     *
+     * 更推荐使用 [MessageSourceBuilder] 和 [MessageSource.copyAmend] 创建 [OfflineMessageSource].
      *
      * @param ids 即 [MessageSource.ids]
      * @param internalIds 即 [MessageSource.internalIds]

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

@@ -35,30 +35,40 @@ import net.mamoe.mirai.utils.safeCast
 /**
  * 消息源. 消息源存在于 [MessageChain] 中, 用于表示这个消息的来源, 也可以用来分辨 [MessageChain].
  *
- * 对于来自 [MessageEvent.message] 的 [MessageChain]
- *
  *
  * ## 组成
- * [MessageSource] 由 metadata (元数据), form & target, content 组成
+ * [MessageSource] 由 定位属性, 发信人和收信人, 内容 组成
  *
- * ### metadata
+ * ### 定位属性
  * - [ids] 消息 ids (序列号)
  * - [internalIds] 消息内部 ids
  * - [time] 时间
  *
- * 官方客户端通过 metadata 这三个数据定位消息, 撤回和引用回复都是如此.
+ * 官方客户端通过这三个属性定位消息, 撤回和引用回复都是如此.
  *
- * ### form & target
+ * ### 发信人和收信人
  * - [fromId] 消息发送人
  * - [targetId] 消息发送目标
  *
- * ### content
+ * ### 内容
  * - [originalMessage] 消息内容
  *
+ * ## 获取
+ * - 来自 [MessageEvent.message] 的 [MessageChain] 总是包含 [MessageSource]. 可通过 [MessageChain.get] 获取 [MessageSource]:
+ *    ```
+ *    val source = chain[MessageSource]
+ *    ```
+ * - 构造离线消息源 [IMirai.constructMessageSource]
+ *
+ *
  * ## 使用
  *
  * 消息源可用于 [引用回复][MessageSource.quote] 或 [撤回][MessageSource.recall].
  *
+ * 对于来自 [MessageEvent.message] 的 [MessageChain], 总是包含 [MessageSource].
+ * 因此也可以对这样的 [MessageChain] 进行 [引用回复][MessageChain.quote] 或 [撤回][MessageChain.recall].
+ *
+ *
  * @see IMirai.recallMessage 撤回一条消息
  * @see MessageSource.quote 引用这条消息, 创建 [MessageChain]
  *

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

@@ -19,7 +19,6 @@ import net.mamoe.mirai.Mirai
 import net.mamoe.mirai.contact.ContactOrBot
 import net.mamoe.mirai.message.data.MessageSource.Key.quote
 import net.mamoe.mirai.message.data.MessageSource.Key.recall
-import net.mamoe.mirai.message.data.MessageSourceBuilder.Companion.create
 import net.mamoe.mirai.utils.PlannedRemoval
 import net.mamoe.mirai.utils.currentTimeSeconds
 
@@ -48,9 +47,12 @@ public fun MessageSource.copyAmend(
 }
 
 /**
- * 仅于 [copyAmend] 中修改 [MessageSource]
+ * [MessageSource] 复制修改器. 不会修改原 [MessageSource], 而是会创建一个新的 [MessageSource].
+ *
+ * @see copyAmend Kotlin DSL
+ * @see MessageSourceBuilder
  */
-public class MessageSourceAmender internal constructor(
+public class MessageSourceAmender public constructor(
     origin: MessageSource,
 ) : MessageSourceBuilder() {
     public var kind: MessageSourceKind = origin.kind
@@ -77,7 +79,31 @@ public class MessageSourceAmender internal constructor(
 
 
 /**
- * 构建一个 [OfflineMessageSource]
+ * 使用 DSL 构建一个 [OfflineMessageSource]. 用法参考 [MessageSourceBuilder].
+ *
+ * @see copyAmend
+ */
+@JvmSynthetic
+public inline fun IMirai.buildMessageSource(
+    botId: Long,
+    kind: MessageSourceKind,
+    block: MessageSourceBuilder.() -> Unit
+): OfflineMessageSource = MessageSourceBuilder().apply(block).build(botId, kind)
+
+/**
+ * 使用 DSL 构建一个 [OfflineMessageSource]. 用法参考 [MessageSourceBuilder].
+ *
+ * @see buildMessageSource
+ */
+@JvmSynthetic
+public inline fun Bot.buildMessageSource(
+    kind: MessageSourceKind,
+    block: MessageSourceBuilder.() -> Unit
+): OfflineMessageSource = Mirai.buildMessageSource(this.id, kind, block)
+
+
+/**
+ * 离线消息源构建器.
  *
  * ### 参数
  * 一个 [OfflineMessageSource] 需要以下参数:
@@ -89,10 +115,11 @@ public class MessageSourceAmender internal constructor(
  * - 消息内容: 通过 [MessageSourceBuilder.messages] 设置
  *
  * ### 性质
- * - 当两个消息的元数据相同时, 他们在群中会是同一条消息. 可通过此特性决定官方客户端 "定位原消息" 的目标
+ * - 当两个消息的元数据相同时, 它们在群中会是同一条消息. 可通过此特性决定官方客户端 "定位原消息" 的目标
  * - 发送人的信息和消息内容会在官方客户端显示在引用回复中.
  *
  * ### 实例
+ * Kotlin:
  * ```
  * bot.buildMessageSource(MessageSourceKind.GROUP) {
  *     from(bot)
@@ -105,32 +132,20 @@ public class MessageSourceAmender internal constructor(
  * }
  * ```
  *
- * @see copyAmend
- */
-public fun IMirai.buildMessageSource(
-    botId: Long,
-    kind: MessageSourceKind,
-    block: MessageSourceBuilder.() -> Unit
-): OfflineMessageSource = MessageSourceBuilder.create().apply(block).run {
-    Mirai.constructMessageSource(botId, kind, fromId, targetId, ids, time, internalIds, originalMessages.build())
-}
-
-/**
- * 构建一个 [OfflineMessageSource]
+ * Java:
+ * ```java
+ * MessageSourceBuilder
+ *     .create()
+ *     .from(bot)
+ *     .target(target)
+ *     .metadata(source) // 从另一个消息源复制 ids, internalIds, time
+ *     .messages(new PlainText("hi"))
+ *     .build(botId, MessageSourceKind.FRIEND);
+ * ```
  *
  * @see buildMessageSource
  */
-public fun Bot.buildMessageSource(
-    kind: MessageSourceKind,
-    block: MessageSourceBuilder.() -> Unit
-): OfflineMessageSource = Mirai.buildMessageSource(this.id, kind, block)
-
-
-/**
- * @see buildMessageSource
- * @see create
- */
-public open class MessageSourceBuilder internal constructor() {
+public open class MessageSourceBuilder public constructor() {
     public open var fromId: Long = 0
     public open var targetId: Long = 0
 
@@ -235,8 +250,16 @@ public open class MessageSourceBuilder internal constructor() {
     public fun setSenderAndTarget(sender: ContactOrBot, target: ContactOrBot): MessageSourceBuilder =
         sender(sender).target(target)
 
-    public companion object {
-        @JvmStatic
-        public fun create(): MessageSourceBuilder = MessageSourceBuilder()
+    public fun build(botId: Long, kind: MessageSourceKind): OfflineMessageSource {
+        return Mirai.constructMessageSource(
+            botId,
+            kind,
+            fromId,
+            targetId,
+            ids,
+            time,
+            internalIds,
+            originalMessages.build()
+        )
     }
 }

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

@@ -20,13 +20,18 @@ import net.mamoe.mirai.message.code.internal.appendStringAsMiraiCode
 import net.mamoe.mirai.utils.MiraiExperimentalApi
 
 /**
- * 纯文本. 可含 emoji 表情如 😊.
+ * 纯文本.
  *
- * 一般不需要主动构造 [PlainText], [Message] 可直接与 [String] 相加. Java 用户请使用 [Message.plus]
+ * 使用时直接构造即可. [Message] 也可以直接与 [String] 相加, 详见 [Message.plus].
+ *
+ * @see String.toPlainText
  */
 @Serializable
 @SerialName(PlainText.SERIAL_NAME)
 public data class PlainText(
+    /**
+     * 消息内容
+     */
     public val content: String
 ) : MessageContent, CodableMessage {
     @Suppress("unused")