Update API documentation

src/main/java/refinedstorage/api/RefinedStorageAPI.java

@@ -4,7 +4,7 @@ import refinedstorage.api.solderer.ISoldererRegistry;
 
 public final class RefinedStorageAPI {
     /**
-     * The solderer registry, set in pre initialization.
+     * The solderer registry, set in pre-initialization.
      */
     public static ISoldererRegistry SOLDERER_REGISTRY;
 }

src/main/java/refinedstorage/api/autocrafting/ICraftingPattern.java

@@ -10,7 +10,7 @@ import net.minecraft.world.World;
 public interface ICraftingPattern {
     /**
      * @param world The world
-     * @return Returns the container where the pattern is in
+     * @return The container where the pattern is in
      */
     ICraftingPatternContainer getContainer(World world);
 
@@ -37,8 +37,8 @@ public interface ICraftingPattern {
     /**
      * Writes this pattern to NBT.
      *
-     * @param tag The NBT tag
+     * @param tag The NBT tag to write to
-     * @return The NBT tag
+     * @return The written NBT tag
      */
     NBTTagCompound writeToNBT(NBTTagCompound tag);
 }

src/main/java/refinedstorage/api/autocrafting/ICraftingTask.java

@@ -37,7 +37,7 @@ public interface ICraftingTask {
     /**
      * Writes this crafting task to NBT.
      *
-     * @param tag The NBT tag
+     * @param tag The NBT tag to write to
      */
     void writeToNBT(NBTTagCompound tag);
 

src/main/java/refinedstorage/api/network/GridPullFlags.java

@@ -1,7 +1,7 @@
 package refinedstorage.api.network;
 
 /**
- * Flags for knowing what pull action the player is performing, can be combined.
+ * Flags for knowing what pull action the player is performing, these can be combined.
  */
 public class GridPullFlags {
     public static final int PULL_HALF = 1;

src/main/java/refinedstorage/api/network/IGridHandler.java

@@ -12,23 +12,23 @@ public interface IGridHandler {
     /**
      * Called when a player tries to pull an item from the grid.
      *
-     * @param stack  The stack we're trying to pull
+     * @param stack  The item we're trying to pull
      * @param flags  How we are pulling, see {@link GridPullFlags}
      * @param player The player that is attempting the pull
      */
     void onPull(ItemStack stack, int flags, EntityPlayerMP player);
 
     /**
-     * Called when a player tries to push to the grid
+     * Called when a player tries to push to the grid.
      *
-     * @param stack The stack we're trying to push
+     * @param stack The item we're trying to push
-     * @return The remainder, or null if no remainder
+     * @return The remainder, or null if there is no remainder
      */
     @Nullable
     ItemStack onPush(ItemStack stack);
 
     /**
-     * Called when a player is trying to push an item that it is holding in their hand in the GUI, so not with shift.
+     * Called when a player is trying to push an item that it is holding in their hand in the GUI.
      *
      * @param single If we are only pushing 1 item
      * @param player The player that is attempting the push

src/main/java/refinedstorage/api/network/INetworkMaster.java

@@ -13,6 +13,9 @@ import javax.annotation.Nonnull;
 import javax.annotation.Nullable;
 import java.util.List;
 
+/**
+ * Represents a network master, usually is a controller.
+ */
 public interface INetworkMaster {
     /**
      * @return The energy storage of this network
@@ -20,12 +23,12 @@ public interface INetworkMaster {
     EnergyStorage getEnergy();
 
     /**
-     * @return The energy usage of this network
+     * @return The energy usage per tick of this network
      */
     int getEnergyUsage();
 
     /**
-     * @return The position of this network in the world (usually where the controller is)
+     * @return The position of this network in the world
      */
     BlockPos getPosition();
 
@@ -35,7 +38,7 @@ public interface INetworkMaster {
     boolean canRun();
 
     /**
-     * @return A list with all network slaves
+     * @return A list with all the network slaves
      */
     List<INetworkSlave> getSlaves();
 
@@ -50,12 +53,12 @@ public interface INetworkMaster {
     void removeSlave(@Nonnull INetworkSlave slave);
 
     /**
-     * @return The grid handler for this network
+     * @return The {@link IGridHandler} for this network
      */
     IGridHandler getGridHandler();
 
     /**
-     * @return The wireless grid handler for this network
+     * @return The {@link IWirelessGridHandler} for this network
      */
     IWirelessGridHandler getWirelessGridHandler();
 
@@ -84,7 +87,7 @@ public interface INetworkMaster {
     void addCraftingTaskAsLast(@Nonnull ICraftingTask task);
 
     /**
-     * Creates a crafting task from a pattern.
+     * Creates a crafting task from a {@link ICraftingPattern}.
      *
      * @param pattern The pattern to create a task for
      * @return A task
@@ -111,7 +114,7 @@ public interface INetworkMaster {
     /**
      * Returns crafting patterns from an item stack.
      *
-     * @param pattern The item to get a pattern for
+     * @param pattern The {@link ItemStack} to get a pattern for
      * @param flags   The flags to compare on, see {@link CompareFlags}
      * @return A list of crafting patterns where the given pattern is one of the outputs
      */
@@ -126,20 +129,20 @@ public interface INetworkMaster {
     ICraftingPattern getPattern(ItemStack pattern, int flags);
 
     /**
-     * Sends to all clients in a grid a packet with all the items in this network.
+     * Sends a grid packet with all the items to all clients that are watching a grid.
      */
     void sendStorageToClient();
 
     /**
-     * Sends a player a packet with all the items in this network.
+     * Sends a grid packet with all the items to a specific player.
      */
     void sendStorageToClient(EntityPlayerMP player);
 
     /**
-     * Sends a storage change to the client.
+     * Sends a storage change to all clients that are watching a grid.
      *
      * @param stack The stack
-     * @param delta The delta changed
+     * @param delta The delta
      */
     void sendStorageDeltaToClient(ItemStack stack, int delta);
 
@@ -157,10 +160,10 @@ public interface INetworkMaster {
     /**
      * Takes an item from this network.
      *
-     * @param stack A prototype of the stack to take, do NOT modify
+     * @param stack The prototype of the stack to take, do NOT modify
      * @param size  The amount of that prototype that has to be taken
      * @param flags The flags to compare on, see {@link CompareFlags}
-     * @return null if we didn't takeFromNetwork anything, or a {@link ItemStack} with the result
+     * @return null if we didn't take anything, or a {@link ItemStack} with the result
      */
     @Nullable
     ItemStack take(@Nonnull ItemStack stack, int size, int flags);

src/main/java/refinedstorage/api/network/INetworkSlave.java

@@ -4,16 +4,16 @@ import net.minecraft.util.math.BlockPos;
 import net.minecraft.world.World;
 
 /**
- * Represents a slave or machine in the storage network.
+ * Represents a node in the storage network.
  */
 public interface INetworkSlave {
     /**
-     * Called every tile entity tick
+     * Called every tile entity tick.
      */
     void updateSlave();
 
     /**
-     * @return If the slave can send a connectivity update (for most slaves this is true, for cables it's false)
+     * @return If the slave can send a connectivity update
      */
     boolean canSendConnectivityUpdate();
 
@@ -55,7 +55,7 @@ public interface INetworkSlave {
     boolean isConnected();
 
     /**
-     * @return If {@link INetworkSlave#canUpdate()} can get called. Typically checks for connection and redstone mode.
+     * @return If {@link INetworkSlave#canUpdate()} can get called. Typically checks for connection status and redstone mode.
      */
     boolean canUpdate();
 

src/main/java/refinedstorage/api/network/IWirelessGridHandler.java

@@ -47,7 +47,7 @@ public interface IWirelessGridHandler {
      * Returns a {@link WirelessGridConsumer} for a player.
      *
      * @param player The player to get the wireless grid consumer for
-     * @return The wireless grid consumer of the player, or null if the player isn't in a wireless grid
+     * @return The {@link IWirelessGridHandler} that corresponds to a player, or null if the player isn't using a wireless grid
      */
     @Nullable
     WirelessGridConsumer getConsumer(EntityPlayer player);

src/main/java/refinedstorage/api/network/WirelessGridConsumer.java

@@ -14,7 +14,7 @@ public class WirelessGridConsumer {
 
     /**
      * @param player       The player using this wireless grid
-     * @param hand         The hand that this wireless grid is in
+     * @param hand         The hand that this wireless grid is opened with
      * @param wirelessGrid The wireless grid {@link ItemStack} in the player's inventory
      */
     public WirelessGridConsumer(EntityPlayer player, EnumHand hand, ItemStack wirelessGrid) {
@@ -31,7 +31,7 @@ public class WirelessGridConsumer {
     }
 
     /**
-     * @return The hand this wireless grid is in
+     * @return The hand this wireless grid is opened with
      */
     public EnumHand getHand() {
         return hand;

src/main/java/refinedstorage/api/solderer/ISoldererRegistry.java

@@ -24,7 +24,7 @@ public interface ISoldererRegistry {
 
     /**
      * @param items An item handler, where slots 0 - 2 are the rows
-     * @return The recipe, or null if no recipe was found
+     * @return The {@link ISoldererRecipe}, or null if no recipe was found
      */
     @Nullable
     ISoldererRecipe getRecipe(@Nonnull IItemHandler items);

src/main/java/refinedstorage/api/storage/IGroupedStorage.java

@@ -31,16 +31,16 @@ public interface IGroupedStorage {
     void remove(ItemStack stack);
 
     /**
-     * Gets an item from the network, does not decrement its count.
+     * Gets an item from the network, does not decrement its count like {@link IGroupedStorage#remove(ItemStack)} does.
      *
      * @param stack The stack to find
      * @param flags The flags to compare on, see {@link CompareFlags}
-     * @return The stack, do NOT modify
+     * @return The {@link ItemStack}, do NOT modify
      */
     ItemStack get(ItemStack stack, int flags);
 
     /**
-     * @return All stacks in this storage network
+     * @return All items in this storage network
      */
     Collection<ItemStack> getStacks();
 

src/main/java/refinedstorage/api/storage/IStorage.java

@@ -30,12 +30,12 @@ public interface IStorage {
     /**
      * Takes an item from storage.
      * If the stack we found in the system is smaller than the requested size, return the stack anyway.
-     * For example: this method is called for dirt (64x) while there is only dirt (32x), return the dirt (32x) anyway.
+     * For example: if this method is called for dirt (64x) while there is only dirt (32x), return the dirt (32x) anyway.
      *
-     * @param stack A prototype of the stack to takeFromNetwork, do NOT modify
+     * @param stack A prototype of the stack to take, do NOT modify
      * @param size  The amount of that prototype that has to be taken
-     * @param flags On what we are comparing to takeFromNetwork the item, see {@link CompareFlags}
+     * @param flags On what we are comparing to take the item, see {@link CompareFlags}
-     * @return null if we didn't takeFromNetwork anything, or a {@link ItemStack} with the result
+     * @return null if we didn't take anything, or a {@link ItemStack} with the result
      */
     @Nullable
     ItemStack take(@Nonnull ItemStack stack, int size, int flags);

src/main/java/refinedstorage/api/storage/IStorageProvider.java

@@ -7,7 +7,7 @@ import java.util.List;
  */
 public interface IStorageProvider {
     /**
-     * Adds the storages that this storage provides.
+     * Adds the storages that this storage provider provides.
      *
      * @param storages The previously added storages
      */