diff --git a/mirai-core/src/commonMain/kotlin/net.mamoe.mirai/event/Event.kt b/mirai-core/src/commonMain/kotlin/net.mamoe.mirai/event/Event.kt index 8328f73d6..942d0cf1d 100644 --- a/mirai-core/src/commonMain/kotlin/net.mamoe.mirai/event/Event.kt +++ b/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 } diff --git a/mirai-core/src/commonMain/kotlin/net.mamoe.mirai/event/subscriber.kt b/mirai-core/src/commonMain/kotlin/net.mamoe.mirai/event/subscriber.kt index 2db5a8635..0d26c0709 100644 --- a/mirai-core/src/commonMain/kotlin/net.mamoe.mirai/event/subscriber.kt +++ b/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 : CompletableJob { * * 当事件被 [拦截][Event.intercept] 后, 优先级较低 (靠右) 的监听器将不会被调用. */ - @SinceMirai("1.0.0") enum class EventPriority { HIGHEST, HIGH, NORMAL, LOW, LOWEST, diff --git a/mirai-core/src/commonMain/kotlin/net.mamoe.mirai/message/data/PlainText.kt b/mirai-core/src/commonMain/kotlin/net.mamoe.mirai/message/data/PlainText.kt index a3bea897e..c278cea48 100644 --- a/mirai-core/src/commonMain/kotlin/net.mamoe.mirai/message/data/PlainText.kt +++ b/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 { diff --git a/mirai-core/src/commonMain/kotlin/net.mamoe.mirai/utils/BotConfiguration.kt b/mirai-core/src/commonMain/kotlin/net.mamoe.mirai/utils/BotConfiguration.kt index 16104b1e8..d3fc4cd14 100644 --- a/mirai-core/src/commonMain/kotlin/net.mamoe.mirai/utils/BotConfiguration.kt +++ b/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 diff --git a/mirai-core/src/commonMain/kotlin/net.mamoe.mirai/utils/MiraiLogger.kt b/mirai-core/src/commonMain/kotlin/net.mamoe.mirai/utils/MiraiLogger.kt index 82c19fec2..8f7f295c5 100644 --- a/mirai-core/src/commonMain/kotlin/net.mamoe.mirai/utils/MiraiLogger.kt +++ b/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 } /** diff --git a/mirai-core/src/commonMain/kotlin/net.mamoe.mirai/utils/internal/ReusableInput.kt b/mirai-core/src/commonMain/kotlin/net.mamoe.mirai/utils/internal/ReusableInput.kt index 9eab67eb4..3f560243f 100644 --- a/mirai-core/src/commonMain/kotlin/net.mamoe.mirai/utils/internal/ReusableInput.kt +++ b/mirai-core/src/commonMain/kotlin/net.mamoe.mirai/utils/internal/ReusableInput.kt @@ -1,9 +1,7 @@ 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 diff --git a/mirai-core/src/jvmMain/kotlin/net/mamoe/mirai/event/JvmMethodListeners.kt b/mirai-core/src/jvmMain/kotlin/net/mamoe/mirai/event/JvmMethodListeners.kt index 3cdf7da9d..2992bea12 100644 --- a/mirai-core/src/jvmMain/kotlin/net/mamoe/mirai/event/JvmMethodListeners.kt +++ b/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,