From 179746c5f7f672ea166623c27c80ef2f1a2efb18 Mon Sep 17 00:00:00 2001
From: Him188 <Him188@mamoe.net>
Date: Fri, 8 Jan 2021 11:24:23 +0800
Subject: [PATCH] Update docs

---
 .../commonMain/kotlin/contact/ContactList.kt   | 18 +++++++++++++++++-
 .../commonMain/kotlin/message/data/Message.kt  |  2 +-
 2 files changed, 18 insertions(+), 2 deletions(-)

diff --git a/mirai-core-api/src/commonMain/kotlin/contact/ContactList.kt b/mirai-core-api/src/commonMain/kotlin/contact/ContactList.kt
index ccac2bfe6..8c476ec52 100644
--- a/mirai-core-api/src/commonMain/kotlin/contact/ContactList.kt
+++ b/mirai-core-api/src/commonMain/kotlin/contact/ContactList.kt
@@ -12,11 +12,12 @@
 package net.mamoe.mirai.contact
 
 import net.mamoe.mirai.utils.MiraiInternalApi
+import net.mamoe.mirai.utils.PlannedRemoval
 import java.util.concurrent.ConcurrentLinkedQueue
 
 
 /**
- * 只读联系人列表, 无锁链表实现
+ * 只读联系人列表. 元素列表仍可能会被 mirai 内部修改.
  *
  * @see ContactList.asSequence
  */
@@ -27,9 +28,24 @@ internal constructor(@JvmField @MiraiInternalApi public val delegate: Concurrent
     internal constructor(collection: Collection<C>) : this(ConcurrentLinkedQueue(collection))
     internal constructor() : this(ConcurrentLinkedQueue())
 
+    /**
+     * 获取一个 [Contact.id] 为 [id] 的元素. 在不存在时返回 `null`.
+     */
     public operator fun get(id: Long): C? = delegate.firstOrNull { it.id == id }
+
+    /**
+     * 获取一个 [Contact.id] 为 [id] 的元素. 在不存在时抛出 [NoSuchElementException].
+     */
     public fun getOrFail(id: Long): C = get(id) ?: throw NoSuchElementException("Contact $id not found.")
+
+    /**
+     * 删除 [Contact.id] 为 [id] 的元素.
+     */
     public fun remove(id: Long): Boolean = delegate.removeAll { it.id == id }
+
+    /**
+     * 当存在 [Contact.id] 为 [id] 的元素时返回 `true`.
+     */
     public operator fun contains(id: Long): Boolean = get(id) != null
 
     override fun toString(): String = delegate.joinToString(separator = ", ", prefix = "ContactList(", postfix = ")")
diff --git a/mirai-core-api/src/commonMain/kotlin/message/data/Message.kt b/mirai-core-api/src/commonMain/kotlin/message/data/Message.kt
index 2e8a68c05..45d361bf1 100644
--- a/mirai-core-api/src/commonMain/kotlin/message/data/Message.kt
+++ b/mirai-core-api/src/commonMain/kotlin/message/data/Message.kt
@@ -68,7 +68,7 @@ import kotlin.internal.LowPriorityInOverloadResolution
  *
  * @see Contact.sendMessage 发送消息
  */
-public interface Message { // must be interface. Don't consider any changes.
+public interface Message {
 
     /**
      * 将 `this` 和 [tail] 连接.