Add docs

mirai-core/src/commonMain/kotlin/net.mamoe.mirai/Bot.kt

@@ -200,13 +200,13 @@ abstract class Bot internal constructor(
      * [Bot] 撤回自己的消息不需要权限.
      * [Bot] 撤回群员的消息需要管理员权限.
      *
-     * @param source 消息源. 可从 [MessageReceipt.source] 获得, 或从消息事件中的 [MessageChain] 获得.
+     * @param source 消息源. 可从 [MessageReceipt.source] 获得, 或从消息事件中的 [MessageChain] 获得, 或通过 [buildMessageSource] 构建.
      *
-     * @throws PermissionDeniedException 当 [Bot] 无权限操作时
-     * @throws IllegalStateException 当这条消息已经被撤回时 (仅同步主动操作)
+     * @throws PermissionDeniedException 当 [Bot] 无权限操作时抛出
+     * @throws IllegalStateException 当这条消息已经被撤回时抛出 (仅同步主动操作)
      *
      * @see Bot.recall (扩展函数) 接受参数 [MessageChain]
-     * @see MessageSource.recall
+     * @see MessageSource.recall 撤回消息扩展
      */
     @JvmSynthetic
     abstract suspend fun recall(source: MessageSource)
@@ -233,7 +233,7 @@ abstract class Bot internal constructor(
      * @param fromUin 为用户时为 [Friend.id], 为群时需使用 [Group.calculateGroupUinByGroupCode] 计算
      * @param targetUin 为用户时为 [Friend.id], 为群时需使用 [Group.calculateGroupUinByGroupCode] 计算
      */
-    @MiraiExperimentalAPI
+    @MiraiExperimentalAPI("This is very experimental and is subject to change.")
     abstract fun constructMessageSource(
         kind: OfflineMessageSource.Kind,
         fromUin: Long, targetUin: Long,
@@ -336,7 +336,7 @@ abstract class Bot internal constructor(
  * 获取 [Job] 的协程 [Job]. 此 [Job] 为一个 [SupervisorJob]
  */
 @get:JvmSynthetic
-inline val Bot.supervisorJob: CompletableJob
+val Bot.supervisorJob: CompletableJob
     get() = this.coroutineContext[Job] as CompletableJob
 
 /**

mirai-core/src/commonMain/kotlin/net.mamoe.mirai/message/MessageEvent.kt

@@ -77,13 +77,20 @@ abstract class MessageEvent : @PlannedRemoval("1.2.0") ContactMessage(),
      */
     abstract override val senderName: String
 
-    /** 消息内容 */
+    /**
+     * 消息内容.
+     *
+     * 第一个元素一定为 [MessageSource], 存储此消息的发送人, 发送时间, 收信人, 消息 id 等数据.
+     * 随后的元素为拥有顺序的真实消息内容.
+     */
     abstract override val message: MessageChain
 
-    /** 消息发送时间 (由服务器提供) */
+    /** 消息发送时间 (由服务器提供, 可能与本地有时差) */
     abstract override val time: Int
 
-    /** 消息源 */
+    /**
+     * 消息源. 来自 [message] 的第一个元素,
+     */
     override val source: OnlineMessageSource.Incoming get() = message.source as OnlineMessageSource.Incoming
 }
 

mirai-core/src/commonMain/kotlin/net.mamoe.mirai/message/MessageReceipt.kt

@@ -41,7 +41,7 @@ import kotlin.jvm.JvmSynthetic
  * @see MessageReceipt.sourceId 源 id
  * @see MessageReceipt.sourceTime 源时间
  */
-open class MessageReceipt<out C : Contact>(
+open class MessageReceipt<out C : Contact> @MiraiExperimentalAPI("The constructor is subject to change.") constructor(
     /**
      * 指代发送出去的消息.
      */
@@ -51,38 +51,68 @@ open class MessageReceipt<out C : Contact>(
      */
     val target: C,
 
-    @MiraiExperimentalAPI
+    /**
+     * @see Group.botAsMember
+     */
+    @MiraiExperimentalAPI("This is subject to change.")
     val botAsMember: Member?
 ) {
     /**
      * 是否为发送给群的消息的回执
      */
-    val isToGroup: Boolean = target is Group
+    val isToGroup: Boolean get() = target is Group
 
+    /**
+     * 引用这条消息并回复.
+     *
+     * 仅供 Java 使用.
+     *
+     * 仅供 Java 使用: `MessageReceipt.quoteReply(message)`
+     */
     @JavaFriendlyAPI
     @JvmName("quoteReply")
     fun __quoteReplyBlockingForJava__(message: Message): MessageReceipt<C> {
         return runBlocking { return@runBlocking quoteReply(message) }
     }
 
+    /**
+     * 引用这条消息并回复.
+     *
+     * 仅供 Java 使用: `MessageReceipt.quoteReply(message)`
+     */
     @JavaFriendlyAPI
     @JvmName("quoteReply")
     fun __quoteReplyBlockingForJava__(message: String): MessageReceipt<C> {
         return runBlocking { quoteReply(message) }
     }
 
+    /**
+     * 撤回这条消息. [recall] 或 [recallIn] 只能被调用一次.
+     *
+     * 仅供 Java 使用: `MessageReceipt.recall()`
+     */
     @JavaFriendlyAPI
     @JvmName("recall")
     fun __recallBlockingForJava__() {
         return runBlocking { recall() }
     }
 
+    /**
+     * 撤回这条消息. [recall] 或 [recallIn] 只能被调用一次.
+     *
+     * 仅供 Java 使用: `MessageReceipt.recallIn(timeMillis)`
+     */
     @JavaFriendlyAPI
     @JvmName("recallIn")
     fun __recallInBlockingForJava__(timeMillis: Long): Job {
         return recallIn(timeMillis = timeMillis)
     }
 
+    /**
+     * 引用这条消息.
+     *
+     * 仅供 Java 使用: `MessageReceipt.quote()`
+     */
     @JavaFriendlyAPI
     @JvmName("quote")
     fun __quoteBlockingForJava__(): QuoteReply {

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

@@ -20,6 +20,7 @@
 
 package net.mamoe.mirai.message.data
 
+import kotlinx.io.core.copyTo
 import kotlinx.serialization.Serializable
 import net.mamoe.mirai.Bot
 import net.mamoe.mirai.contact.Contact
@@ -185,8 +186,8 @@ fun Image(imageId: String): OfflineImage = when {
 /**
  * 查询原图下载链接.
  *
- * 当图片为从服务器接收的消息中的图片时, 可以直接获取下载链接, 本函数不会挂起协程.
- * 其他情况下协程可能会挂起并向服务器查询下载链接, 或不挂起并拼接一个链接.
+ * - 当图片为从服务器接收的消息中的图片时, 可以直接获取下载链接, 本函数不会挂起协程.
+ * - 其他情况下协程可能会挂起并向服务器查询下载链接, 或不挂起并拼接一个链接.
  *
  * @return 原图 HTTP 下载链接 (非 HTTPS)
  * @throws IllegalStateException 当无任何 [Bot] 在线时抛出 (因为无法获取相关协议)
@@ -195,12 +196,15 @@ fun Image(imageId: String): OfflineImage = when {
 suspend fun Image.queryUrl(): String {
     @Suppress("DEPRECATION")
     return when (this) {
-        is OnlineImage -> this.originUrl
-        else -> Bot._instances.peekFirst()?.get()?.queryImageUrl(this)
-            ?: error("No Bot available to query image url")
+        is ConstOriginUrlAware -> this.originUrl
+        is DeferredOriginUrlAware -> this.getUrl(firstOnlineBotInstance)
+        is SuspendDeferredOriginUrlAware -> this.getUrl(firstOnlineBotInstance)
+        else -> error("Internal error: unsupported Image class: ${this::class}")
     }
 }
 
+internal val firstOnlineBotInstance: Bot get() = Bot.botInstancesSequence.firstOrNull() ?: error("No Bot available")
+
 
 /////////////////////////
 ///// 以下 API 已弃用 /////

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

@@ -9,7 +9,7 @@
 
 @file:JvmMultifileClass
 @file:JvmName("MessageUtils")
-@file:Suppress("NOTHING_TO_INLINE", "unused", "INAPPLICABLE_JVM_NAME", "DEPRECATION_ERROR")
+@file:Suppress("NOTHING_TO_INLINE", "unused", "INAPPLICABLE_JVM_NAME", "DEPRECATION_ERROR", "UnUsedImport")
 
 package net.mamoe.mirai.message.data
 
@@ -18,6 +18,8 @@ import net.mamoe.mirai.Bot
 import net.mamoe.mirai.contact.*
 import net.mamoe.mirai.message.MessageEvent
 import net.mamoe.mirai.message.MessageReceipt
+import net.mamoe.mirai.message.quote
+import net.mamoe.mirai.message.recall
 import net.mamoe.mirai.recallIn
 import net.mamoe.mirai.utils.LazyProperty
 import kotlin.coroutines.CoroutineContext
@@ -27,7 +29,9 @@ import kotlin.jvm.JvmName
 import kotlin.jvm.JvmSynthetic
 
 /**
- * 消息源, 它存在于 [MessageChain] 中, 用于表示这个消息的来源.
+ * 消息源. 消息源存在于 [MessageChain] 中, 用于表示这个消息的来源, 也可以用来分辨 [MessageChain].
+ *
+ * 对于来自 [MessageEvent.message] 的 [MessageChain]
  *
  *
  * ### 组成
@@ -47,6 +51,7 @@ import kotlin.jvm.JvmSynthetic
  * #### content
  * - [originalMessage] 消息内容
  *
+ * ### 使用
  *
  * 消息源可用于 [引用回复][QuoteReply] 或 [撤回][Bot.recall].
  *
@@ -55,6 +60,8 @@ import kotlin.jvm.JvmSynthetic
  *
  * @see OnlineMessageSource 在线消息的 [MessageSource]
  * @see OfflineMessageSource 离线消息的 [MessageSource]
+ *
+ * @see buildMessageSource 构造一个 [OfflineMessageSource]
  */
 sealed class MessageSource : Message, MessageMetadata, ConstrainSingle<MessageSource> {
     companion object Key : Message.Key<MessageSource> {
@@ -344,6 +351,10 @@ inline fun MessageChain.quote(): QuoteReply = QuoteReply(this.source)
 /**
  * 撤回这条消息. 可撤回自己 2 分钟内发出的消息, 和任意时间的群成员的消息.
  *
+ * **注意:** 仅从服务器接收的消息 (即来自 [MessageEvent.message]), 或手动添加了 [MessageSource] 元素的 [MessageChain] 才可以撤回.
+ *
+ * *提示: 若要撤回一条机器人自己发出的消息, 使用 [Contact.sendMessage] 返回的 [MessageReceipt] 中的 [MessageReceipt.recall]*
+ *
  * [Bot] 撤回自己的消息不需要权限.
  * [Bot] 撤回群员的消息需要管理员权限.
  *
@@ -376,55 +387,64 @@ inline fun MessageSource.recallIn(
 
 /**
  * 消息 id.
- * 仅从服务器接收的消息才可以获取
+ *
+ * 仅从服务器接收的消息 (即来自 [MessageEvent.message]), 或手动添加了 [MessageSource] 元素的 [MessageChain] 才可以获取消息源.
  *
  * @see MessageSource.id
  */
 @get:JvmSynthetic
-inline val MessageChain.id: Int
+val MessageChain.id: Int
     get() = this.source.id
 
 /**
  * 消息内部 id.
- * 仅从服务器接收的消息才可以获取
+ *
+ * 仅从服务器接收的消息 (即来自 [MessageEvent.message]), 或手动添加了 [MessageSource] 元素的 [MessageChain] 才可以获取消息源.
  *
  * @see MessageSource.id
  */
 @get:JvmSynthetic
-inline val MessageChain.internalId: Int
+val MessageChain.internalId: Int
     get() = this.source.internalId
 
 /**
  * 消息时间.
- * 仅从服务器接收的消息才可以获取
+ *
+ * 仅从服务器接收的消息 (即来自 [MessageEvent.message]), 或手动添加了 [MessageSource] 元素的 [MessageChain] 才可以获取消息源.
  *
  * @see MessageSource.id
  */
 @get:JvmSynthetic
-inline val MessageChain.time: Int
+val MessageChain.time: Int
     get() = this.source.time
 
 /**
  * 消息内部 id.
- * 仅从服务器接收的消息才可以获取
+ *
+ * 仅从服务器接收的消息 (即来自 [MessageEvent.message]), 或手动添加了 [MessageSource] 元素的 [MessageChain] 才可以获取. 否则将抛出异常 [NoSuchElementException]
  *
  * @see MessageSource.id
  */
 @get:JvmSynthetic
-inline val MessageChain.bot: Bot
+val MessageChain.bot: Bot
     get() = this.source.bot
 
 /**
- * 获取这条消息源
- * 仅从服务器接收的消息才可以获取消息源
+ * 获取这条消息的 [消息源][MessageSource].
+ *
+ * 仅从服务器接收的消息 (即来自 [MessageEvent.message]), 或手动添加了 [MessageSource] 元素的 [MessageChain] 才可以获取消息源, 否则将抛出异常 [NoSuchElementException]
  */
 @get:JvmSynthetic
-inline val MessageChain.source: MessageSource
+val MessageChain.source: MessageSource
     get() = this.getOrFail(MessageSource)
 
 /**
  * 撤回这条消息. 可撤回自己 2 分钟内发出的消息, 和任意时间的群成员的消息.
  *
+ * **注意:** 仅从服务器接收的消息 (即来自 [MessageEvent.message]), 或手动添加了 [MessageSource] 元素的 [MessageChain] 才可以撤回.
+ *
+ * *提示: 若要撤回一条机器人自己发出的消息, 使用 [Contact.sendMessage] 返回的 [MessageReceipt] 中的 [MessageReceipt.recall]*
+ *
  * [Bot] 撤回自己的消息不需要权限.
  * [Bot] 撤回群员的消息需要管理员权限.
  *
@@ -439,6 +459,10 @@ suspend inline fun MessageChain.recall() = this.source.recall()
 /**
  * 在一段时间后撤回这条消息. 可撤回自己 2 分钟内发出的消息, 和任意时间的群成员的消息.
  *
+ * **注意:** 仅从服务器接收的消息 (即来自 [MessageEvent.message]), 或手动添加了 [MessageSource] 元素的 [MessageChain] 才可以撤回.
+ *
+ * *提示: 若要撤回一条机器人自己发出的消息, 使用 [Contact.sendMessage] 返回的 [MessageReceipt] 中的 [MessageReceipt.recall]*
+ *
  * [Bot] 撤回自己的消息不需要权限.
  * [Bot] 撤回群员的消息需要管理员权限.
  *

mirai-core/src/commonMain/kotlin/net.mamoe.mirai/utils/ExternalImage.kt

@@ -15,11 +15,11 @@ import net.mamoe.mirai.contact.Contact
 import net.mamoe.mirai.contact.Group
 import net.mamoe.mirai.contact.User
 import net.mamoe.mirai.message.MessageReceipt
-import net.mamoe.mirai.message.data.Image
-import net.mamoe.mirai.message.data.sendTo
+import net.mamoe.mirai.message.data.*
 import net.mamoe.mirai.utils.internal.DeferredReusableInput
 import net.mamoe.mirai.utils.internal.ReusableInput
 import kotlin.jvm.JvmField
+import kotlin.jvm.JvmName
 import kotlin.jvm.JvmSynthetic
 
 /**
@@ -81,7 +81,10 @@ class ExternalImage internal constructor(
  */
 
 /**
- * 将图片作为单独的消息发送给指定联系人
+ * 将图片作为单独的消息发送给指定联系人.
+ *
+ * @see Contact.uploadImage 上传图片
+ * @see Contact.sendMessage 最终调用, 发送消息.
  */
 @JvmSynthetic
 suspend fun <C : Contact> ExternalImage.sendTo(contact: C): MessageReceipt<C> = when (contact) {
@@ -91,10 +94,12 @@ suspend fun <C : Contact> ExternalImage.sendTo(contact: C): MessageReceipt<C> =
 }
 
 /**
- * 上传图片并通过图片 ID 构造 [Image]
- * 这个函数可能需消耗一段时间
+ * 上传图片并构造 [Image].
+ * 这个函数可能需消耗一段时间.
+ *
+ * @param contact 图片上传对象. 由于好友图片与群图片不通用, 上传时必须提供目标联系人
  *
- * @see contact 图片上传对象. 由于好友图片与群图片不通用, 上传时必须提供目标联系人
+ * @see Contact.uploadImage 最终调用, 上传图片.
  */
 @JvmSynthetic
 suspend fun ExternalImage.upload(contact: Contact): Image = when (contact) {
@@ -105,6 +110,8 @@ suspend fun ExternalImage.upload(contact: Contact): Image = when (contact) {
 
 /**
  * 将图片作为单独的消息发送给 [this]
+ *
+ * @see Contact.sendMessage 最终调用, 发送消息.
  */
 @JvmSynthetic
 suspend inline fun <C : Contact> C.sendImage(image: ExternalImage): MessageReceipt<C> = image.sendTo(this)

mirai-core/src/jvmMain/kotlin/net/mamoe/mirai/utils/ExternalImageJvm.kt

@@ -13,6 +13,8 @@ package net.mamoe.mirai.utils
 
 import kotlinx.io.core.Input
 import net.mamoe.mirai.Bot
+import net.mamoe.mirai.message.data.Message
+import net.mamoe.mirai.message.data.MessageChain
 import net.mamoe.mirai.utils.internal.DeferredReusableInput
 import net.mamoe.mirai.utils.internal.asReusableInput
 import java.awt.image.BufferedImage
@@ -64,21 +66,26 @@ fun Input.toExternalImage(): ExternalImage = ExternalImage(DeferredReusableInput
 
 
 @PlannedRemoval("1.2.0")
+@Suppress("RedundantSuspendModifier")
 @Deprecated("no need", ReplaceWith("toExternalImage()"))
-fun Input.suspendToExternalImage(): ExternalImage = toExternalImage()
+suspend fun Input.suspendToExternalImage(): ExternalImage = toExternalImage()
 
+@Suppress("RedundantSuspendModifier")
 @PlannedRemoval("1.2.0")
 @Deprecated("no need", ReplaceWith("toExternalImage()"))
-fun InputStream.suspendToExternalImage(): ExternalImage = toExternalImage()
+suspend fun InputStream.suspendToExternalImage(): ExternalImage = toExternalImage()
 
+@Suppress("RedundantSuspendModifier")
 @PlannedRemoval("1.2.0")
 @Deprecated("no need", ReplaceWith("toExternalImage()"))
-fun URL.suspendToExternalImage(): ExternalImage = toExternalImage()
+suspend fun URL.suspendToExternalImage(): ExternalImage = toExternalImage()
 
+@Suppress("RedundantSuspendModifier")
 @PlannedRemoval("1.2.0")
 @Deprecated("no need", ReplaceWith("toExternalImage()"))
-fun File.suspendToExternalImage(): ExternalImage = toExternalImage()
+suspend fun File.suspendToExternalImage(): ExternalImage = toExternalImage()
 
+@Suppress("RedundantSuspendModifier")
 @PlannedRemoval("1.2.0")
 @Deprecated("no need", ReplaceWith("toExternalImage()"))
-fun BufferedImage.suspendToExternalImage(): ExternalImage = toExternalImage()
+suspend fun BufferedImage.suspendToExternalImage(): ExternalImage = toExternalImage()