Merge pull request #211 from kingbirdy/wip/javadocs

Add or update javadocs for several classes

src/com/projectkorra/projectkorra/ability/api/CoreAbility.java

@@ -11,7 +11,7 @@ import java.util.UUID;
 import java.util.concurrent.ConcurrentHashMap;
 
 /**
- * Represents an the core of all ProjectKorra abilities and implements the
+ * Represents the core of all ProjectKorra abilities and implements the
  * {@link Ability} interface.
  * 
  * @author jacklin213

src/com/projectkorra/projectkorra/event/BendingReloadEvent.java

@@ -2,6 +2,12 @@ package com.projectkorra.projectkorra.event;
 
 import org.bukkit.event.Event;
 import org.bukkit.event.HandlerList;
+/**
+ * Called when the /bending reload command is executed.
+ * 
+ * @author kingbirdy
+ * @version 1.0
+ */
 
 public class BendingReloadEvent extends Event {
 

src/com/projectkorra/projectkorra/event/PlayerBendingDeathEvent.java

@@ -1,9 +1,17 @@
 package com.projectkorra.projectkorra.event;
 
+import com.projectkorra.projectkorra.GeneralMethods;
+
 import org.bukkit.entity.Player;
 import org.bukkit.event.Event;
 import org.bukkit.event.HandlerList;
 
+/**
+ * Called when a player is killed by {@link GeneralMethods#damageEntity(Player player, Entity entity, double damage, String ability) GeneralMethods.damageEntity}
+ * 
+ * @author kingbirdy
+ */
+
 public class PlayerBendingDeathEvent extends Event {
 
 	public static final HandlerList handlers = new HandlerList();
@@ -12,6 +20,13 @@ public class PlayerBendingDeathEvent extends Event {
 	private String ability;
 	private double damage;
 
+	/**
+	 * 
+	 * @param victim the player who died
+	 * @param attacker the player who killed the victim
+	 * @param ability the ability used to kill the victim
+	 * @param damage the amount of damage done in the attack that killed the victim
+	 */
 	public PlayerBendingDeathEvent(Player victim, Player attacker, String ability, double damage) {
 		this.victim = victim;
 		this.attacker = attacker;
@@ -19,18 +34,34 @@ public class PlayerBendingDeathEvent extends Event {
 		this.damage = damage;
 	}
 
+	/**
+	 * 
+	 * @return the player who was killed
+	 */
 	public Player getVictim() {
 		return victim;
 	}
 
+	/**
+	 * 
+	 * @return the player who killed the victim
+	 */
 	public Player getAttacker() {
 		return attacker;
 	}
 
+	/**
+	 * 
+	 * @return the ability used to kill the victim
+	 */
 	public String getAbility() {
 		return ability;
 	}
 
+	/**
+	 * 
+	 * @return the amount of damage done in the attack that killed the victim
+	 */
 	public double getDamage() {
 		return damage;
 	}

src/com/projectkorra/projectkorra/event/PlayerChangeElementEvent.java

@@ -7,6 +7,12 @@ import org.bukkit.entity.Player;
 import org.bukkit.event.Event;
 import org.bukkit.event.HandlerList;
 
+/**
+ * Called when a player's bending element is modified
+ * 
+ * @author kingbirdy
+ *
+ */
 public class PlayerChangeElementEvent extends Event {
 
 	private static final HandlerList handlers = new HandlerList();
@@ -15,6 +21,13 @@ public class PlayerChangeElementEvent extends Event {
 	private Element element;
 	private Result result;
 
+	/**
+	 * 
+	 * @param sender the {@link CommandSender} who changed the player's bending
+	 * @param target the {@link Player player} who's bending was changed
+	 * @param element the {@link Element element} that was affected
+	 * @param result whether the element was chosen, added, removed, or permaremoved
+	 */
 	public PlayerChangeElementEvent(CommandSender sender, Player target, Element element, Result result) {
 		this.sender = sender;
 		this.target = target;
@@ -30,18 +43,34 @@ public class PlayerChangeElementEvent extends Event {
 		return handlers;
 	}
 
+	/**
+	 * 
+	 * @return the {@link CommandSender} who changed the player's bending
+	 */
 	public CommandSender getSender() {
 		return sender;
 	}
 
+	/**
+	 * 
+	 * @return the {@link Player player} who's bending was changed
+	 */
 	public Player getTarget() {
 		return target;
 	}
 
+	/**
+	 * 
+	 * @return the {@link Element element} that was affected
+	 */
 	public Element getElement() {
 		return element;
 	}
 
+	/**
+	 * 
+	 * @return whether the element was chosen, added, removed, or permaremoved
+	 */
 	public Result getResult() {
 		return result;
 	}

src/com/projectkorra/projectkorra/object/Preset.java

@@ -16,14 +16,29 @@ import java.util.List;
 import java.util.UUID;
 import java.util.concurrent.ConcurrentHashMap;
 
+/**
+ * A savable association of abilities and hotbar slots, stored per player.
+ * @author kingbirdy
+ *
+ */
 public class Preset {
 
+	/**
+	 * ConcurrentHashMap that stores a list of every Player's {@link Preset presets}, keyed to their UUID
+	 */
 	public static ConcurrentHashMap<UUID, List<Preset>> presets = new ConcurrentHashMap<UUID, List<Preset>>();
 
 	UUID uuid;
 	HashMap<Integer, String> abilities;
 	String name;
 
+	/**
+	 * Creates a new {@link Preset}
+	 * 
+	 * @param uuid The UUID of the Player who the Preset belongs to
+	 * @param name The name of the Preset
+	 * @param abilities A HashMap of the abilities to be saved in the Preset, keyed to the slot they're bound to
+	 */
 	public Preset(UUID uuid, String name, HashMap<Integer, String> abilities) {
 		this.uuid = uuid;
 		this.name = name;
@@ -34,11 +49,21 @@ public class Preset {
 		presets.get(uuid).add(this);
 	}
 
+	/**
+	 * Unload a Player's Presets from those stored in memory.
+	 * 
+	 * @param player The Player who's Presets should be unloaded
+	 */
 	public static void unloadPreset(Player player) {
 		UUID uuid = player.getUniqueId();
 		presets.remove(uuid);
 	}
 
+	/**
+	 * Load a Player's Presets into memory.
+	 * 
+	 * @param player The Player who's Presets should be loaded
+	 */
 	public static void loadPresets(final Player player) {
 		new BukkitRunnable() {
 			@Override
@@ -71,6 +96,12 @@ public class Preset {
 		}.runTaskAsynchronously(ProjectKorra.plugin);
 	}
 
+	/**
+	 * Binds the abilities from a Preset for the given Player.
+	 * 
+	 * @param player The Player the Preset should be bound for
+	 * @param name The name of the Preset that should be bound
+	 */
 	@SuppressWarnings("unchecked")
 	public static void bindPreset(Player player, String name) {
 		BendingPlayer bPlayer = GeneralMethods.getBendingPlayer(player.getName());
@@ -85,6 +116,12 @@ public class Preset {
 		}
 	}
 
+	/**
+	 * Checks if a Preset with a certain name exists for a given Player.
+	 * @param player The player who's Presets should be checked
+	 * @param name The name of the Preset to look for
+	 * @return true if the Preset exists, false otherwise
+	 */
 	public static boolean presetExists(Player player, String name) {
 		if (!presets.containsKey(player.getUniqueId()))
 			return false;
@@ -96,6 +133,12 @@ public class Preset {
 		return exists;
 	}
 
+	/**
+	 * Gets a Preset for the specified Player.
+	 * @param Player The Player who's Preset should be gotten
+	 * @param name The name of the Preset to get
+	 * @return The Preset, if it exists, or null otherwise
+	 */
 	public static Preset getPreset(Player player, String name) {
 		if (!presets.containsKey(player.getUniqueId()))
 			return null;
@@ -106,6 +149,12 @@ public class Preset {
 		return null;
 	}
 
+	/**
+	 * Gets the contents of a Preset for the specified Player.
+	 * @param player The Player who's Preset should be gotten
+	 * @param name The name of the Preset who's contents should be gotten
+	 * @return HashMap of ability names keyed to hotbar slots, if the Preset exists, or null otherwise
+	 */
 	public static HashMap<Integer, String> getPresetContents(Player player, String name) {
 		if (!presets.containsKey(player.getUniqueId()))
 			return null;
@@ -117,15 +166,25 @@ public class Preset {
 		return null;
 	}
 
+	/**
+	 * Deletes the Preset from the database.
+	 */
 	public void delete() {
 		DBConnection.sql.modifyQuery("DELETE FROM pk_presets WHERE uuid = '" + uuid.toString() + "' AND name = '" + name + "'");
 		presets.get(uuid).remove(this);
 	}
 
+	/**
+	 * Gets the name of the preset.
+	 * @return The name of the preset
+	 */
 	public String getName() {
 		return this.name;
 	}
 
+	/**
+	 * Saves the Preset to the database.
+	 */
 	public void save() {
 		if (ProjectKorra.plugin.getConfig().getString("Storage.engine").equalsIgnoreCase("mysql")) {
 			DBConnection.sql.modifyQuery("INSERT INTO pk_presets (uuid, name) VALUES ('" + uuid.toString() + "', '" + name + "') " + "ON DUPLICATE KEY UPDATE name=VALUES(name)");

src/com/projectkorra/projectkorra/util/AbilityLoadEvent.java

@@ -6,6 +6,11 @@ import org.bukkit.plugin.Plugin;
 
 import java.util.jar.JarFile;
 
+/**
+ * Called when an ability is successfully loaded.
+ * 
+ * @author kingbirdy
+ */
 public class AbilityLoadEvent<T> extends Event {
 
 	private static final HandlerList handlers = new HandlerList();
@@ -14,6 +19,12 @@ public class AbilityLoadEvent<T> extends Event {
 	private final T loadable;
 	private final JarFile jarFile;
 
+	/**
+	 * Creates a new AbilityLoadEvent.
+	 * @param plugin The instance of ProjectKorra
+	 * @param loadable The class that was loaded
+	 * @param jarFile The JarFile the class was loaded from
+	 */
 	public AbilityLoadEvent(Plugin plugin, T loadable, JarFile jarFile) {
 		this.plugin = plugin;
 		this.loadable = loadable;
@@ -29,14 +40,26 @@ public class AbilityLoadEvent<T> extends Event {
 		return handlers;
 	}
 
+	/**
+	 * Gets the JarFile the ability was loaded from.
+	 * @return The JarFile from the event
+	 */
 	public JarFile getJarFile() {
 		return jarFile;
 	}
 
+	/**
+	 * Gets the ability's class that was loaded
+	 * @return The loaded class
+	 */
 	public T getLoadable() {
 		return loadable;
 	}
 
+	/**
+	 * Gets the ProjectKorra instance the ability was loaded into.
+	 * @return The ProjectKorra instance
+	 */
 	public Plugin getPlugin() {
 		return plugin;
 	}

src/com/projectkorra/projectkorra/util/BlockSource.java

@@ -22,6 +22,11 @@ import java.util.HashMap;
  * shift and another involving left clicks.
  */
 public class BlockSource {
+	/**
+	 * An enum representation of the source types available for bending abilities.
+	 * @author kingbirdy
+	 *
+	 */
 	public static enum BlockSourceType {
 		WATER, ICE, PLANT, EARTH, METAL, LAVA
 	}
@@ -35,7 +40,7 @@ public class BlockSource {
 	 * Updates all of the player's sources.
 	 * 
 	 * @param player the player performing the bending.
-	 * @param clickType either ClickType.SHIFT_DOWN or ClickType.LEFT_CLICK
+	 * @param clickType either {@link ClickType}.SHIFT_DOWN or ClickType.LEFT_CLICK
 	 */
 	public static void update(Player player, ClickType clickType) {
 		String boundAbil = GeneralMethods.getBoundAbility(player);
@@ -94,7 +99,7 @@ public class BlockSource {
 	}
 
 	/**
-	 * Access a block source information depending on a source and click type.
+	 * Access a block's source information, depending on a {@link BlockSourceType} and {@link ClickType}.
 	 * 
 	 * @param player the player that is trying to bend.
 	 * @param clickType the action that was performed to access the source,
@@ -113,8 +118,7 @@ public class BlockSource {
 	}
 
 	/**
-	 * Access a block source information depending on a range, source, and click
-	 * type.
+	 * Access a block source information depending on a range, {@link BlockSourceType}, and {@link ClickType}.
 	 * 
 	 * @param player the player that is trying to bend.
 	 * @param range the maximum range to access the block.
@@ -129,8 +133,7 @@ public class BlockSource {
 	}
 
 	/**
-	 * Access a specific type of source block depending on a range and click
-	 * type.
+	 * Access a specific type of source block depending on a range and {@link ClickType}.
 	 * 
 	 * @param player the player that is trying to bend.
 	 * @param range the maximum range to access the block.
@@ -163,7 +166,7 @@ public class BlockSource {
 	 * @param player the player that is trying to bend.
 	 * @param range the maximum range to access the block.
 	 * @param clickType the action that was performed to access the source,
-	 *            either ClickType.SHIFT_DOWN or ClickType.LEFT_CLICK.
+	 *            either {@link ClickType}.SHIFT_DOWN or ClickType.LEFT_CLICK.
 	 * @return a valid Water bendable block, or null if none was found.
 	 */
 	public static Block getWaterSourceBlock(Player player, double range, ClickType clickType) {
@@ -192,7 +195,7 @@ public class BlockSource {
 	 * @param player the player that is trying to bend.
 	 * @param range the maximum range to access the block.
 	 * @param clickType the action that was performed to access the source,
-	 *            either ClickType.SHIFT_DOWN or ClickType.LEFT_CLICK.
+	 *            either {@link ClickType}.SHIFT_DOWN or ClickType.LEFT_CLICK.
 	 * @param allowWater true if water blocks are allowed.
 	 * @param allowIce true if ice blocks are allowed.
 	 * @param allowPlant true if plant blocks are allowed.
@@ -209,7 +212,7 @@ public class BlockSource {
 	 * @param player the player that is trying to bend.
 	 * @param range the maximum range to access the block.
 	 * @param clickType the action that was performed to access the source,
-	 *            either ClickType.SHIFT_DOWN or ClickType.LEFT_CLICK.
+	 *            either {@link ClickType}.SHIFT_DOWN or ClickType.LEFT_CLICK.
 	 * @param allowWater true if water blocks are allowed.
 	 * @param allowIce true if ice blocks are allowed.
 	 * @param allowPlant true if plant blocks are allowed.
@@ -246,7 +249,7 @@ public class BlockSource {
 	 * @param player the player that is trying to bend.
 	 * @param range the maximum range to access the block.
 	 * @param clickType the action that was performed to access the source,
-	 *            either ClickType.SHIFT_DOWN or ClickType.LEFT_CLICK.
+	 *            either {@link ClickType}.SHIFT_DOWN or ClickType.LEFT_CLICK.
 	 * @return a valid Earth bendable block, or null if none was found.
 	 */
 	public static Block getEarthSourceBlock(Player player, double range, ClickType clickType) {
@@ -260,7 +263,7 @@ public class BlockSource {
 	 * @param player the player that is trying to bend.
 	 * @param range the maximum range to access the block.
 	 * @param clickType the action that was performed to access the source,
-	 *            either ClickType.SHIFT_DOWN or ClickType.LEFT_CLICK.
+	 *            either {@link ClickType}.SHIFT_DOWN or ClickType.LEFT_CLICK.
 	 * @param allowNearbySubstitute if a valid earth source could not be found
 	 *            then this method will attempt to find a nearby valid earth
 	 *            block.
@@ -295,7 +298,7 @@ public class BlockSource {
 	 * @param player the player that is trying to bend.
 	 * @param range the maximum range to access the block.
 	 * @param clickType the action that was performed to access the source,
-	 *            either ClickType.SHIFT_DOWN or ClickType.LEFT_CLICK.
+	 *            either {@link ClickType}.SHIFT_DOWN or ClickType.LEFT_CLICK.
 	 * @return a valid Lava bendable block, or null if none was found.
 	 */
 	public static Block getLavaSourceBlock(Player player, double range, ClickType clickType) {
@@ -309,7 +312,7 @@ public class BlockSource {
 	 * @param player the player that is trying to bend.
 	 * @param range the maximum range to access the block.
 	 * @param clickType the action that was performed to access the source,
-	 *            either ClickType.SHIFT_DOWN or ClickType.LEFT_CLICK.
+	 *            either {@link ClickType}.SHIFT_DOWN or ClickType.LEFT_CLICK.
 	 * @return a valid Earth or Lava bendable block, or null if none was found.
 	 */
 	public static Block getEarthOrLavaSourceBlock(Player player, double range, ClickType clickType) {

src/com/projectkorra/projectkorra/util/BlockSourceInformation.java

@@ -5,6 +5,11 @@ import com.projectkorra.projectkorra.util.BlockSource.BlockSourceType;
 import org.bukkit.block.Block;
 import org.bukkit.entity.Player;
 
+/**
+ * The information for a bending source block.
+ * @author kingbirdy
+ *
+ */
 public class BlockSourceInformation {
 	private Player player;
 	private Block block;
@@ -12,6 +17,13 @@ public class BlockSourceInformation {
 	private ClickType clickType;
 	private long creationTime;
 
+	/**
+	 * Creates a new BlockSourceInformation.
+	 * @param player The player the source belongs to
+	 * @param block The source block
+	 * @param sourceType What {@link BlockSourceType source type} the block is
+	 * @param clickType
+	 */
 	public BlockSourceInformation(Player player, Block block, BlockSourceType sourceType, ClickType clickType) {
 		this.player = player;
 		this.block = block;
@@ -20,42 +32,82 @@ public class BlockSourceInformation {
 		this.clickType = clickType;
 	}
 
+	/**
+	 * Gets the source block.
+	 * @return The source block
+	 */
 	public Block getBlock() {
 		return block;
 	}
 
+	/**
+	 * Sets a new source block.
+	 * @param block The new source block.
+	 */
 	public void setBlock(Block block) {
 		this.block = block;
 	}
 
+	/**
+	 * Get what {@link BlockSourceType source type} the source is.
+	 * @return The block's source type
+	 */
 	public BlockSourceType getSourceType() {
 		return sourceType;
 	}
 
+	/**
+	 * Sets the source type.
+	 * @param sourceType The new source type.
+	 */
 	public void setSourceType(BlockSourceType sourceType) {
 		this.sourceType = sourceType;
 	}
 
+	/**
+	 * Gets when the source was created.
+	 * @return The source's creation time
+	 */
 	public long getCreationTime() {
 		return creationTime;
 	}
 
+	/**
+	 * Sets the source's creation time.
+	 * @param creationTime The new creation time
+	 */
 	public void setCreationTime(long creationTime) {
 		this.creationTime = creationTime;
 	}
 
+	/**
+	 * Get the player the source belongs to.
+	 * @return The player the source belongs to
+	 */
 	public Player getPlayer() {
 		return player;
 	}
 
+	/**
+	 * Sets the player the source belongs to.
+	 * @param player The player the source will belong to
+	 */
 	public void setPlayer(Player player) {
 		this.player = player;
 	}
 
+	/**
+	 * Gets the {@link ClickType} used to select the source.
+	 * @return The ClickType used to select the source
+	 */
 	public ClickType getClickType() {
 		return clickType;
 	}
 
+	/**
+	 * Sets the source's {@link ClickType}.
+	 * @param clickType The ClickType to set
+	 */
 	public void setClickType(ClickType clickType) {
 		this.clickType = clickType;
 	}

src/com/projectkorra/projectkorra/util/ClickType.java

@@ -1,5 +1,21 @@
 package com.projectkorra.projectkorra.util;
 
+/**
+ * An enum representation of the ways in which an ability can be activated.
+ * @author kingbirdy
+ *
+ */
 public enum ClickType {
-	SHIFT, SHIFT_DOWN, SHIFT_UP, CLICK, LEFT_CLICK, RIGHT_CLICK
+	SHIFT, 
+	/**
+	 * The shift key being released
+	 */
+	SHIFT_DOWN, 
+	/**
+	 * The shift key being pressed
+	 */
+	SHIFT_UP, 
+	CLICK, 
+	LEFT_CLICK, 
+	RIGHT_CLICK
 }

src/com/projectkorra/projectkorra/util/FileExtensionFilter.java

@@ -3,10 +3,20 @@ package com.projectkorra.projectkorra.util;
 import java.io.File;
 import java.io.FileFilter;
 
+/**
+ * Checks if a file ends with a certain extension.
+ * 
+ * @author kingbirdy
+ *
+ */
 public final class FileExtensionFilter implements FileFilter {
 
 	private final String extension;
 
+	/**
+	 * Creates a new FileExtensionFilter.
+	 * @param extension the extension to filter for
+	 */
 	public FileExtensionFilter(String extension) {
 		this.extension = extension;
 	}