Docs and API improvements

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

@@ -11,34 +11,32 @@
 
 package net.mamoe.mirai.console.command.parse
 
+import net.mamoe.mirai.console.command.Command
 import net.mamoe.mirai.console.command.CommandSender
 import net.mamoe.mirai.console.command.descriptor.ExperimentalCommandDescriptors
-import net.mamoe.mirai.console.command.descriptor.UnresolvedCommandCallException
+import net.mamoe.mirai.console.command.resolve.CommandCallResolver
-import net.mamoe.mirai.console.command.resolve.ResolvedCommandCall
+import net.mamoe.mirai.console.util.ConsoleExperimentalApi
-import net.mamoe.mirai.console.extensions.CommandCallResolverProvider
-import net.mamoe.mirai.console.internal.extension.GlobalComponentStorage
 
+/**
+ * Unresolved [CommandCall].
+ */
 @ExperimentalCommandDescriptors
 public interface CommandCall {
     public val caller: CommandSender
 
+    /**
+     * One of callee [Command]'s [Command.allNames]
+     */
     public val calleeName: String
+
+    /**
+     * Explicit value arguments
+     */
     public val valueArguments: List<CommandValueArgument>
 
-    public companion object {
+    /**
-        @JvmStatic
+     * Custom data for [CommandCallResolver]
-        public fun CommandCall.resolveOrNull(): ResolvedCommandCall? {
+     */
-            GlobalComponentStorage.run {
+    @ConsoleExperimentalApi
-                CommandCallResolverProvider.useExtensions { provider ->
+    public val customData: Map<Any, Any>
-                    provider.instance.resolve(this@resolveOrNull)?.let { return it }
-                }
-            }
-            return null
-        }
-
-        @JvmStatic
-        public fun CommandCall.resolve(): ResolvedCommandCall {
-            return resolveOrNull() ?: throw UnresolvedCommandCallException(this)
-        }
-    }
 }

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

@@ -2,20 +2,35 @@ package net.mamoe.mirai.console.command.parse
 
 import net.mamoe.mirai.console.command.CommandSender
 import net.mamoe.mirai.console.command.descriptor.ExperimentalCommandDescriptors
