feat: document the kotlin modules

.wordlist.txt

@@ -59,3 +59,5 @@ kotlin
 iterable
 Guice
 GuiceInjectionService
+coroutine
+coroutines

docs/kotlin/annotations.md

@@ -0,0 +1,54 @@
+# cloud-kotlin-coroutines-annotations
+
+This module adds coroutine support to [cloud-annotations](../annotations/index.md), allowing you to make
+the annotated command methods and suggestion providers suspending.
+
+The module also adds the ability to use Kotlin default values in both suspending and non-suspending methods.
+
+```kotlin title="Example of a suspending command method"
+@CommandMethod("command [argument]")
+suspend fun yourCommand(
+    argument: String = "default value"
+): Unit = withContext(Dispatchers.IO) {
+  // ...
+}
+```
+
+## Installation
+
+Cloud is available through [Maven Central](https://search.maven.org/search?q=cloud.commandframework).
+
+<!-- prettier-ignore -->
+=== "Gradle (Kotlin)"
+
+    ```kotlin
+    implementation("cloud.commandframework:cloud-kotlin-coroutines-annotations:2.0.0-SNAPSHOT")
+    ```
+
+=== "Gradle (Groovy)"
+
+    ```groovy
+    implementation 'cloud.commandframework:cloud-kotlin-coroutines-annotations:2.0.0-SNAPSHOT'
+    ```
+
+You then need to install the `AnnotationParser` extension:
+
+```kotlin
+annotationParser.installCoroutineSupport()
+```
+
+You may override the default coroutine scope (`GlobalScope`) and context (`EmptyCoroutineContext`)
+when invoking `installCoroutineSupport`.
+
+## Suggestion Providers
+
+The coroutine support extends the allowed signatures for `@Suggestions`-annotated methods, letting you return
+sequences of `Suggestion` objects as well as strings.
+
+```kotlin title="Example of a suspending suggestion provider"
+@Suggestions("custom-suggestions")
+suspend fun suggestionMethod(
+    context: CommandContext<CommandSender>,
+    input: String
+): Sequence<Suggestion> = sequenceOf("a", "b", "c").map(Suggestion::simple)
+```

docs/kotlin/coroutines.md

@@ -0,0 +1,68 @@
+# cloud-kotlin-coroutines
+
+This module adds coroutine support to commands using builders.
+For suspending commands methods, see [cloud-kotlin-coroutines-annotations](./annotations.md).
+
+## Installation
+
+Cloud is available through [Maven Central](https://search.maven.org/search?q=cloud.commandframework).
+
+<!-- prettier-ignore -->
+=== "Gradle (Kotlin)"
+
+    ```kotlin
+    implementation("cloud.commandframework:cloud-kotlin-coroutines:2.0.0-SNAPSHOT")
+    ```
+
+=== "Gradle (Groovy)"
+
+    ```groovy
+    implementation 'cloud.commandframework:cloud-kotlin-coroutines:2.0.0-SNAPSHOT'
+    ```
+
+## Suspending command execution handlers
+
+You may create a suspending command execution handler by implementing `SuspendingExecutionHandler`.
+The `SuspendingExecutionHandler` interface does not extend `CommandExecutionHandler`, but you can convert
+it to a `CommandExecutionHandler` by using `SuspendingExecutionHandler.asCommandExecutionHandler`.
+
+There are extensions for both `Command.Builder` and `MutableCommandBuilder` that allow you to make direct
+use of suspending execution handlers.
+
+```kotlin title="Example"
+manager.commandBuilder("command")
+    .suspendingHandler { context ->
+        // ...
+    }
+```
+
+## Suspending parsers
+
+You may create a suspending argument parser by implementing `SuspendingArgumentParser`.
+The `SuspendingArgumentParser` interface does not extend `ArgumentParser`, but you can convert
+it to an `ArgumentParser` by using `SuspendingArgumentParser.asArgumentParser`.
+
+You may also create a suspending argument parser by making use of the global factory function:
+
+```kotlin title="Creating a suspending parser"
+suspendingArgumentParser<CommandSender, Int> { ctx, input ->
+    ArgumentParseResult.success(input.readInteger())
+}
+```
+
+## Suspending suggestion providers
+
+You may create a suspending suggestion provider by implementing `SuspendingSuggestionProvider`.
+The `SuspendingSuggestionProvider` interface does not extend `SuggestionProvider`, but you can convert
+it to a `SuggestionProvider` by using `SuspendingSuggestionProvider.asSuggestionProvider`.
+
+You may also create a suspending suggestion provider by making use of the global factory function:
+
+```kotlin title="Creating a suspending suggestion provider"
+suspendingSuggestionProvider<CommandSender> { ctx, input ->
+    (1..3).asSequence()
+        .map(Number::toString)
+        .map(Suggestion::simple)
+        .asIterable()
+}
+```

docs/kotlin/extensions.md

@@ -0,0 +1,55 @@
+# cloud-kotlin-extensions
+
+This module contains extensions to different parts of Cloud.
+
+## Installation
+
+Cloud is available through [Maven Central](https://search.maven.org/search?q=cloud.commandframework).
+
+<!-- prettier-ignore -->
+=== "Gradle (Kotlin)"
+
+    ```kotlin
+    implementation("cloud.commandframework:cloud-kotlin-extensions:2.0.0-SNAPSHOT")
+    ```
+
+=== "Gradle (Groovy)"
+
+    ```groovy
+    implementation 'cloud.commandframework:cloud-kotlin-extensions:2.0.0-SNAPSHOT'
+    ```
+
+## MutableCommandBuilder
+
+`MutableCommandBuilder` is a small DSL for `Command.Builder` which allows for the creation of commands
+in more idiomatic Kotlin.
+
+You can initiate the mutable command builder using `CommandManager.commandBuilder` or
+create and register the command in one step by using `CommandManager.buildAndRegister`.
+
+```kotlin title="Example MutableCommandBuilder usage"
+manager.buildAndRegister("command") {
+    senderType<OverriddenSenderType>()
+
+    required("string", stringParser()) {
+        description(argumentDescription("A string argument"))
+    }
+
+    handler { ctx ->
+        // ...
+    }
+}
+```
+
+## Extension Functions
+
+The `cloud.commandframework.kotlin.extension` package contains extensions to:
+
+- `CloudKeyContainer`
+- `CloudKey`
+- `Command.Builder`
+- `CommandManager`
+- `ExceptionController`
+- `ArgumentParser`
+
+The extensions exist to make it easier to use Cloud in Kotlin.

docs/kotlin/index.md

@@ -1 +1,7 @@
 # cloud-kotlin
+
+Cloud has three different modules for Kotlin:
+
+- [cloud-kotlin-coroutines-annotations](./annotations.md)
+- [cloud-kotlin-coroutines](./coroutines.md)
+- [cloud-kotlin-extensions](./extensions.md)

mkdocs.yml

@@ -45,7 +45,7 @@ theme:
     - navigation.sections
     - navigation.indexes
     - navigation.top
-    # - navigation.footer
+    - navigation.footer
     - toc.follow
     - search.suggest
     - search.highlight