From 5f957594e79b25f2d496e9f30c0d425bb5e4e34c Mon Sep 17 00:00:00 2001
From: Jakob K <bluefireolymp@gmail.com>
Date: Mon, 28 Jun 2021 13:08:57 +0200
Subject: [PATCH] Add brigardier docs

---
 guide/docs/commands/brigardier.md | 105 ++++++++++++++++++++++++++++++
 guide/mkdocs.yml                  |   2 +
 2 files changed, 107 insertions(+)
 create mode 100644 guide/docs/commands/brigardier.md

diff --git a/guide/docs/commands/brigardier.md b/guide/docs/commands/brigardier.md
new file mode 100644
index 00000000..a3854def
--- /dev/null
+++ b/guide/docs/commands/brigardier.md
@@ -0,0 +1,105 @@
+# Brigardier support
+
+## Create a command
+
+```kotlin
+command("mycommand") {
+    // the command body
+}
+```
+
+## Register the command
+
+The command will be automatically register by default, **if you are initializing it before the end of the `startup` call
+to your plugin.**
+
+Otherwise, you can register it manually using the `command.register()` function (where command is the command instance
+which the `command(name)` function returns).
+
+## Command features
+
+???+ danger "Where to call these? How to structure these?"
+    All the following features can be used inside the command body. <br>
+    You can infinitely nest all these functions, resulting in complex command structures. <br>
+
+### Execution handler
+
+You provide your execution logic using the `executes` (with status code) or `simpleExecutes` (status code is always 1)
+function.
+
+```kotlin
+simpleExecutes { context ->
+    context.source.bukkitSender.sendMessage("hey gamer ;)")
+}
+```
+
+???+ info 
+    The execution and suggestion providers always do only apply to the location in the tree where they are
+    defined.
+
+#### The command context
+
+You can use the command context to get the command source. You can use the source for:
+
+- `source.bukkitSender` to get the `CommandSender`
+- `source.player` ensure that a player executed the command and get that `Player`
+- `source.bukkitWorld` to get the world of the executor
+
+### Literals (subcommands)
+
+```kotlin
+literal("mysubcommand") {
+    // the command body for this part of the command tree
+}
+```
+
+### Arguments
+
+```kotlin
+argument("argumentname", StringArgumentType.string()) {
+    // the command body (inside this body, the argument exists in the context)
+}
+```
+
+The argument name will be displayed to the player. Also, it can be used to retrieve the value of the argument the
+execution handler.
+
+#### Argument type
+
+The second paramter of the argument function is the argument type. There are a lot of pre defined argument types by
+brigardier. 
+
+The argument types for all primitives can be accessed in the following pattern: `NameArgumentType.name()` (where name is the name of the primitive)
+
+```kotlin
+// examples:
+StringArgumentType.string()
+BoolArgumentType.bool()
+IntegerArgumentType.integer()
+```
+
+#### Retrieve the value of an argument
+
+The value of the argument can be retrieved from the command context.
+
+```kotlin
+argument("argumentname", StringArgumentType.string()) {
+    simpleExecutes {
+        val argValue = it.getArgument<String>("argumentname")
+        // or using reified you can omit the type sometimes
+        mapWhereTheKeysAreStrings[it.getArgument("argumentname")]
+    }
+}
+```
+
+### Suggestions
+
+You can provide argument suggestions using the `simpleSuggests` function. It is **not** recommended using the default 
+`suggests` function.
+
+```kotlin
+simpleSuggests { Material.values().map { it.name } }
+```
+
+It is okay to do heavy operations inside this function. Suggestions are asynchronous. The body of the `simpleSuggests`
+function is suspending, meaning you can use kotlinx.coroutines in it.
diff --git a/guide/mkdocs.yml b/guide/mkdocs.yml
index 55e3d828..eab546fc 100644
--- a/guide/mkdocs.yml
+++ b/guide/mkdocs.yml
@@ -41,5 +41,7 @@ nav:
       - Item builder: extensions/itembuilder.md
   - Gui:
       - Compounds: gui/compounds.md
+  - Commands:
+      - Brigardier: commands/brigardier.md
   - Migration:
       - "1.16 -> 1.17": migration/1_16_to_1_17.md