From 2bcd1a7a7da80277342c04e706a91ae421cecf7d Mon Sep 17 00:00:00 2001 From: Him188 Date: Thu, 28 May 2020 13:43:35 +0800 Subject: [PATCH] Add docs --- .../commonMain/kotlin/net.mamoe.mirai/Bot.kt | 12 ++--- .../net.mamoe.mirai/message/MessageEvent.kt | 13 +++-- .../net.mamoe.mirai/message/MessageReceipt.kt | 36 +++++++++++-- .../net.mamoe.mirai/message/data/Image.kt | 14 ++++-- .../message/data/MessageSource.kt | 50 ++++++++++++++----- .../net.mamoe.mirai/utils/ExternalImage.kt | 19 ++++--- .../net/mamoe/mirai/utils/ExternalImageJvm.kt | 17 +++++-- 7 files changed, 120 insertions(+), 41 deletions(-) diff --git a/mirai-core/src/commonMain/kotlin/net.mamoe.mirai/Bot.kt b/mirai-core/src/commonMain/kotlin/net.mamoe.mirai/Bot.kt index 9fe0eaa0d..348b2b999 100644 --- a/mirai-core/src/commonMain/kotlin/net.mamoe.mirai/Bot.kt +++ b/mirai-core/src/commonMain/kotlin/net.mamoe.mirai/Bot.kt @@ -209,13 +209,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) @@ -242,7 +242,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, @@ -345,7 +345,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 /** diff --git a/mirai-core/src/commonMain/kotlin/net.mamoe.mirai/message/MessageEvent.kt b/mirai-core/src/commonMain/kotlin/net.mamoe.mirai/message/MessageEvent.kt index 4c71d02b3..ab0325413 100644 --- 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 } diff --git a/mirai-core/src/commonMain/kotlin/net.mamoe.mirai/message/MessageReceipt.kt b/mirai-core/src/commonMain/kotlin/net.mamoe.mirai/message/MessageReceipt.kt index 160d525ab..ca78c801f 100644 --- 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( +open class MessageReceipt @MiraiExperimentalAPI("The constructor is subject to change.") constructor( /** * 指代发送出去的消息. */ @@ -51,38 +51,68 @@ open class MessageReceipt( */ 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 { return runBlocking { return@runBlocking quoteReply(message) } } + /** + * 引用这条消息并回复. + * + * 仅供 Java 使用: `MessageReceipt.quoteReply(message)` + */ @JavaFriendlyAPI @JvmName("quoteReply") fun __quoteReplyBlockingForJava__(message: String): MessageReceipt { 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 { diff --git 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 index bc9d55110..e72a2b078 100644 --- 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 @@ -196,8 +197,8 @@ fun Image(imageId: String): OfflineImage = when { /** * 查询原图下载链接. * - * 当图片为从服务器接收的消息中的图片时, 可以直接获取下载链接, 本函数不会挂起协程. - * 其他情况下协程可能会挂起并向服务器查询下载链接, 或不挂起并拼接一个链接. + * - 当图片为从服务器接收的消息中的图片时, 可以直接获取下载链接, 本函数不会挂起协程. + * - 其他情况下协程可能会挂起并向服务器查询下载链接, 或不挂起并拼接一个链接. * * @return 原图 HTTP 下载链接 (非 HTTPS) * @throws IllegalStateException 当无任何 [Bot] 在线时抛出 (因为无法获取相关协议) @@ -206,12 +207,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 已弃用 ///// diff --git 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 index 02e43c8eb..032ed4878 100644 --- 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 { companion object Key : Message.Key { @@ -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] 撤回群员的消息需要管理员权限. * diff --git a/mirai-core/src/commonMain/kotlin/net.mamoe.mirai/utils/ExternalImage.kt b/mirai-core/src/commonMain/kotlin/net.mamoe.mirai/utils/ExternalImage.kt index 478894308..679692180 100644 --- 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 ExternalImage.sendTo(contact: C): MessageReceipt = when (contact) { @@ -91,10 +94,12 @@ suspend fun ExternalImage.sendTo(contact: C): MessageReceipt = } /** - * 上传图片并通过图片 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.sendImage(image: ExternalImage): MessageReceipt = image.sendTo(this) diff --git a/mirai-core/src/jvmMain/kotlin/net/mamoe/mirai/utils/ExternalImageJvm.kt b/mirai-core/src/jvmMain/kotlin/net/mamoe/mirai/utils/ExternalImageJvm.kt index 52ce17c6c..d9f1b5ea4 100644 --- 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()