From e8b0e0efa507684e6032bb02b111b3f315c8aa07 Mon Sep 17 00:00:00 2001
From: Him188 <Him188@mamoe.net>
Date: Thu, 28 May 2020 12:51:30 +0800
Subject: [PATCH] Update docs

---
 .../net.mamoe.mirai/message/data/Message.kt     | 15 ++++++++++++++-
 .../message/data/MessageChain.kt                | 17 ++++++++++++++++-
 2 files changed, 30 insertions(+), 2 deletions(-)

diff --git a/mirai-core/src/commonMain/kotlin/net.mamoe.mirai/message/data/Message.kt b/mirai-core/src/commonMain/kotlin/net.mamoe.mirai/message/data/Message.kt
index ddb5e707b..c97275095 100644
--- a/mirai-core/src/commonMain/kotlin/net.mamoe.mirai/message/data/Message.kt
+++ b/mirai-core/src/commonMain/kotlin/net.mamoe.mirai/message/data/Message.kt
@@ -49,7 +49,7 @@ import kotlin.jvm.JvmSynthetic
  * - 连接 [Message] 与 [Message], [String], (使用操作符 [Message.plus]):
  *  ```
  * val text = PlainText("Hello ") + PlainText("world") + "!"
- * friend.sendMessage(text)
+ * friend.sendMessage(text) // "Hello world!"
  *  ```
  * 但注意: 不能 `String + Message`. 只能 `Message + String`
  *
@@ -177,18 +177,31 @@ interface Message { // must be interface. Don't consider any changes.
         }
     }
 
+    /** 将 [another] 按顺序连接到这个消息的尾部. */
     /* final */ operator fun plus(another: MessageChain): MessageChain = this + another as Message
+
+    /** 将 [another] 按顺序连接到这个消息的尾部. */
     /* final */ operator fun plus(another: Message): MessageChain = this.followedBy(another)
+
+    /** 将 [another] 连接到这个消息的尾部. */
     /* final */ operator fun plus(another: SingleMessage): MessageChain = this.followedBy(another)
+
+    /** 将 [another] 作为 [PlainText] 连接到这个消息的尾部. */
     /* final */ operator fun plus(another: String): MessageChain = this.followedBy(another.toMessage())
+
+    /** 将 [another] 作为 [PlainText] 连接到这个消息的尾部. */
     /* final */ operator fun plus(another: CharSequence): MessageChain = this.followedBy(another.toString().toMessage())
+
+    /** 将 [another] 按顺序连接到这个消息的尾部. */
     /* final */ operator fun plus(another: Iterable<Message>): MessageChain =
         another.fold(this, Message::plus).asMessageChain()
 
+    /** 将 [another] 按顺序连接到这个消息的尾部. */
     @JvmName("plusIterableString")
     /* final */ operator fun plus(another: Iterable<String>): MessageChain =
         another.fold(this, Message::plus).asMessageChain()
 
+    /** 将 [another] 按顺序连接到这个消息的尾部. */
     /* final */ operator fun plus(another: Sequence<Message>): MessageChain =
         another.fold(this, Message::plus).asMessageChain()
 }
diff --git a/mirai-core/src/commonMain/kotlin/net.mamoe.mirai/message/data/MessageChain.kt b/mirai-core/src/commonMain/kotlin/net.mamoe.mirai/message/data/MessageChain.kt
index 8710f03a6..1a2d739a6 100644
--- a/mirai-core/src/commonMain/kotlin/net.mamoe.mirai/message/data/MessageChain.kt
+++ b/mirai-core/src/commonMain/kotlin/net.mamoe.mirai/message/data/MessageChain.kt
@@ -62,7 +62,22 @@ interface MessageChain : Message, List<SingleMessage>, RandomAccess {
     /**
      * 获取第一个类型为 [key] 的 [Message] 实例. 若不存在此实例, 返回 `null`
      *
+     * ### Kotlin 使用方法
+     * ```
+     * val chain: MessageChain = ...
+     *
+     * val at = Message[At] // At 为伴生对象
+     * ```
+     *
+     * ### Java 使用方法
+     * ```java
+     * MessageChain chain = ...
+     * chain.first(At.Key)
+     * ```
+     *
      * @param key 由各个类型消息的伴生对象持有. 如 [PlainText.Key]
+     *
+     * @see MessageChain.getOrFail 在找不到此类型的元素时抛出 [NoSuchElementException]
      */
     @JvmName("first")
     final operator fun <M : Message> get(key: Message.Key<M>): M? = firstOrNull(key)
@@ -93,7 +108,7 @@ interface MessageChain : Message, List<SingleMessage>, RandomAccess {
 // region accessors
 
 /**
- * 获取第一个类型为 [key] 的 [Message] 实例
+ * 获取第一个类型为 [key] 的 [Message] 实例, 在找不到此类型的元素时抛出 [NoSuchElementException]
  *
  * @param key 由各个类型消息的伴生对象持有. 如 [PlainText.Key]
  */