Improve docs

mirai-core/src/commonMain/kotlin/net.mamoe.mirai/event/Event.kt

@@ -46,7 +46,6 @@ interface Event {
      *
      * @see intercept 拦截事件
      */
-    @SinceMirai("1.0.0")
     val isIntercepted: Boolean
 
     /**
@@ -75,7 +74,6 @@ interface Event {
  *
  * 在使用事件时应使用类型 [Event]. 在实现自定义事件时应继承 [AbstractEvent].
  */
-@SinceMirai("1.0.0")
 abstract class AbstractEvent : Event {
     @Suppress("WRONG_MODIFIER_CONTAINING_DECLARATION", "PropertyName")
     @get:JvmSynthetic // so Java user won't see it
@@ -100,7 +98,6 @@ abstract class AbstractEvent : Event {
     /**
      * @see Event.intercept
      */
-    @SinceMirai("1.0.0")
     override fun intercept() {
         _intercepted = true
     }

mirai-core/src/commonMain/kotlin/net.mamoe.mirai/event/subscriber.kt

@@ -26,7 +26,6 @@ import net.mamoe.mirai.event.events.BotEvent
 import net.mamoe.mirai.event.internal.Handler
 import net.mamoe.mirai.event.internal.subscribeInternal
 import net.mamoe.mirai.utils.MiraiLogger
-import net.mamoe.mirai.utils.SinceMirai
 import kotlin.coroutines.CoroutineContext
 import kotlin.coroutines.EmptyCoroutineContext
 import kotlin.internal.LowPriorityInOverloadResolution
@@ -97,7 +96,6 @@ interface Listener<in E : Event> : CompletableJob {
      *
      * 当事件被 [拦截][Event.intercept] 后, 优先级较低 (靠右) 的监听器将不会被调用.
      */
-    @SinceMirai("1.0.0")
     enum class EventPriority {
 
         HIGHEST, HIGH, NORMAL, LOW, LOWEST,

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

@@ -14,7 +14,6 @@
 package net.mamoe.mirai.message.data
 
 import net.mamoe.mirai.utils.PlannedRemoval
-import net.mamoe.mirai.utils.SinceMirai
 import kotlin.jvm.JvmMultifileClass
 import kotlin.jvm.JvmName
 import kotlin.jvm.JvmSynthetic
@@ -25,7 +24,6 @@ import kotlin.jvm.JvmSynthetic
  * 一般不需要主动构造 [PlainText], [Message] 可直接与 [String] 相加. Java 用户请使用 [Message.plus]
  */
 data class PlainText(
-    @SinceMirai("1.0.0")
     val content: String
 ) : MessageContent {
 

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

@@ -29,10 +29,16 @@ open class BotConfiguration {
     /** 日志记录器 */
     var botLoggerSupplier: ((Bot) -> MiraiLogger) = { DefaultLogger("Bot(${it.id})") }
 
-    /** 网络层日志构造器 */
+    /**
+     * 网络层日志构造器
+     * @see noNetworkLog 不显示网络日志
+     */
     var networkLoggerSupplier: ((BotNetworkHandler) -> MiraiLogger) = { DefaultLogger("Network(${it.bot.id})") }
 
-    /** 设备信息覆盖. 默认使用随机的设备信息. */
+    /**
+     * 设备信息覆盖. 默认使用随机的设备信息.
+     * @see fileBasedDeviceInfo 使用文件
+     */
     var deviceInfo: ((Context) -> DeviceInfo)? = null
 
     /** 父 [CoroutineContext]. [Bot] 创建后会使用 [SupervisorJob] 覆盖其 [Job], 但会将这个 [Job] 作为父 [Job] */
@@ -60,7 +66,6 @@ open class BotConfiguration {
     var loginSolver: LoginSolver = LoginSolver.Default
 
     /** 使用协议类型 */
-    @SinceMirai("1.0.0")
     var protocol: MiraiProtocol = MiraiProtocol.ANDROID_PAD
 
     /** 缓存策略  */
@@ -68,7 +73,6 @@ open class BotConfiguration {
     @MiraiExperimentalAPI
     var fileCacheStrategy: FileCacheStrategy = FileCacheStrategy.PlatformDefault
 
-    @SinceMirai("1.0.0")
     enum class MiraiProtocol(
         /** 协议模块使用的 ID */
         @JvmField internal val id: Long
@@ -107,12 +111,13 @@ open class BotConfiguration {
     /**
      * 使用文件存储设备信息
      *
-     * 此函数只在 JVM 有效. 在其他平台将会导致一直使用默认的随机的设备信息.
+     * 此函数只在 JVM 和 Android 有效. 在其他平台将会抛出异常.
+     * @param filepath 文件路径. 可相对于程序运行路径 (`user.dir`), 也可以是绝对路径.
      */
     @ConfigurationDsl
     @JvmOverloads
-    fun fileBasedDeviceInfo(filename: String = "device.json") {
-        deviceInfo = getFileBasedDeviceInfoSupplier(filename)
+    fun fileBasedDeviceInfo(filepath: String = "device.json") {
+        deviceInfo = getFileBasedDeviceInfoSupplier(filepath)
     }
 
     /**
@@ -177,7 +182,6 @@ open class BotConfiguration {
     @DslMarker
     annotation class ConfigurationDsl
 
-    @SinceMirai("1.0.0")
     fun copy(): BotConfiguration {
         return BotConfiguration().also { new ->
             new.botLoggerSupplier = botLoggerSupplier

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

@@ -26,8 +26,8 @@ import kotlin.jvm.JvmOverloads
  * **注意:** 请务必将所有的输出定向到日志记录系统, 否则在某些情况下 (如 web 控制台中) 将无法接收到输出
  *
  * **注意:** 请为日志做好分类, 即不同的模块使用不同的 [MiraiLogger].
- * 如, [Bot] 中使用 identity 为 "Bot(qqId)" 的 [MiraiLogger]
- * 而 [Bot] 的网络处理中使用 identity 为 "BotNetworkHandler" 的.
+ * 如, [Bot] 中使用 `identity` 为 "Bot(qqId)" 的 [MiraiLogger]
+ * 而 [Bot] 的网络处理中使用 `identity` 为 "BotNetworkHandler".
  *
  * Java 调用: `Utils.getDefaultLogger().invoke(identity)`
  */
@@ -35,7 +35,6 @@ var DefaultLogger: (identity: String?) -> MiraiLogger = { PlatformLogger(it) }
 
 /**
  * 给这个 logger 添加一个开关, 用于控制是否记录 log
- *
  */
 @JvmOverloads
 fun MiraiLogger.withSwitch(default: Boolean = true): MiraiLoggerWithSwitch = MiraiLoggerWithSwitch(this, default)
@@ -54,7 +53,7 @@ fun MiraiLogger.withSwitch(default: Boolean = true): MiraiLoggerWithSwitch = Mir
  * @see PlatformLogger 各个平台下的默认日志记录实现.
  * @see SilentLogger 忽略任何日志记录操作的 logger 实例.
  *
- * @see MiraiLoggerPlatformBase 平台通用基础实现. 若
+ * @see MiraiLoggerPlatformBase 平台通用基础实现. 若 Mirai 自带的日志系统无法满足需求, 请继承这个类并实现其抽象函数.
  */
 interface MiraiLogger {
     /**
@@ -88,10 +87,10 @@ interface MiraiLogger {
      * [follower] 的存在可以让一次日志被多个日志记录器记录.
      *
      * 一般不建议直接修改这个属性. 请通过 [plus] 来连接两个日志记录器.
-     * 如: `val logger = bot.logger + MyOwnLogger()`
-     * 这样, 当调用 `logger.info()` 时, bot.logger 会首先记录, MyOwnLogger 会随后记录.
+     * 如: `val logger = bot.logger + MyLogger()`
+     * 当调用 `logger.info()` 时, `bot.logger` 会首先记录, `MyLogger` 会随后记录.
      *
-     * 当然, 多个 logger 也可以加在一起: `val logger = bot.logger + MyOwnLogger() + MyOwnLogger2()`
+     * 当然, 多个 logger 也可以加在一起: `val logger = bot.logger + MynLogger() + MyLogger2()`
      */
     var follower: MiraiLogger?
 
@@ -208,7 +207,7 @@ inline fun MiraiLogger.error(lazyMessage: () -> String?, e: Throwable?) {
  * 在 _JVM 控制台_ 端的实现为 [println]
  * 在 _Android_ 端的实现为 `android.util.Log`
  *
- * 不应该直接构造这个类的实例. 请使用 [DefaultLogger], 或使用默认的顶层日志记录 [MiraiLogger.Companion]
+ * 不应该直接构造这个类的实例. 请使用 [DefaultLogger]
  */
 expect open class PlatformLogger @JvmOverloads constructor(identity: String? = "Mirai") : MiraiLoggerPlatformBase
 
@@ -225,6 +224,12 @@ object SilentLogger : PlatformLogger() {
     override fun warning0(message: String?) = Unit
     override fun verbose0(message: String?) = Unit
     override fun info0(message: String?) = Unit
+
+    override fun verbose0(message: String?, e: Throwable?) = Unit
+    override fun debug0(message: String?, e: Throwable?) = Unit
+    override fun info0(message: String?, e: Throwable?) = Unit
+    override fun warning0(message: String?, e: Throwable?) = Unit
+    override fun error0(message: String?, e: Throwable?) = Unit
 }
 
 /**

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

 package net.mamoe.mirai.utils.internal
 
 import io.ktor.utils.io.ByteWriteChannel
-import net.mamoe.mirai.utils.SinceMirai
 
-@SinceMirai("1.0.0")
 internal interface ReusableInput {
     val md5: ByteArray
     val size: Long

mirai-core/src/jvmMain/kotlin/net/mamoe/mirai/event/JvmMethodListeners.kt

@@ -52,6 +52,20 @@ import kotlin.reflect.jvm.kotlinFunction
  * fun T.onEvent(): ListeningStatus
  * ```
  *
+ * 使用示例:
+ * ```
+ * class MyEvents : ListenerHost {
+ *     @EventHandler
+ *     suspend fun MessageEvent.onMessage() {
+ *         reply("received")
+ *     }
+ * }
+ *
+ * MyEvents.registerEvents(CoroutineExceptionHandler { _, e -> println("Caught exception: $e") })
+ * // CoroutineExceptionHandler 可处理 MyEvents 的所有 @EventHandler 函数中未捕获的异常.
+ * // 也可以不提供 CoroutineExceptionHandler: MyEvents.registerEvents()
+ * ```
+ *
  * ### Java 方法
  * 所有 Java 方法都会在 [Dispatchers.IO] 中调用.
  *
@@ -61,6 +75,20 @@ import kotlin.reflect.jvm.kotlinFunction
  * ListeningStatus onEvent(T)
  * ```
  *
+ * 使用示例:
+ * ```
+ * class MyEvents : ListenerHost {
+ *     @EventHandler
+ *     suspend fun MessageEvent.onMessage() {
+ *         reply("received")
+ *     }
+ * }
+ *
+ * MyEvents.registerEvents(CoroutineExceptionHandler { _, e -> println("Caught exception: $e") })
+ * // CoroutineExceptionHandler 可处理 MyEvents 的所有 @EventHandler 函数中未捕获的异常.
+ * // 也可以不提供 CoroutineExceptionHandler: MyEvents.registerEvents()
+ * ```
+ *
  * @sample net.mamoe.mirai.event.JvmMethodEventsTest
  */
 @Target(AnnotationTarget.FUNCTION)
@@ -111,7 +139,6 @@ fun CoroutineScope.registerEvents(host: ListenerHost, coroutineContext: Coroutin
 }
 
 
-
 @Suppress("UNCHECKED_CAST")
 private fun Method.registerEvent(
     owner: Any,