From a1fa32153cb5410b6874bcb9b39a557eb68ce45b Mon Sep 17 00:00:00 2001
From: TomyLobo <tomylobo@nurfuerspam.de>
Date: Thu, 24 Oct 2013 20:36:44 +0200
Subject: [PATCH] Code quality improvements.

---
 .../java/com/sk89q/worldedit/LocalPlayer.java | 71 ++++++++-----------
 1 file changed, 30 insertions(+), 41 deletions(-)

diff --git a/src/main/java/com/sk89q/worldedit/LocalPlayer.java b/src/main/java/com/sk89q/worldedit/LocalPlayer.java
index 43db697f5..99a102f99 100644
--- a/src/main/java/com/sk89q/worldedit/LocalPlayer.java
+++ b/src/main/java/com/sk89q/worldedit/LocalPlayer.java
@@ -42,7 +42,7 @@ public abstract class LocalPlayer {
     /**
      * Construct the object.
      *
-     * @param server
+     * @param server A reference to the server this player is on
      */
     protected LocalPlayer(ServerInterface server) {
         this.server = server;
@@ -104,7 +104,7 @@ public abstract class LocalPlayer {
     /**
      * Set the player on the ground.
      *
-     * @param searchPos
+     * @param searchPos The location to start searching from
      */
     public void setOnGround(WorldVector searchPos) {
         LocalWorld world = searchPos.getWorld();
@@ -232,7 +232,7 @@ public abstract class LocalPlayer {
     /**
      * Ascend to the ceiling above.
      *
-     * @param clearance
+     * @param clearance How many blocks to leave above the player's head
      * @return whether the player was moved
      */
     public boolean ascendToCeiling(int clearance) {
@@ -321,8 +321,8 @@ public abstract class LocalPlayer {
      * Get the point of the block being looked at. May return null.
      * Will return the farthest away air block if useLastBlock is true and no other block is found.
      *
-     * @param range
-     * @param useLastBlock
+     * @param range How far to checks for blocks
+     * @param useLastBlock Try to return the last valid air block found.
      * @return point
      */
     public WorldVector getBlockTrace(int range, boolean useLastBlock) {
@@ -338,7 +338,7 @@ public abstract class LocalPlayer {
     /**
      * Get the point of the block being looked at. May return null.
      *
-     * @param range
+     * @param range How far to checks for blocks
      * @return point
      */
     public WorldVector getBlockTrace(int range) {
@@ -348,7 +348,7 @@ public abstract class LocalPlayer {
     /**
      * Get the point of the block being looked at. May return null.
      *
-     * @param range
+     * @param range How far to checks for blocks
      * @return point
      */
     public WorldVector getSolidBlockTrace(int range) {
@@ -359,7 +359,7 @@ public abstract class LocalPlayer {
     /**
      * Get the player's cardinal direction (N, W, NW, etc.). May return null.
      *
-     * @return
+     * @return the direction
      */
     public PlayerDirection getCardinalDirection() {
         return getCardinalDirection(0);
@@ -369,7 +369,7 @@ public abstract class LocalPlayer {
      * Get the player's cardinal direction (N, W, NW, etc.) with an offset. May return null.
      * @param yawOffset offset that is added to the player's yaw before determining the cardinal direction
      *
-     * @return
+     * @return the direction
      */
     public PlayerDirection getCardinalDirection(int yawOffset) {
         if (getPitch() > 67.5) {
@@ -390,8 +390,8 @@ public abstract class LocalPlayer {
     /**
      * Returns direction according to rotation. May return null.
      *
-     * @param rot
-     * @return
+     * @param rot yaw
+     * @return the direction
      */
     private static PlayerDirection getDirection(double rot) {
         if (0 <= rot && rot < 22.5) {
@@ -420,7 +420,7 @@ public abstract class LocalPlayer {
     /**
      * Get the ID of the item that the player is holding.
      *
-     * @return
+     * @return the item id of the item the player is holding
      */
     public abstract int getItemInHand();
 
@@ -472,15 +472,15 @@ public abstract class LocalPlayer {
     /**
      * Gives the player an item.
      *
-     * @param type
-     * @param amt
+     * @param type The item id of the item to be given to the player
+     * @param amount How many items in the stack
      */
-    public abstract void giveItem(int type, int amt);
+    public abstract void giveItem(int type, int amount);
 
     /**
      * Pass through the wall that you are looking at.
      *
-     * @param range
+     * @param range How far to checks for blocks
      * @return whether the player was pass through
      */
     public boolean passThroughForwardWall(int range) {
@@ -529,44 +529,44 @@ public abstract class LocalPlayer {
     /**
      * Print a message.
      *
-     * @param msg
+     * @param msg The message text
      */
     public abstract void printRaw(String msg);
 
     /**
      * Print a WorldEdit message.
      *
-     * @param msg
+     * @param msg The message text
      */
     public abstract void printDebug(String msg);
 
     /**
      * Print a WorldEdit message.
      *
-     * @param msg
+     * @param msg The message text
      */
     public abstract void print(String msg);
 
     /**
      * Print a WorldEdit error.
      *
-     * @param msg
+     * @param msg The error message text
      */
     public abstract void printError(String msg);
 
     /**
      * Move the player.
      *
-     * @param pos
-     * @param pitch
-     * @param yaw
+     * @param pos Where to move them
+     * @param pitch The pitch (up/down) of the player's view
+     * @param yaw The yaw (left/right) of the player's view
      */
     public abstract void setPosition(Vector pos, float pitch, float yaw);
 
     /**
      * Move the player.
      *
-     * @param pos
+     * @param pos Where to move them
      */
     public void setPosition(Vector pos) {
         setPosition(pos, (float) getPitch(), (float) getYaw());
@@ -575,22 +575,22 @@ public abstract class LocalPlayer {
     /**
      * Get a player's list of groups.
      *
-     * @return
+     * @return an array containing a group name per entry
      */
     public abstract String[] getGroups();
 
     /**
      * Get this player's block bag.
      *
-     * @return
+     * @return the player's block bag
      */
     public abstract BlockBag getInventoryBlockBag();
 
     /**
      * Checks if a player has permission.
      *
-     * @param perm
-     * @return
+     * @param perm The permission to check
+     * @return true if the player has that permission
      */
     public abstract boolean hasPermission(String perm);
 
@@ -598,7 +598,7 @@ public abstract class LocalPlayer {
      * Open a file open dialog.
      *
      * @param extensions null to allow all
-     * @return
+     * @return the selected file or null if something went wrong
      */
     public File openFileOpenDialog(String[] extensions) {
         printError("File dialogs are not supported in your environment.");
@@ -609,7 +609,7 @@ public abstract class LocalPlayer {
      * Open a file save dialog.
      *
      * @param extensions null to allow all
-     * @return
+     * @return the selected file or null if something went wrong
      */
     public File openFileSaveDialog(String[] extensions) {
         printError("File dialogs are not supported in your environment.");
@@ -641,12 +641,6 @@ public abstract class LocalPlayer {
     public void dispatchCUIHandshake() {
     }
 
-    /**
-     * Returns true if equal.
-     *
-     * @param other
-     * @return whether the other object is equivalent
-     */
     @Override
     public boolean equals(Object other) {
         if (!(other instanceof LocalPlayer)) {
@@ -656,11 +650,6 @@ public abstract class LocalPlayer {
         return other2.getName().equals(getName());
     }
 
-    /**
-     * Gets the hash code.
-     *
-     * @return hash code
-     */
     @Override
     public int hashCode() {
         return getName().hashCode();