feat(discord): document cloud-kord

.wordlist.txt

@@ -92,3 +92,5 @@ ExecutionCoordinator
 autocompletion
 MENTIONABLE
 Subcommands
+kord
+Kord

docs/discord/index.md

@@ -7,5 +7,7 @@ The [cloud-discord](https://github.com/incendo/cloud-discord) repository houses
   Notably, the module contains tooling for integrating with slash commands.
 - [cloud-jda](./jda.md): Integration for JDA4. No slash command support.
 - [cloud-jda5](./jda5.md): Integration for JDA5 slash commands.
+- [cloud-kord](./kord.md): Integration for Kord slash commands.
 - [cloud-javacord](./javacord.md): Integration for Javacord.
 - [example-jda5](https://github.com/Incendo/cloud-discord/tree/master/examples/example-jda5): Example bot using JDA5.
+- [example-kord](https://github.com/Incendo/cloud-discord/tree/master/examples/example-kord): Example bot using Kord.

docs/discord/kord.md

@@ -0,0 +1,170 @@
+# cloud-kord
+
+Cloud integration for [Kord](https://github.com/kordlib/kord) slash commands.
+
+An example bot using cloud-kord can be found [here](https://github.com/Incendo/cloud-discord/tree/master/examples/example-kord).
+
+## Installation
+
+Cloud Annotations is available through [Maven Central](https://search.maven.org/search?q=cloud.commandframework).
+
+<!-- prettier-ignore -->
+=== "Maven"
+
+    ```xml
+    <dependencies>
+        <dependency>
+            <groupId>org.incendo</groupId>
+            <artifactId>cloud-kord</artifactId>
+            <version>1.0.0-SNAPSHOT</version>
+        </dependency>
+    </dependencies>
+    ```
+
+=== "Gradle (Kotlin)"
+
+    ```kotlin
+    implementation("org.incendo:cloud-kord:1.0.0-SNAPSHOT")
+    ```
+
+=== "Gradle (Groovy)"
+
+    ```groovy
+    implementation 'org.incendo:cloud-kord:1.0.0-SNAPSHOT'
+    ```
+
+## Usage
+
+### Command Manager
+
+```kotlin
+// Using the "native" KordInteraction sender type:
+val commandManager: KordCommandManager<KordInteraction> = KordCommandManager(executionCoordinator) {
+  it
+}
+
+// Using a custom sender type:
+val commandManager: KordCommandManager<KordInteraction> = KordCommandManager(executionCoordinator) {
+  it -> senderType
+}
+```
+
+where `executionCoordinator` is an
+[ExecutionCoordinator](../core/index.md#execution-coordinators) instance.
+
+You then register the command manager as a Kord event listener. Example:
+
+```kotlin
+commandManager.installListener(kord)
+```
+
+The event listener handles command synchronization, command execution and
+autocompletion. You may manually synchronize commands using
+`commandManager.commandFactory.createGuildCommands(Guild)` or
+`commandManager.commandFactory.createGlobalCommands(Kord)`.
+
+`cloud-kord` depends on [cloud-kotlin-extensions](../kotlin/extensions.md)
+and [cloud-kotlin-coroutines](../kotlin/coroutines.md). Because Kord is coroutine-based it is recommended
+that you make use of `MutableCommandBuilder` as well as suspending command execution handlers. If you use annotated
+commands you will also want to depend on [cloud-kotlin-coroutines-annotations](../kotlin/annotations.md).
+
+```kotlin title="Example command registration"
+commandManager.buildAndRegister("command") {
+    required("user", KordParser.userParser())
+
+    suspendingHandler { context ->
+        // Always available through an extension function.
+        val interaction: KordInteraction = context.interaction
+        val user: User = context.get("user")
+
+        interaction.respondEphemeral {
+          content = "Hello ${user.mention}"
+        }
+    }
+}
+```
+
+### Parsers
+
+Mappings to all existing option types are supported:
+
+- INTEGER: `IntegerParser`
+- NUMBER: `DoubleParser`
+- BOOLEAN: `BooleanParser`
+- STRING: `StringParser`
+- USER: `KordParser.userParser()`
+- CHANNEL: `KordParser.channelParser()`
+- ROLE: `KordParser.roleParser()`
+- MENTIONABLE: `KordParser.mentionableParser()`
+- ATTACHMENT: `KordParser.attachmentParser()`
+
+Subcommands and subcommand groups are mapped to Cloud literals.
+Other parsers are by default be mapped to the string option type.
+
+### Choices
+
+The [suggestion providers](../core/index.md#suggestions) will be invoked for option types that support
+auto completions.
+You may also use constant choices by using `DiscordChoices` as the suggestion provider. Example:
+
+```kotlin
+commandBuilder.required(
+    "integer",
+    integerParser(),
+    DiscordChoices.integers(1, 2, 3)
+)
+```
+
+Choices may be used for custom parsers that get mapped to string choices.
+
+### Command Scopes
+
+You may choose where a command is registered to by using `CommandScope`. You apply the scope to the command builder using:
+
+```java
+// Available everywhere (DMs, guilds, etc):
+mutableCommandBuilder.scope(CommandScope.global())
+
+// Available in all guilds:
+mutableCommandBuilder.scope(CommandScope.guilds())
+
+// Available in specific guilds:
+mutableCommandBuilder.scope(CommandScope.guilds(some, guild, ids))
+```
+
+You may implement custom filtering by overriding the command scope predicate for the command factory:
+
+```java
+commandManager.commandFactory().commandScopePredicate = { node, scope -> yourLogicHere }
+```
+
+#### Annotations:
+
+If using annotated commands you may use the `@CommandScope` annotation. You must first install the builder modifier:
+
+```kotlin
+CommandScopeBuilderModifier.install(annotationParser)
+```
+
+You may then use the annotation:
+
+```kotlin
+@CommandScope(guilds = { 1337 })
+@Command("command")
+public suspend void yourCommand() { /* ... */ }
+```
+
+### Permissions
+
+You may set the default permissions by using `DiscordPermission.of(Long)` as the command permission. Example:
+
+```kotlin
+commandBuilder.permission(1337)
+```
+
+You may use ordinary permissions by setting the permission function in `KordCommandManager`.
+
+### Settings
+
+You may modify certain behaviors using the `KordSetting`s. You may do this by
+accessing the `Configurable<KordSetting>` instance using `KordCommandManager.kordSettings()`.

mkdocs.yml

@@ -22,6 +22,7 @@ nav:
       - cloud-javacord: discord/javacord.md
       - cloud-jda: discord/jda.md
       - cloud-jda5: discord/jda5.md
+      - cloud-kord: discord/kord.md
   - cloud-minecraft:
       - cloud-minecraft: minecraft/index.md
       - cloud-brigadier: minecraft/brigadier.md