twin/paper-mc
1
0
Fork 0
mirror of https://github.com/PaperMC/Paper.git synced 2025-08-14 11:45:52 -07:00
Code Issues Packages Projects Releases Wiki Activity

Pulling all pending Bukkit-JavaDoc changes

Browse Source 
A special thanks goes to @aerouk for almost all of the changes found here.

By: Wesley Wolfe <weswolf@aol.com>
This commit is contained in:
Bukkit/Spigot
2013-12-15 01:07:43 -05:00
parent 800679913f
commit bb50f1a774
310 changed files with 4218 additions and 2904 deletions
Download Patch File Download Diff File Expand all files Collapse all files

47
paper-api/src/main/java/org/bukkit/command/Command.java
View File

@@ -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
*/

6
paper-api/src/main/java/org/bukkit/command/CommandException.java
View File

@@ -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.
*/

72
paper-api/src/main/java/org/bukkit/command/CommandMap.java
View File

@@ -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;

21
paper-api/src/main/java/org/bukkit/command/PluginCommand.java
View File

@@ -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

9
paper-api/src/main/java/org/bukkit/command/PluginIdentifiableCommand.java
View File

@@ -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.
*

14
paper-api/src/main/java/org/bukkit/command/SimpleCommandMap.java
View File

@@ -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();

3
paper-api/src/main/java/org/bukkit/command/TabCommandExecutor.java
View File

@@ -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

6
paper-api/src/main/java/org/bukkit/command/TabCompleter.java
View File

@@ -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);
}

3
paper-api/src/main/java/org/bukkit/command/TabExecutor.java
View File

@@ -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 {
}