API: cleanup, remove unused functions, improve documentation

api/buildcraft/api/core/IWorldProperty.java

@@ -11,7 +11,6 @@ package buildcraft.api.core;
 import net.minecraft.world.World;
 
 public interface IWorldProperty {
-
 	boolean get(World world, int x, int y, int z);
 
 	void clear();

api/buildcraft/api/core/JavaTools.java

@@ -17,10 +17,6 @@ import java.util.Collections;
 import java.util.List;
 
 public class JavaTools {
-	public static double bounds(double value, double min, double max) {
-		return Math.max(min, Math.min(value, max));
-	}
-
 	public static <T> T[] concat(T[] first, T[] second) {
 		T[] result = Arrays.copyOf(first, first.length + second.length);
 		System.arraycopy(second, 0, result, first.length, second.length);
@@ -39,46 +35,6 @@ public class JavaTools {
 		return result;
 	}
 
-	public <T> T[] concatenate (T[] a, T[] b) {
-	    int aLen = a.length;
-	    int bLen = b.length;
-
-	    @SuppressWarnings("unchecked")
-		T[] c = (T[]) Array.newInstance(a.getClass().getComponentType(), aLen + bLen);
-	    System.arraycopy(a, 0, c, 0, aLen);
-	    System.arraycopy(b, 0, c, aLen, bLen);
-
-	    return c;
-	}
-
-	public static List<Field> getAllFields(Class<?> clas) {
-	    List<Field> result = new ArrayList<Field>();
-
-	    Class<?> current = clas;
-
-	    while (current != null && current != Object.class) {
-			Collections.addAll(result, current.getDeclaredFields());
-
-	        current = current.getSuperclass();
-	    }
-
-	    return result;
-	}
-
-	public static List<Method> getAllMethods(Class<?> clas) {
-	    List<Method> result = new ArrayList<Method>();
-
-	    Class<?> current = clas;
-
-	    while (current != null && current != Object.class) {
-			Collections.addAll(result, current.getDeclaredMethods());
-
-	        current = current.getSuperclass();
-	    }
-
-	    return result;
-	}
-
 	public static String surroundWithQuotes(String stringToSurroundWithQuotes) {
 		return String.format("\"%s\"", stringToSurroundWithQuotes);
 	}

api/buildcraft/api/core/SafeTimeTracker.java

@@ -82,4 +82,4 @@ public class SafeTimeTracker {
 	public void markTime(World world) {
 		lastMark = world.getTotalWorldTime();
 	}
-}
+}

api/buildcraft/api/core/WorldBlockIndex.java

@@ -1,108 +0,0 @@
-/**
- * Copyright (c) 2011-2014, SpaceToad and the BuildCraft Team
- * http://www.mod-buildcraft.com
- *
- * BuildCraft is distributed under the terms of the Minecraft Mod Public
- * License 1.0, or MMPL. Please check the contents of the license located in
- * http://www.mod-buildcraft.com/MMPL-1.0.txt
- */
-package buildcraft.api.core;
-
-import net.minecraft.entity.Entity;
-import net.minecraft.nbt.NBTTagCompound;
-import net.minecraft.world.World;
-
-/**
- * This class is a comparable container for block positions. TODO: should this be merged with position?
- */
-public class WorldBlockIndex implements Comparable<WorldBlockIndex> {
-
-	public int x;
-	public int y;
-	public int z;
-	public int dimension;
-
-	public WorldBlockIndex() {
-
-	}
-
-	/**
-	 * Creates an index for a block located on x, y. z
-	 */
-	public WorldBlockIndex(World world, int x, int y, int z) {
-
-		dimension = world.provider.dimensionId;
-		this.x = x;
-		this.y = y;
-		this.z = z;
-	}
-
-	public WorldBlockIndex(NBTTagCompound c) {
-		dimension = c.getInteger("dimension");
-		x = c.getInteger("x");
-		y = c.getInteger("y");
-		z = c.getInteger("z");
-	}
-
-	public WorldBlockIndex(Entity entity) {
-		dimension = entity.worldObj.provider.dimensionId;
-		x = (int) Math.floor(entity.posX);
-		y = (int) Math.floor(entity.posY);
-		z = (int) Math.floor(entity.posZ);
-	}
-
-	/**
-	 * Provides a deterministic and complete ordering of block positions.
-	 */
-	@Override
-	public int compareTo(WorldBlockIndex o) {
-
-		if (o.dimension < dimension) {
-			return 1;
-		} else if (o.dimension > dimension) {
-			return -1;
-		} else if (o.x < x) {
-			return 1;
-		} else if (o.x > x) {
-			return -1;
-		} else if (o.z < z) {
-			return 1;
-		} else if (o.z > z) {
-			return -1;
-		} else if (o.y < y) {
-			return 1;
-		} else if (o.y > y) {
-			return -1;
-		} else {
-			return 0;
-		}
-	}
-
-	public void writeTo(NBTTagCompound c) {
-		c.setInteger("dimension", dimension);
-		c.setInteger("x", x);
-		c.setInteger("y", y);
-		c.setInteger("z", z);
-	}
-
-	@Override
-	public String toString() {
-		return "{" + dimension + ":" + x + ", " + y + ", " + z + "}";
-	}
-
-	@Override
-	public boolean equals(Object obj) {
-		if (obj instanceof WorldBlockIndex) {
-			WorldBlockIndex b = (WorldBlockIndex) obj;
-
-			return b.dimension == dimension && b.x == x && b.y == y && b.z == z;
-		}
-
-		return super.equals(obj);
-	}
-
-	@Override
-	public int hashCode() {
-		return (dimension * 37 + (x * 37 + y)) * 37 + z;
-	}
-}

api/buildcraft/api/power/IEngine.java

@@ -16,6 +16,21 @@ import net.minecraftforge.common.util.ForgeDirection;
  * without using receiveEnergy() (which has other issues).
  */
 public interface IEngine {
+    /**
+     * Returns true if the engine wants to receive power from
+     * another engine on this side.
+     * @param side
+     * @return
+     */
     boolean canReceiveFromEngine(ForgeDirection side);
+
+    /**
+     * Receives energy from an engine.
+     * See {@link cofh.api.energy.IEnergyHandler#receiveEnergy(ForgeDirection, int, boolean)}
+     * @param side The side the engine is receiving energy from.
+     * @param energy The amount of energy given to the engine.
+     * @param simulate True if the energy should not actually be added.
+     * @return The amount of energy used by the engine.
+     */
     int receiveEnergyFromEngine(ForgeDirection side, int energy, boolean simulate);
 }

api/buildcraft/api/power/ILaserTarget.java

@@ -8,6 +8,12 @@
  */
 package buildcraft.api.power;
 
+/**
+ * This interface should be defined by any Tile which wants
+ * to receive energy from BuildCraft lasers.
+ *
+ * The respective Block MUST implement ILaserTargetBlock!
+ */
 public interface ILaserTarget {
 
 	/**
@@ -33,9 +39,21 @@ public interface ILaserTarget {
 	 */
 	boolean isInvalidTarget();
 
+	/**
+	 * Get the X coordinate of the laser stream.
+	 * @return
+	 */
 	double getXCoord();
 
+	/**
+	 * Get the Y coordinate of the laser stream.
+	 * @return
+	 */
 	double getYCoord();
 
+	/**
+	 * Get the Z coordinate of the laser stream.
+	 * @return
+	 */
 	double getZCoord();
 }

api/buildcraft/api/power/ILaserTargetBlock.java

@@ -8,6 +8,12 @@
  */
 package buildcraft.api.power;
 
+/**
+ * This is a marker interface for laser targets. Implement it on
+ * your Block.
+ *
+ * It is used by BuildCraft Lasers for optimization purposes.
+ */
 public interface ILaserTargetBlock {
 
 }

api/buildcraft/api/tiles/IControllable.java

@@ -8,12 +8,34 @@
  */
 package buildcraft.api.tiles;
 
+/**
+ * This interface should be implemented by any Tile Entity which wishes to
+ * have non-redstone automation (for example, BuildCraft Gates, but also
+ * other mods which implement it, e.g. OpenComputers).
+ */
 public interface IControllable {
 	public enum Mode {
 		Unknown, On, Off, Loop
 	}
 
+	/**
+	 * Get the current control mode of the Tile Entity.
+	 * @return
+	 */
 	Mode getControlMode();
+
+	/**
+	 * Set the mode of the Tile Entity.
+	 * @param mode
+	 */
 	void setControlMode(Mode mode);
+
+	/**
+	 * Check if a given control mode is accepted.
+	 * If you query IControllable tiles, you MUST check with
+	 * acceptsControlMode first.
+	 * @param mode
+	 * @return True if this control mode is accepted.
+	 */
 	boolean acceptsControlMode(Mode mode);
 }

api/buildcraft/api/tiles/IHasWork.java

@@ -8,6 +8,14 @@
  */
 package buildcraft.api.tiles;
 
+/**
+ * This interface should be implemented by any Tile Entity which carries out
+ * work (crafting, ore processing, mining, et cetera).
+ */
 public interface IHasWork {
+	/**
+	 * Check if the Tile Entity is currently doing any work.
+	 * @return True if the Tile Entity is doing work.
+	 */
 	boolean hasWork();
 }

api/buildcraft/api/tiles/IHeatable.java

@@ -8,11 +8,35 @@
  */
 package buildcraft.api.tiles;
 
+/**
+ * This interface should be implemented by Tile Entities
+ * which have an internal heat value.
+ */
 public interface IHeatable {
+    /**
+     * @return The minimum heat value, in degrees.
+     */
     double getMinHeatValue();
+
+    /**
+     * @return The preferred heat value, in degrees.
+     */
     double getIdealHeatValue();
+
+    /**
+     * @return The maxmimum heat value, in degrees.
+     */
     double getMaxHeatValue();
 
+    /**
+     * @return The current heat value, in degrees.
+     */
     double getCurrentHeatValue();
+
+    /**
+     * Set the heat of the tile.
+     * @param value Heat value, in degrees.
+     * @return The heat the tile has after the set.
+     */
     double setHeatValue(double value);
 }