Add docs

2025-01-03 01:39:35 +08:00 · 2020-05-28 13:43:35 +08:00 · 2020-05-28 13:43:35 +08:00 · 1d971badd9
commit 1d971badd9
parent 1f308b3018
7 changed files with 120 additions and 41 deletions
--- a/mirai-core/src/commonMain/kotlin/net.mamoe.mirai/Bot.kt
+++ b/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

 /**
--- a/mirai-core/src/commonMain/kotlin/net.mamoe.mirai/message/MessageEvent.kt
+++ b/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
 }

--- a/mirai-core/src/commonMain/kotlin/net.mamoe.mirai/message/MessageReceipt.kt
+++ b/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 {
--- a/mirai-core/src/commonMain/kotlin/net.mamoe.mirai/message/data/Image.kt
+++ b/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 已弃用 /////
--- a/mirai-core/src/commonMain/kotlin/net.mamoe.mirai/message/data/MessageSource.kt
+++ b/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] 撤回群员的消息需要管理员权限.
 *
--- a/mirai-core/src/commonMain/kotlin/net.mamoe.mirai/utils/ExternalImage.kt
+++ b/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].
+ * 这个函数可能需消耗一段时间.
 *
- * @see contact 图片上传对象. 由于好友图片与群图片不通用, 上传时必须提供目标联系人
+ * @param 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)
--- a/mirai-core/src/jvmMain/kotlin/net/mamoe/mirai/utils/ExternalImageJvm.kt
+++ b/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()