From 5bd2b90d02a0116b1e11ec54eccabda728882f0d Mon Sep 17 00:00:00 2001
From: Jason Penilla <11360596+jpenilla@users.noreply.github.com>
Date: Sun, 2 Apr 2023 12:53:06 -0700
Subject: [PATCH] Improve docs around Brigadier on bukkit/paper

---
 .../bukkit/BukkitCommandManager.java          |  5 ++++-
 .../bukkit/CloudBukkitCapabilities.java       | 20 +++++++++++++++++++
 .../paper/PaperCommandManager.java            | 11 +++++++++-
 examples/example-bukkit/build.gradle.kts      |  4 ----
 .../examples/bukkit/ExamplePlugin.java        |  2 +-
 5 files changed, 35 insertions(+), 7 deletions(-)

diff --git a/cloud-minecraft/cloud-bukkit/src/main/java/cloud/commandframework/bukkit/BukkitCommandManager.java b/cloud-minecraft/cloud-bukkit/src/main/java/cloud/commandframework/bukkit/BukkitCommandManager.java
index 9177898ba..5fbdeef7a 100644
--- a/cloud-minecraft/cloud-bukkit/src/main/java/cloud/commandframework/bukkit/BukkitCommandManager.java
+++ b/cloud-minecraft/cloud-bukkit/src/main/java/cloud/commandframework/bukkit/BukkitCommandManager.java
@@ -331,7 +331,10 @@ public final boolean queryCapability(final @NonNull CloudBukkitCapabilities capa
     }
 
     /**
-     * Attempt to register the Brigadier mapper, and return it.
+     * Attempts to enable Brigadier command registration through Commodore.
+     *
+     * <p>Callers should check for {@link CloudBukkitCapabilities#COMMODORE_BRIGADIER} first
+     * to avoid exceptions.</p>
      *
      * @throws BrigadierFailureException If Brigadier isn't
      *                                   supported by the platform
diff --git a/cloud-minecraft/cloud-bukkit/src/main/java/cloud/commandframework/bukkit/CloudBukkitCapabilities.java b/cloud-minecraft/cloud-bukkit/src/main/java/cloud/commandframework/bukkit/CloudBukkitCapabilities.java
index 5bfb0d17e..e177d287f 100644
--- a/cloud-minecraft/cloud-bukkit/src/main/java/cloud/commandframework/bukkit/CloudBukkitCapabilities.java
+++ b/cloud-minecraft/cloud-bukkit/src/main/java/cloud/commandframework/bukkit/CloudBukkitCapabilities.java
@@ -34,16 +34,36 @@
  * Capabilities for the Bukkit module
  */
 public enum CloudBukkitCapabilities implements CloudCapability {
+    /**
+     * Whether Brigadier is present in the current environment. Certain parser types require this, and are able to work
+     * even if a capability for Brigadier command registration is not present (as long as this capability is present).
+     */
     BRIGADIER(CraftBukkitReflection.classExists("com.mojang.brigadier.tree.CommandNode")
             && CraftBukkitReflection.findOBCClass("command.BukkitCommandWrapper") != null),
 
+    /**
+     * Whether support for native Brigadier command registration is available
+     * through the Paper API ({@code PaperCommandManager#registerBrigadier} from {@code cloud-paper}).
+     */
     NATIVE_BRIGADIER(CraftBukkitReflection.classExists(
             "com.destroystokyo.paper.event.brigadier.CommandRegisteredEvent")),
 
+    /**
+     * Whether support for Brigadier command registration is available through Commodore
+     * ({@link BukkitCommandManager#registerBrigadier}).
+     *
+     * <p><b>Note:</b> As of 1.19.2, Commodore simply delegates to the same Paper API as cloud is capable of using directly,
+     * doing nothing on non-Paper Bukkit implementations. As such, this capability will not be present in 1.19.2+ environments.
+     * Users should prefer using {@code PaperCommandManager} from {@code cloud-paper} and checking for
+     * {@link #NATIVE_BRIGADIER}.</p>
+     */
     COMMODORE_BRIGADIER(BRIGADIER.capable()
             && !NATIVE_BRIGADIER.capable()
             && !CraftBukkitReflection.classExists("org.bukkit.entity.Warden")),
 
+    /**
+     * Whether asynchronous command completions are supported through the Paper API.
+     */
     ASYNCHRONOUS_COMPLETION(CraftBukkitReflection.classExists(
             "com.destroystokyo.paper.event.server.AsyncTabCompleteEvent"));
 
diff --git a/cloud-minecraft/cloud-paper/src/main/java/cloud/commandframework/paper/PaperCommandManager.java b/cloud-minecraft/cloud-paper/src/main/java/cloud/commandframework/paper/PaperCommandManager.java
index 42d29d4d6..c6592b6f0 100644
--- a/cloud-minecraft/cloud-paper/src/main/java/cloud/commandframework/paper/PaperCommandManager.java
+++ b/cloud-minecraft/cloud-paper/src/main/java/cloud/commandframework/paper/PaperCommandManager.java
@@ -113,7 +113,16 @@ public PaperCommandManager(
     }
 
     /**
-     * Register Brigadier mappings using the native paper events
+     * Attempts to enable Brigadier command registration through the Paper API, falling
+     * back to {@link BukkitCommandManager#registerBrigadier()} if that fails.
+     *
+     * <p>Callers should check for {@link CloudBukkitCapabilities#NATIVE_BRIGADIER} first
+     * to avoid exceptions.</p>
+     *
+     * <p>A check for {@link CloudBukkitCapabilities#NATIVE_BRIGADIER} {@code ||} {@link CloudBukkitCapabilities#COMMODORE_BRIGADIER}
+     * may also be appropriate for some use cases (because of the fallback behavior), but not most, as Commodore does not offer
+     * any functionality on modern
+     * versions (see the documentation for {@link CloudBukkitCapabilities#COMMODORE_BRIGADIER}).</p>
      *
      * @throws BrigadierFailureException Exception thrown if the mappings cannot be registered
      */
diff --git a/examples/example-bukkit/build.gradle.kts b/examples/example-bukkit/build.gradle.kts
index 592d9aaa4..0128b3d7b 100644
--- a/examples/example-bukkit/build.gradle.kts
+++ b/examples/example-bukkit/build.gradle.kts
@@ -12,9 +12,6 @@ dependencies {
     implementation(project(":cloud-annotations"))
     implementation(project(":cloud-minecraft-extras"))
     /* Extras */
-    implementation(libs.commodore) {
-        isTransitive = false
-    }
     implementation(libs.adventurePlatformBukkit)
     /* Bukkit */
     compileOnly(libs.bukkit)
@@ -25,7 +22,6 @@ dependencies {
 tasks {
     shadowJar {
         relocate("net.kyori", "cloud.commandframework.example.kyori")
-        relocate("me.lucko", "cloud.commandframework.example.lucko")
         relocate("io.leangen.geantyref", "cloud.commandframework.example.geantyref")
     }
     assemble {
diff --git a/examples/example-bukkit/src/main/java/cloud/commandframework/examples/bukkit/ExamplePlugin.java b/examples/example-bukkit/src/main/java/cloud/commandframework/examples/bukkit/ExamplePlugin.java
index ee4aeadb5..caf24f0a5 100644
--- a/examples/example-bukkit/src/main/java/cloud/commandframework/examples/bukkit/ExamplePlugin.java
+++ b/examples/example-bukkit/src/main/java/cloud/commandframework/examples/bukkit/ExamplePlugin.java
@@ -174,7 +174,7 @@ public void onEnable() {
         //
         // Register Brigadier mappings
         //
-        if (this.manager.hasCapability(CloudBukkitCapabilities.BRIGADIER)) {
+        if (this.manager.hasCapability(CloudBukkitCapabilities.NATIVE_BRIGADIER)) {
             this.manager.registerBrigadier();
         }
         //