Merge branch 'api-8' into api-9

Author: dualspiral

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

@@ -30,10 +30,12 @@
 import org.spongepowered.api.Sponge;
 import org.spongepowered.api.command.exception.ArgumentParseException;
 import org.spongepowered.api.command.exception.CommandException;
+import org.spongepowered.api.command.manager.CommandMapping;
 import org.spongepowered.api.command.parameter.ArgumentReader;
 import org.spongepowered.api.command.parameter.CommandContext;
 import org.spongepowered.api.command.parameter.Parameter;
 import org.spongepowered.api.command.parameter.managed.Flag;
+import org.spongepowered.api.command.registrar.CommandRegistrar;
 import org.spongepowered.api.command.registrar.tree.CommandTreeNode;
 import org.spongepowered.api.command.registrar.tree.CommandTreeNodeTypes;
 import org.spongepowered.api.event.Cause;
@@ -130,7 +132,11 @@ static Builder builder() {
     /**
      * Gets a short one-line description of this command.
      *
-     * <p>The help system may display the description in the command list.</p>
+     * <p>The help system may display the description in the command list, or
+     * in any other function that displays a command list. It is therefore
+     * recommended that any description here is kept very short.</p>
+     *
+     * @see CommandRegistrar#shortDescription(CommandCause, CommandMapping)
      *
      * @param cause The {@link CommandCause} of the help request
      * @return A description
@@ -157,6 +163,8 @@ static Builder builder() {
      * <p>The help system may display this message when a source requests
      * detailed information about a command.</p>
      *
+     * @see CommandRegistrar#help(CommandCause, CommandMapping)
+     *
      * @param cause The {@link Cause} of the help request
      * @return A help text
      */

src/main/java/org/spongepowered/api/command/manager/CommandManager.java

@@ -164,6 +164,14 @@ public interface CommandManager {
      */
     Set<String> knownAliases();
 
+    /**
+     * Gets all the {@link CommandMapping mappings} known to this command
+     * manager.
+     *
+     * @return The known mappings.
+     */
+    Set<CommandMapping> knownMappings();
+
     /**
      * Gets a {@link Collection} of {@link PluginContainer}s with commands
      * registered.

src/main/java/org/spongepowered/api/command/registrar/CommandRegistrar.java

@@ -142,7 +142,30 @@ CommandMapping register(
     List<CommandCompletion> complete(CommandCause cause, CommandMapping mapping, String command, String arguments) throws CommandException;
 
     /**
-     * Returns help text for the invoked command.
+     * Returns a short description for the invoked command, if one is
+     * available.
+     *
+     * <p>A good short description is not necessarily help, rather, it should
+     * be a short description of the command's function. This short description
+     * <strong>may</strong> also be part of the
+     * {@link #help(CommandCause, CommandMapping) standard help} for the
+     * function.</p>
+     *
+     * <p>It is recommended that any description here is kept very short as such
+     * a description may be used in a command listing.</p>
+     *
+     * @param cause The {@link CommandCause} that caused the command to be
+     *              executed
+     * @param mapping The {@link CommandMapping} that is associated with the
+     *                command
+     * @return The help, if any
+     */
+    default Optional<Component> shortDescription(final CommandCause cause, final CommandMapping mapping) {
+        return Optional.empty();
+    }
+
+    /**
+     * Returns help text for the invoked command, if one is available.
      *
      * @param cause The {@link CommandCause} that caused the command to be
      *              executed