+import net.mamoe.mirai.console.command.resolve.CommandCallResolver
+import net.mamoe.mirai.console.command.resolve.ResolvedCommandCall
 import net.mamoe.mirai.console.extensions.CommandCallParserProvider
 import net.mamoe.mirai.console.internal.extension.GlobalComponentStorage
 import net.mamoe.mirai.console.util.ConsoleExperimentalApi
 import net.mamoe.mirai.message.data.MessageChain
 
 /**
- * @see CommandCallParserProvider
+ * Lexical and syntactical parser for transforming a [MessageChain] into [CommandCall]
+ *
+ * @see CommandCallResolver The call resolver for [CommandCall] to become [ResolvedCommandCall]
+ * @see CommandCallParserProvider The extension point
  */
 @ConsoleExperimentalApi
 @ExperimentalCommandDescriptors
 public interface CommandCallParser {
+
+    /**
+     * Lexically and syntactically parse a [message] into [CommandCall], but performs nothing about resolving a call.
+     *
+     * @return `null` if unable to parse (i.e. due to syntax errors).
+     */
     public fun parse(sender: CommandSender, message: MessageChain): CommandCall?
 
     public companion object {
+        /**
+         * Calls [CommandCallParser]s provided by [CommandCallParserProvider] in [GlobalComponentStorage] sequentially,
+         * returning the first non-null result, `null` otherwise.
+         */
         @JvmStatic
         public fun MessageChain.parseCommandCall(sender: CommandSender): CommandCall? {
             GlobalComponentStorage.run {

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

@@ -24,7 +24,10 @@ import kotlin.reflect.typeOf
 public typealias RawCommandArgument = MessageContent
 
 @ExperimentalCommandDescriptors
-public interface CommandValueArgument {
+public interface CommandArgument
+
+@ExperimentalCommandDescriptors
+public interface CommandValueArgument : CommandArgument {
     public val value: RawCommandArgument
     public val typeVariants: List<TypeVariant<*>>
 }

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

@@ -11,8 +11,26 @@ package net.mamoe.mirai.console.command.resolve
 
 import net.mamoe.mirai.console.command.descriptor.ExperimentalCommandDescriptors
 import net.mamoe.mirai.console.command.parse.CommandCall
+import net.mamoe.mirai.console.extensions.CommandCallResolverProvider
+import net.mamoe.mirai.console.internal.extension.GlobalComponentStorage
 
+/**
+ * The resolver converting a [CommandCall] into [ResolvedCommandCall] based on registered []
+ */
+@ExperimentalCommandDescriptors
 public interface CommandCallResolver {
-    @ExperimentalCommandDescriptors
     public fun resolve(call: CommandCall): ResolvedCommandCall?
+
+    public companion object {
+        @JvmStatic
+        @JvmName("resolveCall")
+        public fun CommandCall.resolve(): ResolvedCommandCall? {
+            GlobalComponentStorage.run {
+                CommandCallResolverProvider.useExtensions { provider ->
+                    provider.instance.resolve(this@resolve)?.let { return it }
+                }
+            }
+            return null
+        }
+    }
 }

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

@@ -11,15 +11,37 @@ package net.mamoe.mirai.console.command.resolve;
 
 import net.mamoe.mirai.console.command.Command
 import net.mamoe.mirai.console.command.CommandSender
+import net.mamoe.mirai.console.command.CompositeCommand
 import net.mamoe.mirai.console.command.descriptor.CommandDescriptor
+import net.mamoe.mirai.console.command.descriptor.CommandSignatureVariant
 import net.mamoe.mirai.console.command.descriptor.ExperimentalCommandDescriptors
+import net.mamoe.mirai.console.command.parse.CommandCall
 import net.mamoe.mirai.console.command.parse.CommandValueArgument
 
+/**
+ * The resolved [CommandCall].
+ */
 @ExperimentalCommandDescriptors
 public interface ResolvedCommandCall {
     public val caller: CommandSender
 
+    /**
+     * The callee [Command]
+     */
     public val callee: Command
+
+    /**
+     * The callee [CommandDescriptor], specifically a sub command from [CompositeCommand]
+     */
     public val calleeDescriptor: CommandDescriptor
+
+    /**
+     * The callee [CommandSignatureVariant]
+     */
+    public val calleeSignature: CommandSignatureVariant
+
+    /**
+     * Resolved value arguments arranged mapping the [CommandSignatureVariant.valueParameters] by index.
+     */
     public val valueArguments: List<CommandValueArgument>
 }

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

@@ -14,6 +14,9 @@ import net.mamoe.mirai.console.command.parse.CommandCallParser
 import net.mamoe.mirai.console.extension.AbstractExtensionPoint
 import net.mamoe.mirai.console.extension.InstanceExtension
 
+/**
+ * The resolver for a [CommandCall]
+ */
 @ExperimentalCommandDescriptors
 public interface CommandCallParserProvider : InstanceExtension<CommandCallParser> {
     public companion object ExtensionPoint : AbstractExtensionPoint<CommandCallParserProvider>(CommandCallParserProvider::class)

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

@@ -9,11 +9,12 @@
 
 package net.mamoe.mirai.console.extensions
 
+import net.mamoe.mirai.console.command.descriptor.ExperimentalCommandDescriptors
 import net.mamoe.mirai.console.command.resolve.CommandCallResolver
 import net.mamoe.mirai.console.extension.AbstractExtensionPoint
 import net.mamoe.mirai.console.extension.InstanceExtension
 
+@ExperimentalCommandDescriptors
 public interface CommandCallResolverProvider : InstanceExtension<CommandCallResolver> {
     public companion object ExtensionPoint : AbstractExtensionPoint<CommandCallResolverProvider>(CommandCallResolverProvider::class)
-}
+}
-

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

@@ -20,6 +20,9 @@ import java.util.concurrent.CopyOnWriteArraySet
 import kotlin.contracts.contract
 import kotlin.reflect.KClass
 
+/**
+ * The [ComponentStorage] containing all components provided by Mirai Console internals and installed plugins.
+ */
 internal object GlobalComponentStorage : AbstractConcurrentComponentStorage()
 internal interface ExtensionRegistry<out E : Extension> {
     val plugin: Plugin