1.0-RC Code review

backend/mirai-console/src/main/kotlin/net/mamoe/mirai/console/MiraiConsoleImplementation.kt

@@ -47,7 +47,7 @@ public annotation class ConsoleFrontEndImplementation
 /**
  * 实现 [MiraiConsole] 的接口
  *
- * **注意**: 随着 Console 的更新, 在版本号 `x.y.z` 的 `y` 修改时此接口可能就会变动. 意味着前端实现着需要跟随 Console 更新.
+ * **注意**: 随着 Console 的更新, 在版本号 `x.y.z` 的 `y` 修改时此接口可能就会发生 ABI 变动. 意味着前端实现着需要跟随 Console 更新.
  *
  * @see MiraiConsoleImplementation.start 启动
  */

backend/mirai-console/src/main/kotlin/net/mamoe/mirai/console/command/AbstractCommand.kt

@@ -7,9 +7,12 @@
  * https://github.com/mamoe/mirai/blob/master/LICENSE
  */
 
+@file:Suppress("unused")
+
 package net.mamoe.mirai.console.command
 
-import net.mamoe.mirai.console.internal.command.createOrFindCommandPermission
+import net.mamoe.mirai.console.command.descriptor.ExperimentalCommandDescriptors
+import net.mamoe.mirai.console.internal.command.findOrCreateCommandPermission
 import net.mamoe.mirai.console.permission.Permission
 
 /**
@@ -26,14 +29,17 @@ public abstract class AbstractCommand
     public final override val secondaryNames: Array<out String>,
     public override val description: String = "<no description available>",
     parentPermission: Permission = owner.parentPermission,
-    /** 为 `true` 时表示 [指令前缀][CommandManager.commandPrefix] 可选 */
-    public override val prefixOptional: Boolean = false,
 ) : Command {
+
+    @ExperimentalCommandDescriptors
+    override val prefixOptional: Boolean
+        get() = false
+
     init {
         Command.checkCommandName(primaryName)
         secondaryNames.forEach(Command.Companion::checkCommandName)
     }
 
     public override val usage: String get() = description
-    public override val permission: Permission by lazy { createOrFindCommandPermission(parentPermission) }
+    public override val permission: Permission by lazy { findOrCreateCommandPermission(parentPermission) }
 }

backend/mirai-console/src/main/kotlin/net/mamoe/mirai/console/command/Command.kt

@@ -77,6 +77,9 @@ public interface Command {
      * 为 `true` 时表示 [指令前缀][CommandManager.commandPrefix] 可选.
      *
      * 会影响聊天语境中的解析.
+     *
+     * #### 实验性 API
+     * 由于指令解析允许被扩展, 此属性可能不适用所有解析器, 因此还未决定是否保留.
      */
     @ExperimentalCommandDescriptors
     @ConsoleExperimentalApi

backend/mirai-console/src/main/kotlin/net/mamoe/mirai/console/command/CommandExecuteResult.kt

@@ -21,6 +21,8 @@ import kotlin.contracts.contract
 /**
  * 指令的执行返回
  *
+ * 注意: 现阶段
+ *
  * @see CommandExecuteStatus
  */
 @ConsoleExperimentalApi("Not yet implemented")
@@ -144,12 +146,14 @@ public sealed class CommandExecuteResult {
     }
 }
 
+@ExperimentalCommandDescriptors
 @Suppress("RemoveRedundantQualifierName")
 public typealias CommandExecuteStatus = CommandExecuteResult.CommandExecuteStatus
 
 /**
  * 当 [this] 为 [CommandExecuteResult.Success] 时返回 `true`
  */
