Merge pull request #515 from hugmanrique/dev-3/command-api-changes

[3.0] Document some restrictions in the command API

api/src/main/java/com/velocitypowered/api/command/BrigadierCommand.java

@@ -18,7 +18,7 @@ import com.mojang.brigadier.tree.LiteralCommandNode;
 public final class BrigadierCommand implements Command {
 
   /**
-   * Return code used by a {@link com.mojang.brigadier.Command} to indicate
+   * The return code used by a {@link com.mojang.brigadier.Command} to indicate
    * the command execution should be forwarded to the backend server.
    */
   public static final int FORWARD = 0xF6287429;

api/src/main/java/com/velocitypowered/api/command/Command.java

@@ -17,8 +17,8 @@ import org.checkerframework.checker.nullness.qual.NonNull;
  * Represents a command that can be executed by a {@link CommandSource}
  * such as a {@link Player} or the console.
  *
- * <p>Velocity 1.1.0 introduces specialized command subinterfaces to separate
+ * <p><strong>You must not subclass <code>Command</code></strong>. Use one of the following
- * command parsing concerns. These include, in order of preference:
+ * <i>registrable</i> subinterfaces:</p>
  *
  * <ul>
  * <li>{@link BrigadierCommand}, which supports parameterized arguments and

api/src/main/java/com/velocitypowered/api/command/CommandManager.java

@@ -39,7 +39,9 @@ public interface CommandManager {
    * @param alias the first command alias
    * @param command the command to register
    * @param otherAliases additional aliases
-   * @throws IllegalArgumentException if one of the given aliases is already registered
+   * @throws IllegalArgumentException if one of the given aliases is already registered, or
+   *         the given command does not implement a registrable {@link Command} subinterface
+   * @see Command for a list of registrable {@link Command} subinterfaces
    */
   default void register(String alias, Command command, String... otherAliases) {
     register(metaBuilder(alias).aliases(otherAliases).build(), command);
@@ -58,7 +60,9 @@ public interface CommandManager {
    *
    * @param meta the command metadata
    * @param command the command to register
-   * @throws IllegalArgumentException if one of the given aliases is already registered
+   * @throws IllegalArgumentException if one of the given aliases is already registered, or
+   *         the given command does not implement a registrable {@link Command} subinterface
+   * @see Command for a list of registrable {@link Command} subinterfaces
    */
   void register(CommandMeta meta, Command command);
 

api/src/main/java/com/velocitypowered/api/command/CommandMeta.java

@@ -24,8 +24,8 @@ public interface CommandMeta {
   Collection<String> getAliases();
 
   /**
-   * Returns a collection containing command nodes that provide additional
+   * Returns an immutable collection containing command nodes that provide
-   * argument metadata and tab-complete suggestions.
+   * additional argument metadata and tab-complete suggestions.
    * Note some {@link Command} implementations may not support hinting.
    *
    * @return the hinting command nodes
@@ -51,6 +51,8 @@ public interface CommandMeta {
      *
      * @param node the command node
      * @return this builder, for chaining
+     * @throws IllegalArgumentException if the node is executable, i.e. has a non-null
+     *         {@link com.mojang.brigadier.Command}, or has a redirect.
      */
     Builder hint(CommandNode<CommandSource> node);
 

api/src/main/java/com/velocitypowered/api/command/InvocableCommand.java

@@ -14,6 +14,11 @@ import java.util.concurrent.CompletableFuture;
 /**
  * A command that can be executed with arbitrary arguments.
  *
+ * <p>Modifying the command tree (e.g. registering a command via
+ * {@link CommandManager#register(CommandMeta, Command)}) during
+ * permission checking and suggestions provision results in
+ * undefined behavior, which may include deadlocks.
+ *
  * @param <I> the type of the command invocation object
  */
 public interface InvocableCommand<I extends CommandInvocation<?>> extends Command {