Remove CommandResult#empty()

* This was just causing confusion as it indicated an error condition to the processor. Instead, if you have an error condition, you should indicate it using CommandResult#error(...).

Author: dualspiral

src/main/java/org/spongepowered/api/command/CommandResult.java

@@ -45,23 +45,21 @@ static Builder builder() {
     }
 
     /**
-     * Builds a result that indicates successes.
+     * Builds a result that indicates success (where {@link Builder#result(int)}
+     * is set to 1.
+     *
+     * <p>Note that a successful result is one where the command has done what
+     * is expected of it. This should be used in place of "empty" from previous
+     * API iterations. If an error condition should be reported, use
+     * {@link #error(Component)} instead, which will allow the system to react
+     * accordingly.</p>
      *
      * @return The {@link CommandResult}
      */
     static CommandResult success() {
         return CommandResults.SUCCESS;
     }
 
-    /**
-     * Builds an empty result.
-     *
-     * @return The {@link CommandResult}
-     */
-    static CommandResult empty() {
-        return CommandResults.EMPTY;
-    }
-
     /**
      * Builds an empty result that will prompt the command manager to send an
      * error message without throwing an exception.
@@ -105,7 +103,8 @@ interface Builder extends org.spongepowered.api.util.Builder<CommandResult, Buil
          *
          * <ul>
          *     <li>A positive value indicates successful execution,</li>
-         *     <li>Zero indicates the command didn't fulfil its task</li>
+         *     <li>Zero (generally) indicates the command didn't fulfil its
+         *     task, though that is not necessarily an error condition.</li>
          *     <li>A negative value is undefined in the API, if returned, the
          *     effects are implementation specific.</li>
          * </ul>
@@ -116,11 +115,12 @@ interface Builder extends org.spongepowered.api.util.Builder<CommandResult, Buil
         Builder result(int result);
 
         /**
-         * Sets or removes the error message to return to the user without
-         * throwing an exception.
+         * Sets the built result to report an error, with an optional error
+         * message.
          *
          * <p>If this is set, then the command parser will send this message to
-         * the command invoker.</p>
+         * the command invoker. Otherwise, the parser will report an unknown
+         * exception.</p>
          *
          * @param errorMessage The message to send to the user.
          * @return This builder, for chaining

src/main/java/org/spongepowered/api/command/CommandResults.java

@@ -37,7 +37,7 @@ public final class CommandResults {
     /**
      * Indicates that the command executed but was unable to carry out its task.
      */
-    public static final CommandResult EMPTY = CommandResult.builder().build();
+    public static final CommandResult UNKNOWN_ERROR = CommandResult.builder().error(null).build();
 
     private CommandResults() {
         throw new AssertionError("You shouldn't be trying to instantiate this");