diff options
author | Wesley Wolfe <weswolf@aol.com> | 2014-03-24 13:20:52 -0500 |
---|---|---|
committer | Wesley Wolfe <weswolf@aol.com> | 2014-03-24 13:20:52 -0500 |
commit | 7c4a4dc3b2b26d0ee4fd0d52f50f2d699963aa04 (patch) | |
tree | 6a2c08c8cb1d561566bc422644cbda1ef5954083 | |
parent | e6be37d9e39145183e47490b9d92e783ad14fb17 (diff) | |
download | bukkit-7c4a4dc3b2b26d0ee4fd0d52f50f2d699963aa04.tar bukkit-7c4a4dc3b2b26d0ee4fd0d52f50f2d699963aa04.tar.gz bukkit-7c4a4dc3b2b26d0ee4fd0d52f50f2d699963aa04.tar.lz bukkit-7c4a4dc3b2b26d0ee4fd0d52f50f2d699963aa04.tar.xz bukkit-7c4a4dc3b2b26d0ee4fd0d52f50f2d699963aa04.zip |
Pulling all pending Bukkit-JavaDoc changes
-rw-r--r-- | src/main/java/org/bukkit/BanEntry.java | 104 | ||||
-rw-r--r-- | src/main/java/org/bukkit/BanList.java | 70 | ||||
-rw-r--r-- | src/main/java/org/bukkit/Bukkit.java | 2 | ||||
-rw-r--r-- | src/main/java/org/bukkit/Material.java | 2 | ||||
-rw-r--r-- | src/main/java/org/bukkit/OfflinePlayer.java | 6 | ||||
-rw-r--r-- | src/main/java/org/bukkit/Server.java | 332 | ||||
-rw-r--r-- | src/main/java/org/bukkit/World.java | 2 | ||||
-rw-r--r-- | src/main/java/org/bukkit/entity/Projectile.java | 2 | ||||
-rw-r--r-- | src/main/java/org/bukkit/event/EventPriority.java | 3 | ||||
-rw-r--r-- | src/main/java/org/bukkit/event/player/AsyncPlayerChatEvent.java | 4 | ||||
-rw-r--r-- | src/main/java/org/bukkit/event/player/PlayerStatisticIncrementEvent.java | 14 | ||||
-rw-r--r-- | src/main/java/org/bukkit/scoreboard/Team.java | 6 |
12 files changed, 299 insertions, 248 deletions
diff --git a/src/main/java/org/bukkit/BanEntry.java b/src/main/java/org/bukkit/BanEntry.java index 4359067a..986120e5 100644 --- a/src/main/java/org/bukkit/BanEntry.java +++ b/src/main/java/org/bukkit/BanEntry.java @@ -3,95 +3,125 @@ package org.bukkit; import java.util.Date; /** - * A single entry from the ban list. This may represent either a player ban or an - * IP ban.<br /> + * A single entry from a ban list. This may represent either a player ban or + * an IP ban. + * <p> * Ban entries include the following properties: - * <ul> - * <li><b>Target Name/IP Address</b> - The target name or IP address - * <li><b>Creation Date</b> - The creation date of the ban - * <li><b>Source</b> - The source of the ban, such as a player, console, plugin, etc - * <li><b>Expiration Date</b> - The expiration date of the ban - * <li><b>Reason</b> - The reason for the ban - * </ul> - * Unsaved information is not automatically written to the implementation's ban list, instead, - * the {@link #save()} method must be called to write the changes to the ban list. If this ban - * entry has expired (such as from an unban) and is no longer found in the list, the {@link #save()} - * call will re-add it to the list, therefore banning the victim specified. + * <table border=1> + * <tr> + * <th>Property</th> + * <th>Description</th> + * </tr><tr> + * <td>Target Name / IP Address</td> + * <td>The target name or IP address</td> + * </tr><tr> + * <td>Creation Date</td> + * <td>The creation date of the ban</td> + * </tr><tr> + * <td>Source</td> + * <td>The source of the ban, such as a player, console, plugin, etc</td> + * </tr><tr> + * <td>Expiration Date</td> + * <td>The expiration date of the ban</td> + * </tr><tr> + * <td>Reason</td> + * <td>The reason for the ban</td> + * </tr> + * </table> + * <p> + * Unsaved information is not automatically written to the implementation's + * ban list, instead, the {@link #save()} method must be called to write the + * changes to the ban list. If this ban entry has expired (such as from an + * unban) and is no longer found in the list, the {@link #save()} call will + * re-add it to the list, therefore banning the victim specified. + * <p> + * Likewise, changes to the associated {@link BanList} or other entries may or + * may not be reflected in this entry. */ public interface BanEntry { + /** - * Gets the target involved. This may be in the form of an IP or a player name. + * Gets the target involved. This may be in the form of an IP or a player + * name. * - * @return The target name or IP address + * @return the target name or IP address */ public String getTarget(); /** * Gets the date this ban entry was created. * - * @return The creation date + * @return the creation date */ public Date getCreated(); /** - * Sets the date this ban entry was created.<br /> - * Use {@link #save()} to save the changes. + * Sets the date this ban entry was created. * - * @param created The new created date, cannot be null + * @param created the new created date, cannot be null + * @see #save() saving changes */ public void setCreated(Date created); /** - * Gets the source of this ban.<br /> - * A source is considered any String, although this is generally a player name. + * Gets the source of this ban. + * <p> + * Note: A source is considered any String, although this is generally a + * player name. * - * @return The source of the ban + * @return the source of the ban */ public String getSource(); /** - * Sets the source of this ban.<br /> - * A source is considered any String, although this is generally a player name.<br /> - * Use {@link #save()} to save the changes. + * Sets the source of this ban. + * <p> + * Note: A source is considered any String, although this is generally a + * player name. * - * @param source The new source where null values become empty strings + * @param source the new source where null values become empty strings + * @see #save() saving changes */ public void setSource(String source); /** * Gets the date this ban expires on, or null for no defined end date. * - * @return The expiration date + * @return the expiration date */ public Date getExpiration(); /** - * Sets the date this ban expires on. Null values are considered "infinite" bans.<br /> - * Use {@link #save()} to save the changes. + * Sets the date this ban expires on. Null values are considered + * "infinite" bans. * - * @param expiry The new expiration date, or null to indicate an eternity + * @param expiration the new expiration date, or null to indicate an + * eternity + * @see #save() saving changes */ public void setExpiration(Date expiration); /** * Gets the reason for this ban. * - * @return The ban reason or null if not set + * @return the ban reason, or null if not set */ public String getReason(); /** - * Sets the reason for this ban. Reasons must not be null.<br /> - * Use {@link #save()} to save the changes. + * Sets the reason for this ban. Reasons must not be null. * - * @param reason The new reason, null values assume the implementation default + * @param reason the new reason, null values assume the implementation + * default + * @see #save() saving changes */ public void setReason(String reason); /** - * Saves the ban entry, overwriting any previous data in the ban list.<br /> - * Saving the ban entry of an unbanned player will cause the player to be banned once again. + * Saves the ban entry, overwriting any previous data in the ban list. + * <p> + * Saving the ban entry of an unbanned player will cause the player to be + * banned once again. */ public void save(); - } diff --git a/src/main/java/org/bukkit/BanList.java b/src/main/java/org/bukkit/BanList.java index 86ae7cd2..c21b858e 100644 --- a/src/main/java/org/bukkit/BanList.java +++ b/src/main/java/org/bukkit/BanList.java @@ -4,63 +4,69 @@ import java.util.Date; import java.util.Set; /** - * A ban list, containing bans of type {@link org.bukkit.BanList.Type} + * A ban list, containing bans of some {@link Type}. */ public interface BanList { + + /** + * Represents a ban-type that a {@link BanList} may track. + */ + public enum Type { + /** + * Banned player names + */ + NAME, + /** + * Banned player IP addresses + */ + IP, + ; + } + /** * Gets a {@link BanEntry} by target. * - * @param target Entry parameter to search for - * @return BanEntry for the submitted query, or null if none found + * @param target entry parameter to search for + * @return the corresponding entry, or null if none found */ public BanEntry getBanEntry(String target); /** - * Adds a ban to the ban list. If a previous ban exists, this will overwrite the previous - * entry. + * Adds a ban to the this list. If a previous ban exists, this will + * update the previous entry. * - * @param target The target of the ban - * @param reason Reason for the ban. If null, the implementation default is assumed - * @param expires Expiration Date of the ban. If null, "infinity" is assumed - * @param source Source of the ban. If null, the implementation default is assumed - * @return The BanEntry of the added ban + * @param target the target of the ban + * @param reason reason for the ban, null indicates implementation default + * @param expires date for the ban's expiration (unban), or null to imply + * forever + * @param source source of the ban, null indicates implementation default + * @return the entry for the newly created ban, or the entry for the + * (updated) previous ban */ public BanEntry addBan(String target, String reason, Date expires, String source); /** - * Gets a set containing every {@link BanEntry} in the BanList. + * Gets a set containing every {@link BanEntry} in this list. * - * @return an immutable set containing every BanEntry tracked by the BanList + * @return an immutable set containing every entry tracked by this list */ public Set<BanEntry> getBanEntries(); /** - * Gets if a {@link BanEntry} exists for the target, indicating ban status + * Gets if a {@link BanEntry} exists for the target, indicating an active + * ban status. * - * @param target Entry target to lookup - * @return true if a {@link BanEntry} exists for the name, indicating ban status + * @param target the target to find + * @return true if a {@link BanEntry} exists for the name, indicating an + * active ban status, false otherwise */ public boolean isBanned(String target); /** - * Removes the specified target from the list, therefore indicating a "not banned" status. + * Removes the specified target from this list, therefore indicating a + * "not banned" status. * - * @param target The target to remove from the list + * @param target the target to remove from this list */ public void pardon(String target); - - /** - * Represents the various types a {@link BanList} may track. - */ - public enum Type { - /** - * Banned player names - */ - NAME, - /** - * Banned player IP addresses - */ - IP; - } - } diff --git a/src/main/java/org/bukkit/Bukkit.java b/src/main/java/org/bukkit/Bukkit.java index a90b3901..53f8a372 100644 --- a/src/main/java/org/bukkit/Bukkit.java +++ b/src/main/java/org/bukkit/Bukkit.java @@ -451,7 +451,7 @@ public final class Bukkit { * @see Server#getBanList(BanList.Type) */ public static BanList getBanList(BanList.Type type){ - return server.getBanList(type); + return server.getBanList(type); } /** diff --git a/src/main/java/org/bukkit/Material.java b/src/main/java/org/bukkit/Material.java index 13d2cb74..c45c1805 100644 --- a/src/main/java/org/bukkit/Material.java +++ b/src/main/java/org/bukkit/Material.java @@ -59,7 +59,7 @@ import org.bukkit.util.Java15Compat; import com.google.common.collect.Maps; /** - * An enum of all material ids accepted by the official server + client + * An enum of all material IDs accepted by the official server and client */ public enum Material { AIR(0, 0), diff --git a/src/main/java/org/bukkit/OfflinePlayer.java b/src/main/java/org/bukkit/OfflinePlayer.java index 61964597..48a50a30 100644 --- a/src/main/java/org/bukkit/OfflinePlayer.java +++ b/src/main/java/org/bukkit/OfflinePlayer.java @@ -1,5 +1,7 @@ package org.bukkit; +import java.util.Date; + import org.bukkit.configuration.serialization.ConfigurationSerializable; import org.bukkit.entity.AnimalTamer; import org.bukkit.entity.Player; @@ -32,7 +34,9 @@ public interface OfflinePlayer extends ServerOperator, AnimalTamer, Configuratio * Bans or unbans this player * * @param banned true if banned - * @deprecated Use {@link org.bukkit.BanList#addBan(String, String, java.util.Date, String)} or {@link org.bukkit.BanList#unban(String)} to enhance functionality + * @deprecated Use {@link org.bukkit.BanList#addBan(String, String, Date, + * String)} or {@link org.bukkit.BanList#pardon(String)} to enhance + * functionality */ @Deprecated public void setBanned(boolean banned); diff --git a/src/main/java/org/bukkit/Server.java b/src/main/java/org/bukkit/Server.java index 3b6ea63b..b51b924e 100644 --- a/src/main/java/org/bukkit/Server.java +++ b/src/main/java/org/bukkit/Server.java @@ -23,6 +23,7 @@ import org.bukkit.inventory.InventoryHolder; import org.bukkit.inventory.ItemStack; import org.bukkit.inventory.Recipe; import org.bukkit.map.MapView; +import org.bukkit.permissions.Permissible; import org.bukkit.plugin.PluginManager; import org.bukkit.plugin.ServicesManager; import org.bukkit.plugin.messaging.Messenger; @@ -32,11 +33,12 @@ import org.bukkit.scoreboard.ScoreboardManager; import org.bukkit.util.CachedServerIcon; import com.avaje.ebean.config.ServerConfig; + import org.bukkit.inventory.ItemFactory; import org.bukkit.inventory.meta.ItemMeta; /** - * Represents a server implementation + * Represents a server implementation. */ public interface Server extends PluginMessageRecipient { @@ -44,7 +46,7 @@ public interface Server extends PluginMessageRecipient { * Used for all administrative messages, such as an operator using a * command. * <p> - * For use in {@link #broadcast(java.lang.String, java.lang.String)} + * For use in {@link #broadcast(java.lang.String, java.lang.String)}. */ public static final String BROADCAST_CHANNEL_ADMINISTRATIVE = "bukkit.broadcast.admin"; @@ -52,12 +54,12 @@ public interface Server extends PluginMessageRecipient { * Used for all announcement messages, such as informing users that a * player has joined. * <p> - * For use in {@link #broadcast(java.lang.String, java.lang.String)} + * For use in {@link #broadcast(java.lang.String, java.lang.String)}. */ public static final String BROADCAST_CHANNEL_USERS = "bukkit.broadcast.user"; /** - * Gets the name of this server implementation + * Gets the name of this server implementation. * * @return name of this server implementation */ @@ -73,51 +75,51 @@ public interface Server extends PluginMessageRecipient { /** * Gets the Bukkit version that this server is running. * - * @return Version of Bukkit + * @return version of Bukkit */ public String getBukkitVersion(); /** - * Gets a list of all currently logged in players + * Gets a list of all currently logged in players. * - * @return An array of Players that are currently online + * @return an array of Players that are currently online */ public Player[] getOnlinePlayers(); /** - * Get the maximum amount of players which can login to this server + * Get the maximum amount of players which can login to this server. * - * @return The amount of players this server allows + * @return the amount of players this server allows */ public int getMaxPlayers(); /** - * Get the game port that the server runs on + * Get the game port that the server runs on. * - * @return The port number of this server + * @return the port number of this server */ public int getPort(); /** * Get the view distance from this server. * - * @return The view distance from this server. + * @return the view distance from this server. */ public int getViewDistance(); /** - * Get the IP that this server is bound to or empty string if not - * specified + * Get the IP that this server is bound to, or empty string if not + * specified. * - * @return The IP string that this server is bound to, otherwise empty + * @return the IP string that this server is bound to, otherwise empty * string */ public String getIp(); /** - * Get the name of this server + * Get the name of this server. * - * @return The name of this server + * @return the name of this server */ public String getServerName(); @@ -125,61 +127,61 @@ public interface Server extends PluginMessageRecipient { * Get an ID of this server. The ID is a simple generally alphanumeric ID * that can be used for uniquely identifying this server. * - * @return The ID of this server + * @return the ID of this server */ public String getServerId(); /** - * Get world type (level-type setting) for default world + * Get world type (level-type setting) for default world. * - * @return The value of level-type (e.g. DEFAULT, FLAT, DEFAULT_1_1) + * @return the value of level-type (e.g. DEFAULT, FLAT, DEFAULT_1_1) */ public String getWorldType(); /** - * Get generate-structures setting + * Get generate-structures setting. * - * @return true if structure generation is enabled, false if not + * @return true if structure generation is enabled, false otherwise */ public boolean getGenerateStructures(); /** * Gets whether this server allows the End or not. * - * @return Whether this server allows the End or not. + * @return whether this server allows the End or not */ public boolean getAllowEnd(); /** * Gets whether this server allows the Nether or not. * - * @return Whether this server allows the Nether or not. + * @return whether this server allows the Nether or not */ public boolean getAllowNether(); /** * Gets whether this server has a whitelist or not. * - * @return Whether this server has a whitelist or not. + * @return whether this server has a whitelist or not */ public boolean hasWhitelist(); /** - * Sets the whitelist on or off + * Sets if the server is whitelisted. * - * @param value true if whitelist is on, otherwise false + * @param value true for whitelist on, false for off */ public void setWhitelist(boolean value); /** - * Gets a list of whitelisted players + * Gets a list of whitelisted players. * - * @return Set containing all whitelisted players + * @return a set containing all whitelisted players */ public Set<OfflinePlayer> getWhitelistedPlayers(); /** - * Reloads the whitelist from disk + * Reloads the whitelist from disk. */ public void reloadWhitelist(); @@ -200,7 +202,7 @@ public interface Server extends PluginMessageRecipient { * <p> * The update folder name is relative to the plugins folder. * - * @return The name of the update folder + * @return the name of the update folder */ public String getUpdateFolder(); @@ -208,19 +210,19 @@ public interface Server extends PluginMessageRecipient { * Gets the update folder. The update folder is used to safely update * plugins at the right moment on a plugin load. * - * @return The name of the update folder + * @return the update folder */ public File getUpdateFolderFile(); /** - * Gets the value of the connection throttle setting + * Gets the value of the connection throttle setting. * * @return the value of the connection throttle setting */ public long getConnectionThrottle(); /** - * Gets default ticks per animal spawns value + * Gets default ticks per animal spawns value. * <p> * <b>Example Usage:</b> * <ul> @@ -236,12 +238,12 @@ public interface Server extends PluginMessageRecipient { * <p> * Minecraft default: 400. * - * @return The default ticks per animal spawns value + * @return the default ticks per animal spawns value */ public int getTicksPerAnimalSpawns(); /** - * Gets the default ticks per monster spawns value + * Gets the default ticks per monster spawns value. * <p> * <b>Example Usage:</b> * <ul> @@ -257,65 +259,65 @@ public interface Server extends PluginMessageRecipient { * <p> * Minecraft default: 1. * - * @return The default ticks per monsters spawn value + * @return the default ticks per monsters spawn value */ public int getTicksPerMonsterSpawns(); /** - * Gets a player object by the given username + * Gets a player object by the given username. * <p> - * This method may not return objects for offline players + * This method may not return objects for offline players. * - * @param name Name to look up - * @return Player if it was found, otherwise null + * @param name the name to look up + * @return a player if one was found, null otherwise */ public Player getPlayer(String name); /** - * Gets the player with the exact given name, case insensitive + * Gets the player with the exact given name, case insensitive. * * @param name Exact name of the player to retrieve - * @return Player object or null if not found + * @return a player object if one was found, null otherwise */ public Player getPlayerExact(String name); /** * Attempts to match any players with the given name, and returns a list - * of all possibly matches + * of all possibly matches. * <p> * This list is not sorted in any particular order. If an exact match is * found, the returned list will only contain a single result. * - * @param name Name to match - * @return List of all possible players + * @param name the (partial) name to match + * @return list of all possible players */ public List<Player> matchPlayer(String name); /** - * Gets the PluginManager for interfacing with plugins + * Gets the plugin manager for interfacing with plugins. * - * @return PluginManager for this Server instance + * @return a plugin manager for this Server instance */ public PluginManager getPluginManager(); /** - * Gets the Scheduler for managing scheduled events + * Gets the scheduler for managing scheduled events. * - * @return Scheduler for this Server instance + * @return a scheduling service for this server */ public BukkitScheduler getScheduler(); /** - * Gets a services manager + * Gets a services manager. * - * @return Services manager + * @return s services manager */ public ServicesManager getServicesManager(); /** - * Gets a list of all worlds on this server + * Gets a list of all worlds on this server. * - * @return A list of worlds + * @return a list of worlds */ public List<World> getWorlds(); @@ -326,8 +328,8 @@ public interface Server extends PluginMessageRecipient { * If the world is already loaded, it will just return the equivalent of * getWorld(creator.name()). * - * @param creator The options to use when creating the world. - * @return Newly created or loaded world + * @param creator the options to use when creating the world + * @return newly created or loaded world */ public World createWorld(WorldCreator creator); @@ -335,41 +337,41 @@ public interface Server extends PluginMessageRecipient { * Unloads a world with the given name. * * @param name Name of the world to unload - * @param save Whether to save the chunks before unloading. - * @return Whether the action was Successful + * @param save whether to save the chunks before unloading + * @return true if successful, false otherwise */ public boolean unloadWorld(String name, boolean save); /** * Unloads the given world. * - * @param world The world to unload - * @param save Whether to save the chunks before unloading. - * @return Whether the action was Successful + * @param world the world to unload + * @param save whether to save the chunks before unloading + * @return true if successful, false otherwise */ public boolean unloadWorld(World world, boolean save); /** - * Gets the world with the given name + * Gets the world with the given name. * - * @param name Name of the world to retrieve - * @return World with the given name, or null if none exists + * @param name the name of the world to retrieve + * @return a world with the given name, or null if none exists */ public World getWorld(String name); /** - * Gets the world from the given Unique ID + * Gets the world from the given Unique ID. * - * @param uid Unique ID of the world to retrieve. - * @return World with the given Unique ID, or null if none exists. + * @param uid a unique-id of the world to retrieve + * @return a world with the given Unique ID, or null if none exists */ public World getWorld(UUID uid); /** * Gets the map from the given item ID. * - * @param id ID of the map to get. - * @return The MapView if it exists, or null otherwise. + * @param id the id of the map to get + * @return a map view if it exists, or null otherwise * @deprecated Magic value */ @Deprecated @@ -378,61 +380,62 @@ public interface Server extends PluginMessageRecipient { /** * Create a new map with an automatically assigned ID. * - * @param world The world the map will belong to. - * @return The MapView just created. + * @param world the world the map will belong to + * @return a newly created map view */ public MapView createMap(World world); /** - * Reloads the server, refreshing settings and plugin information + * Reloads the server, refreshing settings and plugin information. */ public void reload(); /** - * Returns the primary logger associated with this server instance + * Returns the primary logger associated with this server instance. * * @return Logger associated with this server */ public Logger getLogger(); /** - * Gets a {@link PluginCommand} with the given name or alias + * Gets a {@link PluginCommand} with the given name or alias. * - * @param name Name of the command to retrieve - * @return PluginCommand if found, otherwise null + * @param name the name of the command to retrieve + * @return a plugin command if found, null otherwise */ public PluginCommand getPluginCommand(String name); /** - * Writes loaded players to disk + * Writes loaded players to disk. */ public void savePlayers(); /** - * Dispatches a command on the server, and executes it if found. + * Dispatches a command on this server, and executes it if found. * - * @param sender The apparent sender of the command - * @param commandLine command + arguments. Example: "test abc 123" - * @return returns false if no target is found. - * @throws CommandException Thrown when the executor for the given command + * @param sender the apparent sender of the command + * @param commandLine the command + arguments. Example: <code>test abc + * 123</code> + * @return returns false if no target is found + * @throws CommandException thrown when the executor for the given command * fails with an unhandled exception */ public boolean dispatchCommand(CommandSender sender, String commandLine) throws CommandException; /** * Populates a given {@link ServerConfig} with values attributes to this - * server + * server. * - * @param config ServerConfig to populate + * @param config the server config to populate */ public void configureDbConfig(ServerConfig config); /** * Adds a recipe to the crafting manager. * - * @param recipe The recipe to add. - * @return True if the recipe was added, false if it wasn't for some - * reason. + * @param recipe the recipe to add + * @return true if the recipe was added, false if it wasn't for some + * reason */ public boolean addRecipe(Recipe recipe); @@ -440,15 +443,15 @@ public interface Server extends PluginMessageRecipient { * Get a list of all recipes for a given item. The stack size is ignored * in comparisons. If the durability is -1, it will match any data value. * - * @param result The item whose recipes you want - * @return The list of recipes + * @param result the item to match against recipe results + * @return a list of recipes with the given result */ public List<Recipe> getRecipesFor(ItemStack result); /** * Get an iterator through the list of crafting recipes. * - * @return The iterator. + * @return an iterator */ public Iterator<Recipe> recipeIterator(); @@ -465,42 +468,42 @@ public interface Server extends PluginMessageRecipient { /** * Gets a list of command aliases defined in the server properties. * - * @return Map of aliases to command names + * @return a map of aliases to command names */ public Map<String, String[]> getCommandAliases(); /** - * Gets the radius, in blocks, around each worlds spawn point to protect + * Gets the radius, in blocks, around each worlds spawn point to protect. * - * @return Spawn radius, or 0 if none + * @return spawn radius, or 0 if none */ public int getSpawnRadius(); /** - * Sets the radius, in blocks, around each worlds spawn point to protect + * Sets the radius, in blocks, around each worlds spawn point to protect. * - * @param value New spawn radius, or 0 if none + * @param value new spawn radius, or 0 if none */ public void setSpawnRadius(int value); /** * Gets whether the Server is in online mode or not. * - * @return Whether the server is in online mode. + * @return true if the server authenticates clients, false otherwise */ public boolean getOnlineMode(); /** * Gets whether this server allows flying or not. * - * @return Whether this server allows flying or not. + * @return true if the server allows flight, false otherwise */ public boolean getAllowFlight(); /** * Gets whether the server is in hardcore mode or not. * - * @return Whether this server is in hardcore mode or not. + * @return true if the server mode is hardcore, false otherwise */ public boolean isHardcore(); @@ -513,7 +516,8 @@ public interface Server extends PluginMessageRecipient { * <li>Exact behaviour: spawn players exactly where they should be. * </ul> * - * @return Whether to use vanilla (false) or exact behaviour (true). + * @return true if exact location locations are used for spawning, false + * for vanilla collision detection or otherwise */ public boolean useExactLoginLocation(); @@ -524,11 +528,12 @@ public interface Server extends PluginMessageRecipient { /** * Broadcasts the specified message to every user with the given - * permission + * permission name. * - * @param message Message to broadcast - * @param permission Permission the users must have to receive the broadcast - * @return Amount of users who received the message + * @param message message to broadcast + * @param permission the required permission {@link Permissible + * permissibles} must have to receive the broadcast + * @return number of message recipients */ public int broadcast(String message, String permission); @@ -539,101 +544,101 @@ public interface Server extends PluginMessageRecipient { * This will return an object even if the player does not exist. To this * method, all players will exist. * - * @param name Name of the player to retrieve - * @return OfflinePlayer object + * @param name the name the player to retrieve + * @return an offline player */ public OfflinePlayer getOfflinePlayer(String name); /** - * Gets a set containing all current IPs that are banned + * Gets a set containing all current IPs that are banned. * - * @return Set containing banned IP addresses + * @return a set containing banned IP addresses */ public Set<String> getIPBans(); /** - * Bans the specified address from the server + * Bans the specified address from the server. * - * @param address IP address to ban + * @param address the IP address to ban */ public void banIP(String address); /** - * Unbans the specified address from the server + * Unbans the specified address from the server. * - * @param address IP address to unban + * @param address the IP address to unban */ public void unbanIP(String address); /** - * Gets a set containing all banned players + * Gets a set containing all banned players. * - * @return Set containing banned players + * @return a set containing banned players */ public Set<OfflinePlayer> getBannedPlayers(); /** - * Gets a BanList for the supplied BanList Type + * Gets a ban list for the supplied type. * - * @param type The BanList Type to fetch, cannot be null - * @return the BanList of the specified type + * @param type the type of list to fetch, cannot be null + * @return a ban list of the specified type */ public BanList getBanList(BanList.Type type); /** - * Gets a set containing all player operators + * Gets a set containing all player operators. * - * @return Set containing player operators + * @return a set containing player operators */ public Set<OfflinePlayer> getOperators(); /** - * Gets the default {@link GameMode} for new players + * Gets the default {@link GameMode} for new players. * - * @return Default game mode + * @return the default game mode */ public GameMode getDefaultGameMode(); /** - * Sets the default {@link GameMode} for new players + * Sets the default {@link GameMode} for new players. * - * @param mode New game mode + * @param mode the new game mode */ public void setDefaultGameMode(GameMode mode); /** - * Gets the {@link ConsoleCommandSender} that may be used as an input - * source for this server. + * Gets a {@link ConsoleCommandSender} that may be used as an input source + * for this server. * - * @return The Console CommandSender + * @return a console command sender */ public ConsoleCommandSender getConsoleSender(); /** * Gets the folder that contains all of the various {@link World}s. * - * @return World container folder + * @return folder that contains all worlds */ public File getWorldContainer(); /** * Gets every player that has ever played on this server. * - * @return Array containing all players + * @return an array containing all previous players */ public OfflinePlayer[] getOfflinePlayers(); /** * Gets the {@link Messenger} responsible for this server. * - * @return Messenger responsible for this server. + * @return messenger responsible for this server */ public Messenger getMessenger(); /** * Gets the {@link HelpMap} providing help topics for this server. * - * @return The server's HelpMap. + * @return a help map for this server */ public HelpMap getHelpMap(); @@ -642,10 +647,9 @@ public interface Server extends PluginMessageRecipient { * InventoryType#CHEST}, the new inventory has a size of 27; otherwise the * new inventory has the normal size for its type. * - * @param owner The holder of the inventory; can be null if there's no - * holder. - * @param type The type of inventory to create. - * @return The new inventory. + * @param owner the holder of the inventory, or null to indicate no holder + * @param type the type of inventory to create + * @return a new inventory */ Inventory createInventory(InventoryHolder owner, InventoryType type); @@ -653,84 +657,90 @@ public interface Server extends PluginMessageRecipient { * Creates an empty inventory of type {@link InventoryType#CHEST} with the * specified size. * - * @param owner The holder of the inventory; can be null if there's no - * holder. - * @param size The size of inventory to create; must be a multiple of 9. - * @return The new inventory. - * @throws IllegalArgumentException If the size is not a multiple of 9. + * @param owner the holder of the inventory, or null to indicate no holder + * @param size a multiple of 9 as the size of inventory to create + * @return a new inventory + * @throws IllegalArgumentException if the size is not a multiple of 9 */ - Inventory createInventory(InventoryHolder owner, int size); + Inventory createInventory(InventoryHolder owner, int size) throws IllegalArgumentException; /** * Creates an empty inventory of type {@link InventoryType#CHEST} with the * specified size and title. * - * @param owner The holder of the inventory; can be null if there's no - * holder. - * @param size The size of inventory to create; must be a multiple of 9. - * @param title The title of the inventory, to be displayed when it is - * viewed. - * @return The new inventory. - * @throws IllegalArgumentException If the size is not a multiple of 9. + * @param owner the holder of the inventory, or null to indicate no holder + * @param size a multiple of 9 as the size of inventory to create + * @param title the title of the inventory, displayed when inventory is + * viewed + * @return a new inventory + * @throws IllegalArgumentException if the size is not a multiple of 9 */ - Inventory createInventory(InventoryHolder owner, int size, String title); + Inventory createInventory(InventoryHolder owner, int size, String title) throws IllegalArgumentException; /** * Gets user-specified limit for number of monsters that can spawn in a - * chunk + * chunk. * - * @return The monster spawn limit + * @return the monster spawn limit */ int getMonsterSpawnLimit(); /** * Gets user-specified limit for number of animals that can spawn in a - * chunk + * chunk. * - * @return The animal spawn limit + * @return the animal spawn limit */ int getAnimalSpawnLimit(); /** * Gets user-specified limit for number of water animals that can spawn in - * a chunk + * a chunk. * - * @return The water animal spawn limit + * @return the water animal spawn limit */ int getWaterAnimalSpawnLimit(); /** * Gets user-specified limit for number of ambient mobs that can spawn in - * a chunk + * a chunk. * - * @return The ambient spawn limit + * @return the ambient spawn limit */ int getAmbientSpawnLimit(); /** - * Returns true if the current {@link Thread} is the server's primary - * thread + * Checks the current thread against the expected primary thread for the + * server. + * <p> + * <b>Note:</b> this method should not be used to indicate the current + * synchronized state of the runtime. A current thread matching the main + * thread indicates that it is synchronized, but a mismatch <b>does not + * preclude</b> the same assumption. + * + * @return true if the current thread matches the expected primary thread, + * false otherwise */ boolean isPrimaryThread(); /** - * Gets the message that is displayed on the server list + * Gets the message that is displayed on the server list. * * @return the servers MOTD */ String getMotd(); /** - * Gets the default message that is displayed when the server is stopped + * Gets the default message that is displayed when the server is stopped. * * @return the shutdown message */ String getShutdownMessage(); /** - * Gets the current warning state for the server + * Gets the current warning state for the server. * - * @return The configured WarningState + * @return the configured warning state */ public WarningState getWarningState(); diff --git a/src/main/java/org/bukkit/World.java b/src/main/java/org/bukkit/World.java index f02bfb74..4580d732 100644 --- a/src/main/java/org/bukkit/World.java +++ b/src/main/java/org/bukkit/World.java @@ -484,7 +484,7 @@ public interface World extends PluginMessageRecipient, Metadatable { * <p> * Note that setting the relative time below the current relative time * will actually move the clock forward a day. If you require to rewind - * time, please see {@link #setFullTime()} + * time, please see {@link #setFullTime(long)} * * @param time The new relative time to set the in-game time to (in * hours*1000) diff --git a/src/main/java/org/bukkit/entity/Projectile.java b/src/main/java/org/bukkit/entity/Projectile.java index 02c840c3..90ce3b3f 100644 --- a/src/main/java/org/bukkit/entity/Projectile.java +++ b/src/main/java/org/bukkit/entity/Projectile.java @@ -33,7 +33,7 @@ public interface Projectile extends Entity { /** * Set the shooter of this projectile. * - * @param shooter the {@link ProjectileSource} that shot this projectile + * @param source the {@link ProjectileSource} that shot this projectile */ public void setShooter(ProjectileSource source); diff --git a/src/main/java/org/bukkit/event/EventPriority.java b/src/main/java/org/bukkit/event/EventPriority.java index ad381a79..61ffa50f 100644 --- a/src/main/java/org/bukkit/event/EventPriority.java +++ b/src/main/java/org/bukkit/event/EventPriority.java @@ -15,7 +15,8 @@ public enum EventPriority { */ LOW(1), /** - * Event call is neither important or unimportant, and may be ran normally + * Event call is neither important nor unimportant, and may be ran + * normally */ NORMAL(2), /** diff --git a/src/main/java/org/bukkit/event/player/AsyncPlayerChatEvent.java b/src/main/java/org/bukkit/event/player/AsyncPlayerChatEvent.java index e728d44b..a7962920 100644 --- a/src/main/java/org/bukkit/event/player/AsyncPlayerChatEvent.java +++ b/src/main/java/org/bukkit/event/player/AsyncPlayerChatEvent.java @@ -13,10 +13,10 @@ import org.bukkit.event.HandlerList; * <p> * The constructor provides a boolean to indicate if the event was fired * synchronously or asynchronously. When asynchronous, this event can be - * called from any thread, but the main thread, and has limited access to the + * called from any thread, sans the main thread, and has limited access to the * API. * <p> - * If a player is the direct cause of this event by incoming packet, this + * If a player is the direct cause of this event by an incoming packet, this * event will be asynchronous. If a plugin triggers this event by compelling a * player to chat, this event will be synchronous. * <p> diff --git a/src/main/java/org/bukkit/event/player/PlayerStatisticIncrementEvent.java b/src/main/java/org/bukkit/event/player/PlayerStatisticIncrementEvent.java index 124a1bd3..3b64d702 100644 --- a/src/main/java/org/bukkit/event/player/PlayerStatisticIncrementEvent.java +++ b/src/main/java/org/bukkit/event/player/PlayerStatisticIncrementEvent.java @@ -10,8 +10,8 @@ import org.bukkit.event.HandlerList; /** * Called when a player statistic is incremented. * <p> - * This event is not called for {@link org.bukkit.Statistic#PLAY_ONE_MINUTE} - * or movement based statistics. + * This event is not called for {@link org.bukkit.Statistic#PLAY_ONE_TICK} or + * movement based statistics. * */ public class PlayerStatisticIncrementEvent extends PlayerEvent implements Cancellable { @@ -52,7 +52,7 @@ public class PlayerStatisticIncrementEvent extends PlayerEvent implements Cancel /** * Gets the statistic that is being incremented. - * + * * @return the incremented statistic */ public Statistic getStatistic() { @@ -61,7 +61,7 @@ public class PlayerStatisticIncrementEvent extends PlayerEvent implements Cancel /** * Gets the previous value of the statistic. - * + * * @return the previous value of the statistic */ public int getPreviousValue() { @@ -70,7 +70,7 @@ public class PlayerStatisticIncrementEvent extends PlayerEvent implements Cancel /** * Gets the new value of the statistic. - * + * * @return the new value of the statistic */ public int getNewValue() { @@ -80,7 +80,7 @@ public class PlayerStatisticIncrementEvent extends PlayerEvent implements Cancel /** * Gets the EntityType if {@link #getStatistic() getStatistic()} is an * entity statistic otherwise returns null. - * + * * @return the EntityType of the statistic */ public EntityType getEntityType() { @@ -90,7 +90,7 @@ public class PlayerStatisticIncrementEvent extends PlayerEvent implements Cancel /** * Gets the Material if {@link #getStatistic() getStatistic()} is a block * or item statistic otherwise returns null. - * + * * @return the Material of the statistic */ public Material getMaterial() { diff --git a/src/main/java/org/bukkit/scoreboard/Team.java b/src/main/java/org/bukkit/scoreboard/Team.java index b3269618..50c6f762 100644 --- a/src/main/java/org/bukkit/scoreboard/Team.java +++ b/src/main/java/org/bukkit/scoreboard/Team.java @@ -39,7 +39,7 @@ public interface Team { void setDisplayName(String displayName) throws IllegalStateException, IllegalArgumentException; /** - * Sets the prefix prepended to the display of players on this team. + * Gets the prefix prepended to the display of players on this team. * * @return Team prefix * @throws IllegalStateException if this team has been unregistered @@ -102,8 +102,8 @@ public interface Team { boolean canSeeFriendlyInvisibles() throws IllegalStateException; /** - * Sets the team's ability to see invisible {@link - * PotionEffectType#INVISIBILITY invisible} teammates. + * Sets the team's ability to see {@link PotionEffectType#INVISIBILITY + * invisible} teammates. * * @param enabled true if invisible teammates are to be visible * @throws IllegalStateException if this team has been unregistered |