mirror of
https://github.com/mamoe/mirai.git
synced 2025-01-03 01:14:44 +08:00
Improve docs
This commit is contained in:
Him188
parent
90e78e4bf1
commit
f5db6e0201
@ -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
|
||||
}
|
||||
|
||||
@ -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,
|
||||
|
||||
@ -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 {
|
||||
|
||||
|
||||
@ -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
|
||||
|
||||
@ -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
|
||||
}
|
||||
|
||||
/**
|
||||
|
||||
@ -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
|
||||
|
||||
@ -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,
|
||||
|
||||
Loading…
Reference in New Issue
Block a user