Updates the comments for BlockLocation

src/main/java/net/knarcraft/stargate/container/BlockLocation.java

@@ -7,8 +7,8 @@ import org.bukkit.World;
 import org.bukkit.block.Block;
 import org.bukkit.block.BlockFace;
 import org.bukkit.block.data.BlockData;
+import org.bukkit.block.data.Directional;
 import org.bukkit.block.data.type.Sign;
-import org.bukkit.block.data.type.WallSign;
 import org.bukkit.util.Vector;
 
 /**
@@ -16,7 +16,7 @@ import org.bukkit.util.Vector;
  *
  * <p>The BlockLocation class is basically a Location with some extra functionality.
  * Warning: Because of differences in the equals methods between Location and BlockLocation, a BlockLocation which
- * equals another BlockLocation does not necessarily equal the name BlockLocation if treated as a Location.</p>
+ * equals another BlockLocation does not necessarily equal the same BlockLocation if treated as a Location.</p>
  */
 public class BlockLocation extends Location {
 
@@ -35,19 +35,19 @@ public class BlockLocation extends Location {
     }
 
     /**
-     * Copies a craftbukkit block
+     * Creates a block location from a block
      *
-     * @param block <p>The block to </p>
+     * @param block <p>The block to get the location of</p>
      */
     public BlockLocation(Block block) {
         super(block.getWorld(), block.getX(), block.getY(), block.getZ());
     }
 
     /**
-     * Gets a block from a string
+     * Gets a block location from a string
      *
      * @param world  <p>The world the block exists in</p>
-     * @param string <p>A comma separated list of z, y and z coordinates as integers</p>
+     * @param string <p>A comma separated list of x, y and z coordinates as integers</p>
      */
     public BlockLocation(World world, String string) {
         super(world, Integer.parseInt(string.split(",")[0]), Integer.parseInt(string.split(",")[1]),
@@ -55,11 +55,11 @@ public class BlockLocation extends Location {
     }
 
     /**
-     * Makes a new block in a relative position to this block
+     * Creates a new block location in a relative position to this block location
      *
-     * @param x <p>The x position relative to this block's position</p>
+     * @param x <p>The number of blocks to move in the x-direction</p>
-     * @param y <p>The y position relative to this block's position</p>
+     * @param y <p>The number of blocks to move in the y-direction</p>
-     * @param z <p>The z position relative to this block's position</p>
+     * @param z <p>The number of blocks to move in the z-direction</p>
      * @return <p>A new block location</p>
      */
     public BlockLocation makeRelativeBlockLocation(int x, int y, int z) {
@@ -67,12 +67,12 @@ public class BlockLocation extends Location {
     }
 
     /**
-     * Makes a location relative to the block location
+     * Creates a location in a relative position to this block location
      *
-     * @param x   <p>The x position relative to this block's position</p>
+     * @param x   <p>The number of blocks to move in the x-direction</p>
-     * @param y   <p>The y position relative to this block's position</p>
+     * @param y   <p>The number of blocks to move in the y-direction</p>
      * @param z   <p>The z position relative to this block's position</p>
-     * @param yaw <p>The yaw of the location</p>
+     * @param yaw <p>The number of blocks to move in the z-direction</p>
      * @return <p>A new location</p>
      */
     public Location makeRelativeLocation(double x, double y, double z, float yaw) {
@@ -86,7 +86,7 @@ public class BlockLocation extends Location {
      * Gets a location relative to this block location
      *
      * @param relativeVector <p>The relative block vector describing the relative location</p>
-     * @param yaw            <p>The yaw pointing in the distance direction</p>
+     * @param yaw            <p>The yaw pointing outwards from a portal (in the relative vector's distance direction)</p>
      * @return <p>A location relative to this location</p>
      */
     public BlockLocation getRelativeLocation(RelativeBlockVector relativeVector, double yaw) {
@@ -98,9 +98,12 @@ public class BlockLocation extends Location {
     /**
      * Makes a location relative to the current location according to given parameters
      *
-     * @param right     <p>The amount of blocks to go right when looking the opposite direction from the yaw</p>
+     * <p>The distance goes in the direction of the yaw. Right goes in the direction of (yaw - 90) degrees.
-     * @param depth     <p>The amount of blocks to go downwards when looking the opposite direction from the yaw</p>
+     * Depth goes downwards following the -y direction.</p>
-     * @param distance  <p>The amount of blocks to go outwards when looking the opposite direction from the yaw</p>
+     *
+     * @param right     <p>The amount of blocks to go right when looking towards a portal</p>
+     * @param depth     <p>The amount of blocks to go downwards when looking towards a portal</p>
+     * @param distance  <p>The amount of blocks to go outwards when looking towards a portal</p>
      * @param portalYaw <p>The yaw when looking out from the portal</p>
      * @return A new location relative to this block location
      */
@@ -111,18 +114,18 @@ public class BlockLocation extends Location {
     }
 
     /**
-     * Gets the type for the block at this location
+     * Gets the type of block at this block location
      *
-     * @return <p>The block material type</p>
+     * @return <p>The block's material type</p>
      */
     public Material getType() {
         return this.getBlock().getType();
     }
 
     /**
-     * Sets the type for the block at this location
+     * Sets the type of block at this location
      *
-     * @param type <p>The new block material type</p>
+     * @param type <p>The block's new material type</p>
      */
     public void setType(Material type) {
         this.getBlock().setType(type);
@@ -140,6 +143,9 @@ public class BlockLocation extends Location {
     /**
      * Gets this block location's parent block
      *
+     * <p>The parent block is the block the item at this block location is attached to. Usually this is the block a
+     * sign or wall sign is attached to.</p>
+     *
      * @return <p>This block location's parent block</p>
      */
     public Block getParent() {
@@ -163,11 +169,13 @@ public class BlockLocation extends Location {
         int offsetZ = 0;
 
         BlockData blockData = getBlock().getBlockData();
-        if (blockData instanceof WallSign) {
+        if (blockData instanceof Directional) {
-            BlockFace facing = ((WallSign) blockData).getFacing().getOppositeFace();
+            //Get the offset of the block "behind" this block
+            BlockFace facing = ((Directional) blockData).getFacing().getOppositeFace();
             offsetX = facing.getModX();
             offsetZ = facing.getModZ();
         } else if (blockData instanceof Sign) {
+            //Get offset the block beneath the sign
             offsetY = -1;
         } else {
             return;
@@ -195,21 +203,23 @@ public class BlockLocation extends Location {
     }
 
     @Override
-    public boolean equals(Object obj) {
+    public boolean equals(Object object) {
-        if (this == obj) {
+        if (this == object) {
             return true;
         }
-        if (obj == null || getClass() != obj.getClass()) {
+        if (object == null || getClass() != object.getClass()) {
             return false;
         }
 
-        BlockLocation blockLocation = (BlockLocation) obj;
+        BlockLocation blockLocation = (BlockLocation) object;
 
         World thisWorld = this.getWorld();
         World otherWorld = blockLocation.getWorld();
+        //Check if the worlds of the two locations match
         boolean worldsEqual = (thisWorld == null && otherWorld == null) || ((thisWorld != null && otherWorld != null)
                 && thisWorld == otherWorld);
 
+        //As this is a block location, only the block coordinates are compared
         return blockLocation.getBlockX() == this.getBlockX() && blockLocation.getBlockY() == this.getBlockY() &&
                 blockLocation.getBlockZ() == this.getBlockZ() && worldsEqual;
     }