+@ExperimentalCommandDescriptors
 @JvmSynthetic
 public fun CommandExecuteResult.isSuccess(): Boolean {
     contract {
@@ -162,6 +166,7 @@ public fun CommandExecuteResult.isSuccess(): Boolean {
 /**
  * 当 [this] 为 [CommandExecuteResult.IllegalArgument] 时返回 `true`
  */
+@ExperimentalCommandDescriptors
 @JvmSynthetic
 public fun CommandExecuteResult.isIllegalArgument(): Boolean {
     contract {
@@ -174,6 +179,7 @@ public fun CommandExecuteResult.isIllegalArgument(): Boolean {
 /**
  * 当 [this] 为 [CommandExecuteResult.ExecutionFailed] 时返回 `true`
  */
+@ExperimentalCommandDescriptors
 @JvmSynthetic
 public fun CommandExecuteResult.isExecutionException(): Boolean {
     contract {
@@ -186,6 +192,7 @@ public fun CommandExecuteResult.isExecutionException(): Boolean {
 /**
  * 当 [this] 为 [CommandExecuteResult.PermissionDenied] 时返回 `true`
  */
+@ExperimentalCommandDescriptors
 @JvmSynthetic
 public fun CommandExecuteResult.isPermissionDenied(): Boolean {
     contract {
@@ -198,6 +205,7 @@ public fun CommandExecuteResult.isPermissionDenied(): Boolean {
 /**
  * 当 [this] 为 [CommandExecuteResult.UnresolvedCall] 时返回 `true`
  */
+@ExperimentalCommandDescriptors
 @JvmSynthetic
 public fun CommandExecuteResult.isCommandNotFound(): Boolean {
     contract {
@@ -210,6 +218,7 @@ public fun CommandExecuteResult.isCommandNotFound(): Boolean {
 /**
  * 当 [this] 为 [CommandExecuteResult.ExecutionFailed], [CommandExecuteResult.IllegalArgument] 或 [CommandExecuteResult.UnresolvedCall] 时返回 `true`
  */
+@ExperimentalCommandDescriptors
 @JvmSynthetic
 public fun CommandExecuteResult.isFailure(): Boolean {
     contract {

backend/mirai-console/src/main/kotlin/net/mamoe/mirai/console/command/CommandExecutionException.kt

@@ -11,10 +11,8 @@
 
 package net.mamoe.mirai.console.command
 
-import net.mamoe.mirai.console.command.CommandManager.INSTANCE.executeCommand
-
 /**
- * 在 [CommandManager.executeCommand] 中, [Command.onCommand] 抛出异常时包装的异常.
+ * 在 [CommandManager.executeCommand] 中抛出异常时包装的异常.
  */
 public class CommandExecutionException(
     /**
@@ -29,7 +27,7 @@ public class CommandExecutionException(
      * 匹配到的指令名
      */
     public val name: String,
-    cause: Throwable
+    cause: Throwable,
 ) : RuntimeException(
     "Exception while executing command '${command.primaryName}'",
     cause

backend/mirai-console/src/main/kotlin/net/mamoe/mirai/console/command/CommandOwner.kt

@@ -9,7 +9,6 @@
 
 package net.mamoe.mirai.console.command
 
-import net.mamoe.mirai.console.command.CommandManager.INSTANCE.unregisterAllCommands
 import net.mamoe.mirai.console.compiler.common.ResolveContext
 import net.mamoe.mirai.console.compiler.common.ResolveContext.Kind.PERMISSION_NAME
 import net.mamoe.mirai.console.permission.Permission
@@ -34,11 +33,13 @@ public interface CommandOwner : PermissionIdNamespace {
 
 /**
  * 代表控制台所有者. 所有的 mirai-console 内建的指令都属于 [ConsoleCommandOwner].
+ *
+ * 插件注册指令时不应该使用 [ConsoleCommandOwner].
  */
-internal object ConsoleCommandOwner : CommandOwner {
+public object ConsoleCommandOwner : CommandOwner {
-    override val parentPermission: Permission get() = BuiltInCommands.parentPermission
+    public override val parentPermission: Permission get() = BuiltInCommands.parentPermission
 
-    override fun permissionId(
+    public override fun permissionId(
         @ResolveContext(PERMISSION_NAME) name: String,
     ): PermissionId = PermissionId("console", name)
 }

backend/mirai-console/src/main/kotlin/net/mamoe/mirai/console/command/CommandPermissionDeniedException.kt

@@ -9,8 +9,6 @@
 
 package net.mamoe.mirai.console.command
 
-import net.mamoe.mirai.console.command.CommandManager.INSTANCE.executeCommand
-
 /**
  * 在 [CommandManager.executeCommand] 中, [CommandSender] 未拥有 [Command.permission] 所要求的权限时抛出的异常.
  *
@@ -24,7 +22,7 @@ public class CommandPermissionDeniedException(
     /**
      * 执行过程发生异常的指令
      */
-    public val command: Command
+    public val command: Command,
 ) : RuntimeException("Permission denied while executing command '${command.primaryName}'") {
     public override fun toString(): String =
         "CommandPermissionDeniedException(command=$command)"

backend/mirai-console/src/main/kotlin/net/mamoe/mirai/console/command/CompositeCommand.kt

@@ -87,9 +87,8 @@ public abstract class CompositeCommand(
     @ResolveContext(COMMAND_NAME) vararg secondaryNames: String,
     description: String = "no description available",
     parentPermission: Permission = owner.parentPermission,
-    prefixOptional: Boolean = false,
     overrideContext: CommandArgumentContext = EmptyCommandArgumentContext,
-) : Command, AbstractCommand(owner, primaryName, secondaryNames = secondaryNames, description, parentPermission, prefixOptional),
+) : Command, AbstractCommand(owner, primaryName, secondaryNames = secondaryNames, description, parentPermission),
     CommandArgumentContextAware {
 
     private val reflector by lazy { CommandReflector(this, CompositeCommandSubCommandAnnotationResolver) }

backend/mirai-console/src/main/kotlin/net/mamoe/mirai/console/command/RawCommand.kt

@@ -15,7 +15,7 @@ import net.mamoe.mirai.console.command.descriptor.*
 import net.mamoe.mirai.console.command.java.JRawCommand
 import net.mamoe.mirai.console.compiler.common.ResolveContext
 import net.mamoe.mirai.console.compiler.common.ResolveContext.Kind.COMMAND_NAME
-import net.mamoe.mirai.console.internal.command.createOrFindCommandPermission
+import net.mamoe.mirai.console.internal.command.findOrCreateCommandPermission
 import net.mamoe.mirai.console.internal.data.typeOf0
 import net.mamoe.mirai.console.permission.Permission
 import net.mamoe.mirai.message.data.Message
@@ -53,7 +53,7 @@ public abstract class RawCommand(
     @OptIn(ExperimentalCommandDescriptors::class)
     public override val prefixOptional: Boolean = false,
 ) : Command {
-    public override val permission: Permission by lazy { createOrFindCommandPermission(parentPermission) }
+    public override val permission: Permission by lazy { findOrCreateCommandPermission(parentPermission) }
 
     @ExperimentalCommandDescriptors
     override val overloads: List<CommandSignature> = listOf(

backend/mirai-console/src/main/kotlin/net/mamoe/mirai/console/command/SimpleCommand.kt

@@ -58,9 +58,8 @@ public abstract class SimpleCommand(
     @ResolveContext(COMMAND_NAME) vararg secondaryNames: String,
     description: String = "no description available",
     parentPermission: Permission = owner.parentPermission,
-    prefixOptional: Boolean = false,
     overrideContext: CommandArgumentContext = EmptyCommandArgumentContext,
-) : Command, AbstractCommand(owner, primaryName, secondaryNames = secondaryNames, description, parentPermission, prefixOptional),
+) : Command, AbstractCommand(owner, primaryName, secondaryNames = secondaryNames, description, parentPermission),
     CommandArgumentContextAware {
 
     private val reflector by lazy { CommandReflector(this, SimpleCommandSubCommandAnnotationResolver) }

backend/mirai-console/src/main/kotlin/net/mamoe/mirai/console/command/java/JRawCommand.kt

@@ -16,7 +16,7 @@ import net.mamoe.mirai.console.command.CommandOwner
 import net.mamoe.mirai.console.command.descriptor.ExperimentalCommandDescriptors
 import net.mamoe.mirai.console.compiler.common.ResolveContext
 import net.mamoe.mirai.console.compiler.common.ResolveContext.Kind.COMMAND_NAME
-import net.mamoe.mirai.console.internal.command.createOrFindCommandPermission
+import net.mamoe.mirai.console.internal.command.findOrCreateCommandPermission
 import net.mamoe.mirai.console.permission.Permission
 
 /**
@@ -65,7 +65,7 @@ public abstract class JRawCommand
         protected set
 
     /** 指令权限 */
-    public final override var permission: Permission = createOrFindCommandPermission(parentPermission)
+    public final override var permission: Permission = findOrCreateCommandPermission(parentPermission)
         protected set
 
     /** 为 `true` 时表示 [指令前缀][CommandManager.commandPrefix] 可选 */

backend/mirai-console/src/main/kotlin/net/mamoe/mirai/console/data/AbstractPluginData.kt

@@ -23,6 +23,9 @@ import kotlin.reflect.KProperty
 /**
  * [PluginData] 的默认实现. 支持使用 `by value()` 等委托方法创建 [Value] 并跟踪其改动.
  *
+ * ### 实现注意
+ * 此类型处于实验性阶段. 使用其中定义的属性和函数是安全的, 但将来可能会新增成员抽象函数.
+ *
  * @see PluginData
  */
 public abstract class AbstractPluginData : PluginData, PluginDataImpl() {

backend/mirai-console/src/main/kotlin/net/mamoe/mirai/console/data/AutoSavePluginConfig.kt

@@ -23,10 +23,4 @@ import kotlinx.coroutines.Job
  * @see PluginConfig
  * @see AutoSavePluginData
  */
-public open class AutoSavePluginConfig : AutoSavePluginData, PluginConfig {
+public open class AutoSavePluginConfig public constructor(saveName: String) : AutoSavePluginData(saveName), PluginConfig
-    @Deprecated("请手动指定保存名称. 此构造器将在 1.0.0 删除", level = DeprecationLevel.ERROR, replaceWith = ReplaceWith("AutoSavePluginConfig(\"把我改成保存名称\")"))
-    @Suppress("DEPRECATION_ERROR")
-    public constructor() : super()
-
-    public constructor(saveName: String) : super(saveName)
-}

backend/mirai-console/src/main/kotlin/net/mamoe/mirai/console/data/AutoSavePluginData.kt

@@ -18,7 +18,6 @@ import net.mamoe.mirai.console.internal.data.qualifiedNameOrTip
 import net.mamoe.mirai.console.internal.plugin.updateWhen
 import net.mamoe.mirai.console.util.ConsoleExperimentalApi
 import net.mamoe.mirai.utils.*
-import kotlin.reflect.full.findAnnotation
 
 /**
  * 链接自动保存的 [PluginData].
@@ -46,14 +45,6 @@ public open class AutoSavePluginData private constructor(
         _saveName = saveName
     }
 
-    @Deprecated("请手动指定保存名称. 此构造器将在 1.0.0 删除", level = DeprecationLevel.ERROR, replaceWith = ReplaceWith("AutoSavePluginData(\"把我改成保存名称\")"))
-    public constructor() : this(null) {
-        val clazz = this::class
-        _saveName = clazz.findAnnotation<ValueName>()?.value
-            ?: clazz.qualifiedName
-                ?: throw IllegalArgumentException("Cannot find a serial name for ${this::class}")
-    }
-
     @ConsoleExperimentalApi
     override fun onInit(owner: PluginDataHolder, storage: PluginDataStorage) {
         check(owner is AutoSavePluginDataHolder) { "owner must be AutoSavePluginDataHolder for AutoSavePluginData" }

backend/mirai-console/src/main/kotlin/net/mamoe/mirai/console/data/PluginData.kt

@@ -98,13 +98,16 @@ import kotlin.reflect.KType
  * ```
  * // MyPluginData.nestedMap: MutableMap<Long, List<Long>> by value()
  * val newList = MyPluginData.map.getOrPut(1, ::mutableListOf)
- * newList.add(1) // 不会添加到 MyPluginData.nestedMap 中, 因为 `mutableListOf` 创建的 MutableList 被非引用地添加进了 MyPluginData.nestedMap
+ * newList.add(1) // 不会添加到 MyPluginData.nestedMap 中, 因为 `mutableListOf` 创建的 MutableList 被非引用 (浅拷贝) 地添加进了 MyPluginData.nestedMap
  * ```
  *
  * 一个解决方案是对 [SerializerAwareValue] 做映射或相关修改. 如 [PluginDataExtensions].
  *
  * 要查看详细的解释，请查看 [docs/PluginData.md](https://github.com/mamoe/mirai-console/blob/master/docs/PluginData.md)
  *
+ * ## 实现注意
+ * 此类型处于实验性阶段. 使用其中定义的属性和函数是安全的, 但将来可能会新增成员抽象函数.
+ *
  * @see AbstractJvmPlugin.reloadPluginData 通过 [JvmPlugin] 获取指定 [PluginData] 实例.
  * @see PluginDataStorage [PluginData] 存储仓库
  * @see PluginDataExtensions 相关 [SerializerAwareValue] 映射函数

backend/mirai-console/src/main/kotlin/net/mamoe/mirai/console/data/ValueDescription.kt

@@ -35,4 +35,9 @@ import kotlinx.serialization.SerialInfo
 @SerialInfo
 @Target(AnnotationTarget.PROPERTY, AnnotationTarget.CLASS)
 @Retention(AnnotationRetention.RUNTIME)
-public annotation class ValueDescription(val value: String)
+public annotation class ValueDescription(
+    /**
+     * 将会被 [String.trimIndent] 处理.
+     */
+    val value: String,
+)

backend/mirai-console/src/main/kotlin/net/mamoe/mirai/console/data/java/JAutoSavePluginConfig.kt

@@ -37,10 +37,4 @@ import net.mamoe.mirai.console.data.PluginData
  * @see JAutoSavePluginData
  * @see PluginConfig
  */
-public abstract class JAutoSavePluginConfig : AutoSavePluginConfig, PluginConfig {
+public abstract class JAutoSavePluginConfig public constructor(saveName: String) : AutoSavePluginConfig(saveName), PluginConfig
-    @Deprecated("请手动指定保存名称. 此构造器将在 1.0.0 删除", level = DeprecationLevel.ERROR, replaceWith = ReplaceWith("JAutoSavePluginConfig(\"把我改成保存名称\")"))
-    @Suppress("DEPRECATION_ERROR")
-    public constructor() : super()
-
-    public constructor(saveName: String) : super(saveName)
-}

backend/mirai-console/src/main/kotlin/net/mamoe/mirai/console/data/java/JAutoSavePluginData.kt

@@ -66,12 +66,7 @@ import kotlin.reflect.full.createType
  *
  * @see PluginData
  */
-public abstract class JAutoSavePluginData : AutoSavePluginData, PluginConfig {
+public abstract class JAutoSavePluginData public constructor(saveName: String) : AutoSavePluginData(saveName), PluginConfig {
-    @Deprecated("请手动指定保存名称. 此构造器将在 1.0.0 删除", level = DeprecationLevel.ERROR, replaceWith = ReplaceWith("JAutoSavePluginData(\"把我改成保存名称\")"))
-    @Suppress("DEPRECATION_ERROR")
-    public constructor() : super()
-
-    public constructor(saveName: String) : super(saveName)
 
     //// region JPluginData_value_primitives CODEGEN ////
 

backend/mirai-console/src/main/kotlin/net/mamoe/mirai/console/extension/ExtensionPoint.kt

@@ -50,7 +50,8 @@ public interface InstanceExtensionPoint<T : InstanceExtension<*>> : ExtensionPoi
 public interface FunctionExtensionPoint<T : FunctionExtension> : ExtensionPoint<T>
 
 
-public abstract class AbstractInstanceExtensionPoint<E : InstanceExtension<T>, T>(
+public abstract class AbstractInstanceExtensionPoint<E : InstanceExtension<T>, T>
+@ConsoleExperimentalApi constructor(
     extensionType: KClass<E>,
     /**
      * 内建的实现列表.
@@ -59,7 +60,8 @@ public abstract class AbstractInstanceExtensionPoint<E : InstanceExtension<T>, T
     public vararg val builtinImplementations: E,
 ) : AbstractExtensionPoint<E>(extensionType)
 
-public abstract class AbstractSingletonExtensionPoint<E : SingletonExtension<T>, T>(
+public abstract class AbstractSingletonExtensionPoint<E : SingletonExtension<T>, T>
+@ConsoleExperimentalApi constructor(
     extensionType: KClass<E>,
     /**
      * 内建的实现.

backend/mirai-console/src/main/kotlin/net/mamoe/mirai/console/extensions/CommandCallParserProvider.kt

@@ -30,6 +30,6 @@ public interface CommandCallParserProvider : InstanceExtension<CommandCallParser
 public class CommandCallParserProviderImpl(override val instance: CommandCallParser) : CommandCallParserProvider
 
 @ExperimentalCommandDescriptors
-public class CommandCallParserProviderImplLazy(instanceCalculator: () -> CommandCallParser) : CommandCallParserProvider {
+public class CommandCallParserProviderImplLazy(initializer: () -> CommandCallParser) : CommandCallParserProvider {
-    override val instance: CommandCallParser by lazy(instanceCalculator)
+    override val instance: CommandCallParser by lazy(initializer)
 }

backend/mirai-console/src/main/kotlin/net/mamoe/mirai/console/extensions/CommandCallResolverProvider.kt

@@ -26,6 +26,6 @@ public interface CommandCallResolverProvider : InstanceExtension<CommandCallReso
 public class CommandCallResolverProviderImpl(override val instance: CommandCallResolver) : CommandCallResolverProvider
 
 @ExperimentalCommandDescriptors
-public class CommandCallResolverProviderImplLazy(instanceCalculator: () -> CommandCallResolver) : CommandCallResolverProvider {
+public class CommandCallResolverProviderImplLazy(initializer: () -> CommandCallResolver) : CommandCallResolverProvider {
-    override val instance: CommandCallResolver by lazy(instanceCalculator)
+    override val instance: CommandCallResolver by lazy(initializer)
 }

backend/mirai-console/src/main/kotlin/net/mamoe/mirai/console/extensions/PostStartupExtension.kt

@@ -24,10 +24,10 @@ public fun interface PostStartupExtension : FunctionExtension {
     /**
      * 将在 Console 主线程执行.
      *
-     * @throws Exception 所有抛出的 [Exception] 都会被捕获并包装为 [ExtensionException] 抛出, 并停止 [MiraiConsole]
-     *
      * #### 内部实现细节
      * 在 [MiraiConsoleImplementationBridge.doStart] 所有 [MiraiConsoleImplementationBridge.phase] 执行完成后顺序调用.
+     *
+     * @throws Exception 所有抛出的 [Exception] 都会被捕获并包装为 [ExtensionException] 抛出, 并停止 [MiraiConsole]
      */
     @Throws(Exception::class)
     public operator fun invoke()

backend/mirai-console/src/main/kotlin/net/mamoe/mirai/console/extensions/SingletonExtensionSelector.kt

@@ -28,13 +28,16 @@ import kotlin.reflect.KClass
  * 如有多个 [SingletonExtensionSelector] 注册, 将会停止服务器.
  */
 public interface SingletonExtensionSelector : FunctionExtension {
+    /**
+     * 表示一个插件注册的 [Extension]
+     */
     public data class Registry<T : Extension>(
         val plugin: Plugin?,
         val extension: T,
     )
 
     /**
-     * @return null 表示使用 builtin
+     * @return `null` 表示使用 Console 内置的 [SingletonExtensionSelector]
      */
     public fun <T : Extension> selectSingleton(
         extensionType: KClass<T>,

backend/mirai-console/src/main/kotlin/net/mamoe/mirai/console/internal/MiraiConsoleImplementationBridge.kt

@@ -226,6 +226,9 @@ internal object MiraiConsoleImplementationBridge : CoroutineScope, MiraiConsoleI
     @DslMarker
     internal annotation class ILoveOmaeKumikoForever
 
+    /**
+     * 表示一个初始化阶段, 无实际作用.
+     */
     @ILoveOmaeKumikoForever
     private inline fun phase(block: () -> Unit) {
         contract {

backend/mirai-console/src/main/kotlin/net/mamoe/mirai/console/internal/command/CommandReflector.kt

@@ -1,3 +1,12 @@
+/*
+ * Copyright 2019-2020 Mamoe Technologies and contributors.
+ *
+ * 此源代码的使用受 GNU AFFERO GENERAL PUBLIC LICENSE version 3 许可证的约束, 可以在以下链接找到该许可证.
+ * Use of this source code is governed by the GNU AFFERO GENERAL PUBLIC LICENSE version 3 license that can be found via the following link.
+ *
+ * https://github.com/mamoe/mirai/blob/master/LICENSE
+ */
+
 package net.mamoe.mirai.console.internal.command
 
 import net.mamoe.mirai.console.command.*
@@ -149,7 +158,7 @@ internal class CommandReflector(
                     append(" ")
                 }
                 append(subcommand.valueParameters.joinToString(" ") { it.render() })
-                annotationResolver.getDescription(command, subcommand.originFunction).let { description ->
+                annotationResolver.getDescription(command, subcommand.originFunction)?.let { description ->
                     append("   ")
                     append(description)
                 }

backend/mirai-console/src/main/kotlin/net/mamoe/mirai/console/internal/command/internal.kt

@@ -58,6 +58,7 @@ internal fun Group.fuzzySearchMember(
     disambiguationRate: Double = 0.1,
 ): List<Pair<Member, Double>> {
     val candidates = (this.members + botAsMember)
+        .asSequence()
         .associateWith { it.nameCard.fuzzyMatchWith(nameCardTarget) }
         .filter { it.value >= minRate }
         .toList()
@@ -79,7 +80,7 @@ internal fun Group.fuzzySearchMember(
     }
 }
 
-internal fun Command.createOrFindCommandPermission(parent: Permission): Permission {
+internal fun Command.findOrCreateCommandPermission(parent: Permission): Permission {
     val id = owner.permissionId("command.$primaryName")
     return PermissionService.INSTANCE[id] ?: PermissionService.INSTANCE.register(id, description, parent)
 }

backend/mirai-console/src/main/kotlin/net/mamoe/mirai/console/internal/data/builtins/AutoLoginConfig.kt

@@ -1,3 +1,12 @@
+/*
+ * Copyright 2019-2020 Mamoe Technologies and contributors.
+ *
+ * 此源代码的使用受 GNU AFFERO GENERAL PUBLIC LICENSE version 3 许可证的约束, 可以在以下链接找到该许可证.
+ * Use of this source code is governed by the GNU AFFERO GENERAL PUBLIC LICENSE version 3 license that can be found via the following link.
+ *
+ * https://github.com/mamoe/mirai/blob/master/LICENSE
+ */
+
 package net.mamoe.mirai.console.internal.data.builtins
 
 import net.mamoe.mirai.console.data.AutoSavePluginConfig

backend/mirai-console/src/main/kotlin/net/mamoe/mirai/console/internal/extension/BuiltInSingletonExtensionSelector.kt

@@ -1,3 +1,12 @@
+/*
+ * Copyright 2019-2020 Mamoe Technologies and contributors.
+ *
+ * 此源代码的使用受 GNU AFFERO GENERAL PUBLIC LICENSE version 3 许可证的约束, 可以在以下链接找到该许可证.
+ * Use of this source code is governed by the GNU AFFERO GENERAL PUBLIC LICENSE version 3 license that can be found via the following link.
+ *
+ * https://github.com/mamoe/mirai/blob/master/LICENSE
+ */
+
 package net.mamoe.mirai.console.internal.extension
 
 import kotlinx.coroutines.runBlocking

backend/mirai-console/src/main/kotlin/net/mamoe/mirai/console/internal/plugin/ExportManagerImpl.kt

@@ -1,12 +1,10 @@
 /*
- * Copyright (c) 2018-2020 Karlatemp. All rights reserved.
+ * Copyright 2019-2020 Mamoe Technologies and contributors.
- * @author Karlatemp <karlatemp@vip.qq.com> <https://github.com/Karlatemp>
- *
- * LuckPerms-Mirai/mirai-console.mirai-console.main/ExportManagerImpl.kt
  *
+ * 此源代码的使用受 GNU AFFERO GENERAL PUBLIC LICENSE version 3 许可证的约束, 可以在以下链接找到该许可证.
  * Use of this source code is governed by the GNU AFFERO GENERAL PUBLIC LICENSE version 3 license that can be found via the following link.
  *
- * https://github.com/Karlatemp/LuckPerms-Mirai/blob/master/LICENSE
+ * https://github.com/mamoe/mirai/blob/master/LICENSE
  */
 
 package net.mamoe.mirai.console.internal.plugin

backend/mirai-console/src/main/kotlin/net/mamoe/mirai/console/internal/util/JavaPluginSchedulerImpl.kt

@@ -43,11 +43,10 @@ internal class JavaPluginSchedulerImpl internal constructor(parentCoroutineConte
         }
     }
 
-    override fun <R> delayed(delayMillis: Long, runnable: Callable<R>): CompletableFuture<Void?> {
+    override fun <R> delayed(delayMillis: Long, callable: Callable<R>): CompletableFuture<R> {
         return future {
             delay(delayMillis)
-            withContext(Dispatchers.IO) { runnable.call() }
+            withContext(Dispatchers.IO) { callable.call() }
-            null
         }
     }
 

backend/mirai-console/src/main/kotlin/net/mamoe/mirai/console/permission/PermissionIdNamespace.kt

@@ -20,7 +20,7 @@ public interface PermissionIdNamespace {
     /**
      * 创建一个此命名空间下的 [PermitteeId].
      *
-     * 在指令初始化时, 会申请对应权限. 此时 [name] 为 "command.$primaryName` 其中 [primaryName][Command.primaryName].
+     * 在指令初始化时, 会申请对应权限. 此时 [name] 为 `command.$primaryName` 其中 [primaryName][Command.primaryName].
      */
     public fun permissionId(@ResolveContext(PERMISSION_NAME) name: String): PermissionId
 }

backend/mirai-console/src/main/kotlin/net/mamoe/mirai/console/plugin/Plugin.kt

@@ -35,7 +35,7 @@ import kotlin.DeprecationLevel.ERROR
  */
 public interface Plugin : CommandOwner {
     /**
-     * 判断此插件是否已启用
+     * 当插件已启用时返回 `true`, 否则表示插件未启用.
      *
      * @see PluginManager.enablePlugin 启用一个插件
      * @see PluginManager.disablePlugin 禁用一个插件

backend/mirai-console/src/main/kotlin/net/mamoe/mirai/console/plugin/PluginManager.kt

@@ -140,16 +140,28 @@ public interface PluginManager {
             get() = this.loader as PluginLoader<P, PluginDescription>
 
 
+        /**
+         * @see getPluginDescription
+         */
         @get:JvmSynthetic
         public inline val Plugin.description: PluginDescription
             get() = getPluginDescription(this)
 
+        /**
+         * @see disablePlugin
+         */
         @JvmSynthetic
         public inline fun Plugin.disable(): Unit = disablePlugin(this)
 
+        /**
+         * @see enablePlugin
+         */
         @JvmSynthetic
         public inline fun Plugin.enable(): Unit = enablePlugin(this)
 
+        /**
+         * @see loadPlugin
+         */
         @JvmSynthetic
         public inline fun Plugin.load(): Unit = loadPlugin(this)
     }

backend/mirai-console/src/main/kotlin/net/mamoe/mirai/console/plugin/jvm/JavaPluginScheduler.kt

@@ -19,6 +19,7 @@ import java.util.concurrent.Callable
 import java.util.concurrent.CompletableFuture
 import java.util.concurrent.Future
 import kotlin.coroutines.CoroutineContext
+import kotlin.coroutines.EmptyCoroutineContext
 
 
 /**
@@ -48,9 +49,9 @@ public interface JavaPluginScheduler : CoroutineScope {
     /**
      * 新增一个 Delayed Task (延迟任务)
      *
-     * 在延迟 [delayMillis] 后执行 [runnable]
+     * 在延迟 [delayMillis] 后执行 [callable]
      */
-    public fun <R> delayed(delayMillis: Long, runnable: Callable<R>): CompletableFuture<Void?>
+    public fun <R> delayed(delayMillis: Long, callable: Callable<R>): CompletableFuture<R>
 
     /**
      * 异步执行一个任务, 最终返回 [Future], 与 Java 使用方法无异, 但效率更高且可以在插件关闭时停止
@@ -68,7 +69,8 @@ public interface JavaPluginScheduler : CoroutineScope {
          */
         @JvmStatic
         @JvmName("create")
-        public operator fun invoke(parentCoroutineContext: CoroutineContext): JavaPluginScheduler =
+        @JvmOverloads
+        public operator fun invoke(parentCoroutineContext: CoroutineContext = EmptyCoroutineContext): JavaPluginScheduler =
             JavaPluginSchedulerImpl(parentCoroutineContext)
     }
 }

backend/mirai-console/src/main/kotlin/net/mamoe/mirai/console/util/ConsoleInput.kt

@@ -18,7 +18,7 @@ import net.mamoe.mirai.console.MiraiConsole
 import net.mamoe.mirai.console.internal.util.ConsoleInputImpl
 
 /**
- * Console 输入. 由于 console 接管了 [stdin][System. in], [readLine] 等操作需要在这里进行.
+ * Console 输入. 由于 console 接管了 [标准输入][System. in], [readLine] 等操作需要在这里进行.
  */
 public interface ConsoleInput {
     /**

backend/mirai-console/src/main/kotlin/net/mamoe/mirai/console/util/MessageScope.kt

@@ -72,6 +72,7 @@ import kotlin.internal.LowPriorityInOverloadResolution
  *     val duration = Random.nextInt(1, 15)
  *     target.mute(duration)
  *
+ *
  *     // 不使用 MessageScope, 无用的样板代码
  *     val thisGroup = this.getGroupOrNull()
  *     val message = "${this.name} 禁言 ${target.nameCardOrNick} $duration 秒"
@@ -80,12 +81,14 @@ import kotlin.internal.LowPriorityInOverloadResolution
  *     }
  *     sendMessage(message)
  *
+ *
  *     // 使用 MessageScope, 清晰逻辑
  *     // 表示至少发送给 `this`, 当 `this` 的真实发信对象与 `target.group` 不同时, 还额外发送给 `target.group`
  *     this.scopeWith(target.group) {
  *         sendMessage("${name} 禁言了 ${target.nameCardOrNick} $duration 秒")
  *     }
  *
+ *
  *     // 同样地, 可以扩展用法, 同时私聊指令执行者:
  *     // this.scopeWith(
  *     //    target,
@@ -132,6 +135,8 @@ public inline operator fun <R, MS : MessageScope> MS.invoke(action: MS.() -> R):
 
 /*
  * 实现提示: 以下所有代码都通过 codegen 模块中 net.mamoe.mirai.console.codegen.MessageScopeCodegen 生成. 请不要手动修改它们.
+ *
+ * 建议阅读 [MessageScope] 的文档.
  */
 
 //// region MessageScopeBuilders CODEGEN ////

backend/mirai-console/src/test/kotlin/net/mamoe/mirai/console/command/TestCommand.kt

@@ -77,6 +77,7 @@ internal class TestCommand {
 
     @Test
     fun testRegister() {
+        error(TestCompositeCommand.usage)
         try {
             unregisterAllCommands(ConsoleCommandOwner) // builtins
             unregisterCommand(TestSimpleCommand)