Improve docs around Brigadier on bukkit/paper

Incendo · Sep 9, 2023 · 5bd2b90 · 5bd2b90
1 parent c8f0703
commit 5bd2b90
Show file tree

Hide file tree

Showing 5 changed files with 35 additions and 7 deletions.
diff --git a/...ecraft/cloud-bukkit/src/main/java/cloud/commandframework/bukkit/BukkitCommandManager.java b/...ecraft/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/...aft/cloud-bukkit/src/main/java/cloud/commandframework/bukkit/CloudBukkitCapabilities.java b/...aft/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/...minecraft/cloud-paper/src/main/java/cloud/commandframework/paper/PaperCommandManager.java b/...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
@@ -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/...es/example-bukkit/src/main/java/cloud/commandframework/examples/bukkit/ExamplePlugin.java b/...es/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();
         }
         //