diff options
author | Wesley Wolfe <weswolf@aol.com> | 2013-12-15 01:07:43 -0500 |
---|---|---|
committer | Wesley Wolfe <weswolf@aol.com> | 2013-12-15 01:09:18 -0500 |
commit | d8b48c2ec9f38a921ac54f5655a2da2d88f10ec5 (patch) | |
tree | 52ad0a3c379beb3fa5d8b0f368b0ade6649b8459 /src/main/java/org/bukkit/command | |
parent | 49a400e44a10dfdbccea86a1c76fb94ab2e666bf (diff) | |
download | bukkit-d8b48c2ec9f38a921ac54f5655a2da2d88f10ec5.tar bukkit-d8b48c2ec9f38a921ac54f5655a2da2d88f10ec5.tar.gz bukkit-d8b48c2ec9f38a921ac54f5655a2da2d88f10ec5.tar.lz bukkit-d8b48c2ec9f38a921ac54f5655a2da2d88f10ec5.tar.xz bukkit-d8b48c2ec9f38a921ac54f5655a2da2d88f10ec5.zip |
Pulling all pending Bukkit-JavaDoc changes
A special thanks goes to @aerouk for almost all of the changes found here.
Diffstat (limited to 'src/main/java/org/bukkit/command')
9 files changed, 120 insertions, 61 deletions
diff --git a/src/main/java/org/bukkit/command/Command.java b/src/main/java/org/bukkit/command/Command.java index 4ad60996..1c235720 100644 --- a/src/main/java/org/bukkit/command/Command.java +++ b/src/main/java/org/bukkit/command/Command.java @@ -64,13 +64,14 @@ public abstract class Command { } /** - * Executed on tab completion for this command, returning a list of options - * the player can tab through. + * Executed on tab completion for this command, returning a list of + * options the player can tab through. * * @param sender Source object which is executing this command * @param alias the alias being used * @param args All arguments passed to the command, split via ' ' - * @return a list of tab-completions for the specified arguments. This will never be null. List may be immutable. + * @return a list of tab-completions for the specified arguments. This + * will never be null. List may be immutable. * @throws IllegalArgumentException if sender, alias, or args is null */ public List<String> tabComplete(CommandSender sender, String alias, String[] args) throws IllegalArgumentException { @@ -108,7 +109,8 @@ public abstract class Command { } /** - * Gets the permission required by users to be able to perform this command + * Gets the permission required by users to be able to perform this + * command * * @return Permission name, or null if none */ @@ -117,7 +119,8 @@ public abstract class Command { } /** - * Sets the permission required by users to be able to perform this command + * Sets the permission required by users to be able to perform this + * command * * @param permission Permission name or null */ @@ -126,9 +129,11 @@ public abstract class Command { } /** - * Tests the given {@link CommandSender} to see if they can perform this command. + * Tests the given {@link CommandSender} to see if they can perform this + * command. * <p> - * If they do not have permission, they will be informed that they cannot do this. + * If they do not have permission, they will be informed that they cannot + * do this. * * @param target User to test * @return true if they can use it, otherwise false @@ -150,7 +155,8 @@ public abstract class Command { } /** - * Tests the given {@link CommandSender} to see if they can perform this command. + * Tests the given {@link CommandSender} to see if they can perform this + * command. * <p> * No error is sent to the sender. * @@ -181,12 +187,14 @@ public abstract class Command { } /** - * Sets the label of this command - * If the command is currently registered the label change will only take effect after - * its been reregistered e.g. after a /reload + * Sets the label of this command. + * <p> + * If the command is currently registered the label change will only take + * effect after its been re-registered e.g. after a /reload * * @param name The command's name - * @return returns true if the name change happened instantly or false if it was scheduled for reregistration + * @return returns true if the name change happened instantly or false if + * it was scheduled for re-registration */ public boolean setLabel(String name) { this.nextLabel = name; @@ -198,11 +206,12 @@ public abstract class Command { } /** - * Registers this command to a CommandMap + * Registers this command to a CommandMap. * Once called it only allows changes the registered CommandMap * * @param commandMap the CommandMap to register this command to - * @return true if the registration was successful (the current registered CommandMap was the passed CommandMap or null) false otherwise + * @return true if the registration was successful (the current registered + * CommandMap was the passed CommandMap or null) false otherwise */ public boolean register(CommandMap commandMap) { if (allowChangesFrom(commandMap)) { @@ -214,10 +223,13 @@ public abstract class Command { } /** - * Unregisters this command from the passed CommandMap applying any outstanding changes + * Unregisters this command from the passed CommandMap applying any + * outstanding changes * * @param commandMap the CommandMap to unregister - * @return true if the unregistration was successfull (the current registered CommandMap was the passed CommandMap or null) false otherwise + * @return true if the unregistration was successfull (the current + * registered CommandMap was the passed CommandMap or null) false + * otherwise */ public boolean unregister(CommandMap commandMap) { if (allowChangesFrom(commandMap)) { @@ -253,7 +265,8 @@ public abstract class Command { } /** - * Returns a message to be displayed on a failed permission check for this command + * Returns a message to be displayed on a failed permission check for this + * command * * @return Permission check failed message */ diff --git a/src/main/java/org/bukkit/command/CommandException.java b/src/main/java/org/bukkit/command/CommandException.java index 76c1a016..b63015f4 100644 --- a/src/main/java/org/bukkit/command/CommandException.java +++ b/src/main/java/org/bukkit/command/CommandException.java @@ -7,12 +7,14 @@ package org.bukkit.command; public class CommandException extends RuntimeException { /** - * Creates a new instance of <code>CommandException</code> without detail message. + * Creates a new instance of <code>CommandException</code> without detail + * message. */ public CommandException() {} /** - * Constructs an instance of <code>CommandException</code> with the specified detail message. + * Constructs an instance of <code>CommandException</code> with the + * specified detail message. * * @param msg the detail message. */ diff --git a/src/main/java/org/bukkit/command/CommandMap.java b/src/main/java/org/bukkit/command/CommandMap.java index e7fad287..e7e20d89 100644 --- a/src/main/java/org/bukkit/command/CommandMap.java +++ b/src/main/java/org/bukkit/command/CommandMap.java @@ -6,37 +6,62 @@ public interface CommandMap { /** * Registers all the commands belonging to a certain plugin. + * <p> * Caller can use:- - * command.getName() to determine the label registered for this command - * command.getAliases() to determine the aliases which where registered + * <ul> + * <li>command.getName() to determine the label registered for this + * command + * <li>command.getAliases() to determine the aliases which where + * registered + * </ul> * - * @param fallbackPrefix a prefix which is prepended to each command with a ':' one or more times to make the command unique + * @param fallbackPrefix a prefix which is prepended to each command with + * a ':' one or more times to make the command unique * @param commands a list of commands to register */ public void registerAll(String fallbackPrefix, List<Command> commands); /** - * Registers a command. Returns true on success; false if name is already taken and fallback had to be used. + * Registers a command. Returns true on success; false if name is already + * taken and fallback had to be used. + * <p> * Caller can use:- - * command.getName() to determine the label registered for this command - * command.getAliases() to determine the aliases which where registered + * <ul> + * <li>command.getName() to determine the label registered for this + * command + * <li>command.getAliases() to determine the aliases which where + * registered + * </ul> * * @param label the label of the command, without the '/'-prefix. - * @param fallbackPrefix a prefix which is prepended to the command with a ':' one or more times to make the command unique + * @param fallbackPrefix a prefix which is prepended to the command with a + * ':' one or more times to make the command unique * @param command the command to register - * @return true if command was registered with the passed in label, false otherwise, which indicates the fallbackPrefix was used one or more times + * @return true if command was registered with the passed in label, false + * otherwise, which indicates the fallbackPrefix was used one or more + * times */ public boolean register(String label, String fallbackPrefix, Command command); /** - * Registers a command. Returns true on success; false if name is already taken and fallback had to be used. + * Registers a command. Returns true on success; false if name is already + * taken and fallback had to be used. + * <p> * Caller can use:- - * command.getName() to determine the label registered for this command - * command.getAliases() to determine the aliases which where registered + * <ul> + * <li>command.getName() to determine the label registered for this + * command + * <li>command.getAliases() to determine the aliases which where + * registered + * </ul> * - * @param fallbackPrefix a prefix which is prepended to the command with a ':' one or more times to make the command unique - * @param command the command to register, from which label is determined from the command name - * @return true if command was registered with the passed in label, false otherwise, which indicates the fallbackPrefix was used one or more times + * @param fallbackPrefix a prefix which is prepended to the command with a + * ':' one or more times to make the command unique + * @param command the command to register, from which label is determined + * from the command name + * @return true if command was registered with the passed in label, false + * otherwise, which indicates the fallbackPrefix was used one or more + * times */ public boolean register(String fallbackPrefix, Command command); @@ -46,7 +71,8 @@ public interface CommandMap { * @param sender The command's sender * @param cmdLine command + arguments. Example: "/test abc 123" * @return returns false if no target is found, true otherwise. - * @throws CommandException Thrown when the executor for the given command fails with an unhandled exception + * @throws CommandException Thrown when the executor for the given command + * fails with an unhandled exception */ public boolean dispatch(CommandSender sender, String cmdLine) throws CommandException; @@ -59,18 +85,24 @@ public interface CommandMap { * Gets the command registered to the specified name * * @param name Name of the command to retrieve - * @return Command with the specified name or null if a command with that label doesn't exist + * @return Command with the specified name or null if a command with that + * label doesn't exist */ public Command getCommand(String name); /** - * Looks for the requested command and executes an appropriate tab-completer if found. This method will also tab-complete partial commands. + * Looks for the requested command and executes an appropriate + * tab-completer if found. This method will also tab-complete partial + * commands. * * @param sender The command's sender. - * @param cmdLine The entire command string to tab-complete, excluding initial slash. - * @return a list of possible tab-completions. This list may be immutable. Will be null if no matching command of which sender has permission. - * @throws CommandException Thrown when the tab-completer for the given command fails with an unhandled exception + * @param cmdLine The entire command string to tab-complete, excluding + * initial slash. + * @return a list of possible tab-completions. This list may be immutable. + * Will be null if no matching command of which sender has permission. + * @throws CommandException Thrown when the tab-completer for the given + * command fails with an unhandled exception * @throws IllegalArgumentException if either sender or cmdLine are null */ public List<String> tabComplete(CommandSender sender, String cmdLine) throws IllegalArgumentException; diff --git a/src/main/java/org/bukkit/command/PluginCommand.java b/src/main/java/org/bukkit/command/PluginCommand.java index f90ee7e0..3bfa31fc 100644 --- a/src/main/java/org/bukkit/command/PluginCommand.java +++ b/src/main/java/org/bukkit/command/PluginCommand.java @@ -104,17 +104,20 @@ public final class PluginCommand extends Command implements PluginIdentifiableCo } /** - * {@inheritDoc}<br> - * <br> - * Delegates to the tab completer if present.<br> - * If it is not present or returns null, will delegate to the current command - * executor if it implements {@link TabCompleter}. If a non-null list has not - * been found, will default to standard player name completion in - * {@link Command#tabComplete(CommandSender, String, String[])}.<br> - * <br> + * {@inheritDoc} + * <p> + * Delegates to the tab completer if present. + * <p> + * If it is not present or returns null, will delegate to the current + * command executor if it implements {@link TabCompleter}. If a non-null + * list has not been found, will default to standard player name + * completion in {@link + * Command#tabComplete(CommandSender, String, String[])}. + * <p> * This method does not consider permissions. * - * @throws CommandException if the completer or executor throw an exception during the process of tab-completing. + * @throws CommandException if the completer or executor throw an + * exception during the process of tab-completing. * @throws IllegalArgumentException if sender, alias, or args is null */ @Override diff --git a/src/main/java/org/bukkit/command/PluginIdentifiableCommand.java b/src/main/java/org/bukkit/command/PluginIdentifiableCommand.java index c58abb66..c5e0d2c4 100644 --- a/src/main/java/org/bukkit/command/PluginIdentifiableCommand.java +++ b/src/main/java/org/bukkit/command/PluginIdentifiableCommand.java @@ -3,12 +3,13 @@ package org.bukkit.command; import org.bukkit.plugin.Plugin; /** - * This interface is used by the help system to group commands into sub-indexes based - * on the {@link Plugin} they are a part of. Custom command implementations will need to - * implement this interface to have a sub-index automatically generated on the plugin's - * behalf. + * This interface is used by the help system to group commands into + * sub-indexes based on the {@link Plugin} they are a part of. Custom command + * implementations will need to implement this interface to have a sub-index + * automatically generated on the plugin's behalf. */ public interface PluginIdentifiableCommand { + /** * Gets the owner of this PluginIdentifiableCommand. * diff --git a/src/main/java/org/bukkit/command/SimpleCommandMap.java b/src/main/java/org/bukkit/command/SimpleCommandMap.java index f7167824..c2f488a7 100644 --- a/src/main/java/org/bukkit/command/SimpleCommandMap.java +++ b/src/main/java/org/bukkit/command/SimpleCommandMap.java @@ -117,14 +117,18 @@ public class SimpleCommandMap implements CommandMap { } /** - * Registers a command with the given name is possible, otherwise uses fallbackPrefix to create a unique name if its not an alias + * Registers a command with the given name is possible, otherwise uses + * fallbackPrefix to create a unique name if its not an alias * * @param label the name of the command, without the '/'-prefix. - * @param fallbackPrefix a prefix which is prepended to the command with a ':' one or more times to make the command unique + * @param fallbackPrefix a prefix which is prepended to the command with a + * ':' one or more times to make the command unique * @param command the command to register - * @return true if command was registered with the passed in label, false otherwise. - * If isAlias was true a return of false indicates no command was registerd - * If isAlias was false a return of false indicates the fallbackPrefix was used one or more times to create a unique name for the command + * @return true if command was registered with the passed in label, false + * otherwise. If isAlias was true a return of false indicates no + * command was registered. If isAlias was false a return of false + * indicates the fallbackPrefix was used one or more times to create a + * unique name for the command */ private synchronized boolean register(String label, String fallbackPrefix, Command command, boolean isAlias) { String lowerLabel = label.trim().toLowerCase(); diff --git a/src/main/java/org/bukkit/command/TabCommandExecutor.java b/src/main/java/org/bukkit/command/TabCommandExecutor.java index bf6ddd4e..d24d795c 100644 --- a/src/main/java/org/bukkit/command/TabCommandExecutor.java +++ b/src/main/java/org/bukkit/command/TabCommandExecutor.java @@ -5,7 +5,8 @@ import java.util.List; /** * Represents a class which can handle command tab completion and commands * - * @deprecated Remains for plugins that would have implemented it even without functionality + * @deprecated Remains for plugins that would have implemented it even without + * functionality * @see TabExecutor */ @Deprecated diff --git a/src/main/java/org/bukkit/command/TabCompleter.java b/src/main/java/org/bukkit/command/TabCompleter.java index 3ba64fe8..6d61e3ab 100644 --- a/src/main/java/org/bukkit/command/TabCompleter.java +++ b/src/main/java/org/bukkit/command/TabCompleter.java @@ -13,8 +13,10 @@ public interface TabCompleter { * @param sender Source of the command * @param command Command which was executed * @param alias The alias used - * @param args The arguments passed to the command, including final partial argument to be completed and command label - * @return A List of possible completions for the final argument, or null to default to the command executor + * @param args The arguments passed to the command, including final + * partial argument to be completed and command label + * @return A List of possible completions for the final argument, or null + * to default to the command executor */ public List<String> onTabComplete(CommandSender sender, Command command, String alias, String[] args); } diff --git a/src/main/java/org/bukkit/command/TabExecutor.java b/src/main/java/org/bukkit/command/TabExecutor.java index 67b3503d..6b8e3fb2 100644 --- a/src/main/java/org/bukkit/command/TabExecutor.java +++ b/src/main/java/org/bukkit/command/TabExecutor.java @@ -1,7 +1,8 @@ package org.bukkit.command; /** - * This class is provided as a convenience to implement both TabCompleter and CommandExecutor. + * This class is provided as a convenience to implement both TabCompleter and + * CommandExecutor. */ public interface TabExecutor extends TabCompleter, CommandExecutor { } |