Rearrange `FlashImage`, add more docs

mirai-core-qqandroid/src/commonMain/kotlin/net/mamoe/mirai/qqandroid/contact/GroupImpl.kt

@@ -274,7 +274,7 @@ internal class GroupImpl(
     @OptIn(MiraiExperimentalAPI::class, LowLevelAPI::class)
     @JvmSynthetic
     override suspend fun sendMessage(message: Message): MessageReceipt<Group> {
-        check(!isBotMuted) { "bot is muted. Remaining seconds=$botMuteRemaining" }
+        check(!isBotMuted) { throw BotIsBeingMutedException(this) }
 
         val msg: MessageChain
 

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

-@file:Suppress("NOTHING_TO_INLINE", "unused")
-
-package net.mamoe.mirai.message.data
-
-import net.mamoe.mirai.utils.MiraiInternalAPI
-import net.mamoe.mirai.utils.SinceMirai
-import kotlin.jvm.JvmName
-import kotlin.jvm.JvmStatic
-import kotlin.jvm.JvmSynthetic
-
-/**
- * 闪照
- *
- * @see Image.flash
- */
-@SinceMirai("")
-sealed class FlashImage : MessageContent {
-    companion object Key : Message.Key<FlashImage> {
-        @JvmStatic
-        @JvmName("from")
-        operator fun invoke(image: Image): FlashImage {
-            @OptIn(MiraiInternalAPI::class)
-            return when (image) {
-                is GroupImage -> GroupFlashImage(image)
-                is FriendImage -> FriendFlashImage(image)
-                else -> throw IllegalArgumentException("不支持的图片类型(Please use GroupImage or FriendImage)")
-            }
-        }
-
-        @JvmStatic
-        @JvmName("from")
-        operator fun invoke(imageId: String): FlashImage {
-            return invoke(Image(imageId))
-        }
-    }
-
-    /**
-     * 闪照的图片, 不同于普通的图片.
-     */
-    abstract val image: Image
-
-    private var stringValue: String? = null
-        get() {
-            return field ?: kotlin.run {
-                field = "[mirai:flash:${image.imageId}]"
-                field
-            }
-        }
-
-    override fun toString(): String = stringValue!!
-    override val length: Int get() = stringValue!!.length
-    override fun get(index: Int) = stringValue!![index]
-    override fun subSequence(startIndex: Int, endIndex: Int) = stringValue!!.subSequence(startIndex, endIndex)
-    override fun compareTo(other: String) = other.compareTo(stringValue!!)
-}
-
-@JvmSynthetic
-inline fun Image.flash(): FlashImage = FlashImage(this)
-
-@JvmSynthetic
-inline fun GroupImage.flash(): GroupFlashImage = FlashImage(this) as GroupFlashImage
-
-@JvmSynthetic
-inline fun FriendImage.flash(): FriendFlashImage = FlashImage(this) as FriendFlashImage
-
-/**
- * @see FlashImage.invoke
- */
-class GroupFlashImage @MiraiInternalAPI constructor(override val image: GroupImage) : FlashImage() {
-    companion object Key : Message.Key<FlashImage>
-}
-
-/**
- * @see FlashImage.invoke
- */
-class FriendFlashImage @MiraiInternalAPI constructor(override val image: FriendImage) : FlashImage() {
-    companion object Key : Message.Key<FlashImage>
-}

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

@@ -7,7 +7,7 @@
  * https://github.com/mamoe/mirai/blob/master/LICENSE
  */
 
-@file:Suppress("unused")
+@file:Suppress("unused", "NOTHING_TO_INLINE")
 
 package net.mamoe.mirai.message.data
 
@@ -15,14 +15,28 @@ import net.mamoe.mirai.utils.MiraiExperimentalAPI
 import net.mamoe.mirai.utils.MiraiInternalAPI
 import net.mamoe.mirai.utils.SinceMirai
 import kotlin.jvm.JvmField
+import kotlin.jvm.JvmName
+import kotlin.jvm.JvmStatic
+import kotlin.jvm.JvmSynthetic
 
+/**
+ * 一些特殊的消息
+ *
+ * @see PokeMessage 戳一戳
+ * @see FlashImage 闪照
+ */
 @SinceMirai("0.31.0")
 sealed class HummerMessage : MessageContent {
     companion object Key : Message.Key<HummerMessage>
+    // has service type etc.
 }
 
+////////////////////////////////////////
+///////////// POKE MESSAGE /////////////
+////////////////////////////////////////
+
 /**
- * 戳一戳
+ * 戳一戳. 可以发送给好友或群.
  */
 @SinceMirai("0.31.0")
 @OptIn(MiraiInternalAPI::class)
@@ -73,3 +87,91 @@ class PokeMessage @MiraiInternalAPI(message = "使用伴生对象中的常量")
     //pbElem=08 01 18 00 20 FF FF FF FF 0F 2A 00 32 00 38 00 50 00
     //serviceType=0x00000002(2)
 }
+
+
+///////////////////////////////////////
+///////////// FLASH IMAGE /////////////
+///////////////////////////////////////
+
+
+/**
+ * 闪照
+ *
+ * @see Image.flash 转换普通图片为闪照
+ */
+@SinceMirai("0.33.0")
+sealed class FlashImage : MessageContent, HummerMessage() {
+    companion object Key : Message.Key<FlashImage> {
+        /**
+         * 将普通图片转换为闪照.
+         */
+        @JvmStatic
+        @JvmName("from")
+        operator fun invoke(image: Image): FlashImage {
+            @OptIn(MiraiInternalAPI::class)
+            return when (image) {
+                is GroupImage -> GroupFlashImage(image)
+                is FriendImage -> FriendFlashImage(image)
+                else -> throw IllegalArgumentException("不支持的图片类型(Please use GroupImage or FriendImage)")
+            }
+        }
+
+        /**
+         * 将普通图片转换为闪照.
+         *
+         * @param imageId 图片 id, 详见 [Image.imageId]
+         */
+        @JvmStatic
+        @JvmName("from")
+        operator fun invoke(imageId: String): FlashImage {
+            return invoke(Image(imageId))
+        }
+    }
+
+    /**
+     * 闪照的内容图片, 即一个普通图片.
+     */
+    abstract val image: Image
+
+    private var stringValue: String? = null
+        get() {
+            return field ?: kotlin.run {
+                field = "[mirai:flash:${image.imageId}]"
+                field
+            }
+        }
+
+    override fun toString(): String = stringValue!!
+    override val length: Int get() = stringValue!!.length
+    override fun get(index: Int) = stringValue!![index]
+    override fun subSequence(startIndex: Int, endIndex: Int) = stringValue!!.subSequence(startIndex, endIndex)
+    override fun compareTo(other: String) = other.compareTo(stringValue!!)
+}
+
+@JvmSynthetic
+@SinceMirai("0.33.0")
+inline fun Image.flash(): FlashImage = FlashImage(this)
+
+@JvmSynthetic
+@SinceMirai("0.33.0")
+inline fun GroupImage.flash(): GroupFlashImage = FlashImage(this) as GroupFlashImage
+
+@JvmSynthetic
+@SinceMirai("0.33.0")
+inline fun FriendImage.flash(): FriendFlashImage = FlashImage(this) as FriendFlashImage
+
+/**
+ * @see FlashImage.invoke
+ */
+@SinceMirai("0.33.0")
+class GroupFlashImage @MiraiInternalAPI constructor(override val image: GroupImage) : FlashImage() {
+    companion object Key : Message.Key<GroupFlashImage>
+}
+
+/**
+ * @see FlashImage.invoke
+ */
+@SinceMirai("0.33.0")
+class FriendFlashImage @MiraiInternalAPI constructor(override val image: FriendImage) : FlashImage() {
+    companion object Key : Message.Key<FriendFlashImage>
+}

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

@@ -28,16 +28,22 @@ import kotlin.jvm.JvmSynthetic
 
 /**
  * 自定义表情 (收藏的表情), 图片
+ *
+ * @see FlashImage 闪照
+ * @see Image.flash 转换普通图片为闪照
  */
 interface Image : Message, MessageContent {
     companion object Key : Message.Key<Image>
 
     /**
-     * 图片的 id. 只需要有这个 id 即可发送图片.
+     * 图片的 id.
+     * 图片 id 不一定会长时间保存, 因此不建议使用 id 发送图片.
      *
      * 示例:
      * 好友图片的 id: `/f8f1ab55-bf8e-4236-b55e-955848d7069f` 或 `/000000000-3814297509-BFB7027B9354B8F899A062061D74E206`
      * 群图片的 id: `{01E9451B-70ED-EAE3-B37C-101F1EEBF5B5}.png`
+     *
+     * @see Image 使用 id 构造图片
      */
     val imageId: String
 }
@@ -45,6 +51,7 @@ interface Image : Message, MessageContent {
 /**
  * 通过 [Image.imageId] 构造一个 [Image] 以便发送.
  * 这个图片必须是服务器已经存在的图片.
+ * 图片 id 不一定会长时间保存, 因此不建议使用 id 发送图片.
  *
  * 请查看 `ExternalImageJvm` 获取更多创建 [Image] 的方法
  */

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

@@ -52,6 +52,8 @@ import kotlin.jvm.JvmSynthetic
  * @see At 一个群成员的引用
  * @see AtAll 全体成员的引用
  * @see QuoteReply 一条消息的引用
+ * @see RichMessage 富文本消息, 如 [Xml][XmlMessage], [小程序][LightApp], [Json][JsonMessage]
+ * @see HummerMessage 一些特殊的消息, 如 [闪照][FlashImage], [戳一戳][PokeMessage]
  *
  * @see MessageChain 消息链(即 `List<Message>`)
  * @see CombinedMessage 链接的两个消息

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

@@ -111,7 +111,7 @@ interface RichMessage : MessageContent {
 /**
  * Json 消息.
  *
- * @see LightApp 一些消息实际上是 [LightApp]
+ * @see LightApp 一些 json 消息实际上是 [LightApp]
  */
 @SinceMirai("0.27.0")
 @OptIn(MiraiExperimentalAPI::class)
@@ -123,7 +123,9 @@ class JsonMessage(override val content: String) : RichMessage {
 }
 
 /**
- * 小程序, 如音乐分享
+ * 小程序, 如音乐分享.
+ *
+ * @param content 一般是 json
  */
 @OptIn(MiraiExperimentalAPI::class)
 @SinceMirai("0.27.0")
@@ -138,7 +140,7 @@ class LightApp constructor(override val content: String) : RichMessage {
 /**
  * XML 消息, 如分享, 卡片等.
  *
- * @see buildXmlMessage
+ * @see buildXmlMessage 使用 DSL 构造一个 XML 消息
  */
 @SinceMirai("0.27.0")
 @OptIn(MiraiExperimentalAPI::class)

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

@@ -52,6 +52,7 @@ inline fun buildMessageChain(
 
 /**
  * [MessageChain] 构建器.
+ * 多个连续的 [String] 会被连接为单个 [PlainText] 以优化性能.
  *
  * @see buildMessageChain 推荐使用
  * @see asMessageChain 完成构建