Update docs

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

@@ -3,11 +3,17 @@ package refinedstorage.api.storage;
 import net.minecraft.item.ItemStack;
 import refinedstorage.api.network.INetworkMaster;
 
+import javax.annotation.Nonnull;
+import javax.annotation.Nullable;
 import java.util.Collection;
 import java.util.List;
 
 /**
  * This holds all items from all the connected storages from a {@link INetworkMaster}.
+ * <p>
+ * Refined Storage uses this class mainly for use in Grids and Detectors to avoid querying
+ * individual {@link IStorage} constantly (performance impact) and to send and detect storage changes
+ * more efficiently.
  */
 public interface IGroupedStorage {
     /**
@@ -17,35 +23,45 @@ public interface IGroupedStorage {
     void rebuild();
 
     /**
-     * Adds an item to the network. Will merge it with another item if it already exists.
+     * Adds an item to the global item list.
+     * <p>
+     * Note that this doesn't modify any of the connected storages, but just modifies the global item list.
+     * Use {@link INetworkMaster#insertItem(ItemStack, int, boolean)} to add an item to an actual storage.
+     * <p>
+     * Will merge it with another item if it already exists.
      *
      * @param stack      The stack to add, do NOT modify
      * @param rebuilding Whether this method is called while the storage is rebuilding
      */
-    void add(ItemStack stack, boolean rebuilding);
+    void add(@Nonnull ItemStack stack, boolean rebuilding);
 
     /**
-     * Removes a item from the network.
+     * Removes a item from global item list.
+     * <p>
+     * Note that this doesn't modify any of the connected storages, but just modifies the global item list.
+     * Use {@link INetworkMaster#extractItem(ItemStack, int, int)} to remove an item from an actual storage.
      *
      * @param stack The item to remove, do NOT modify
      */
-    void remove(ItemStack stack);
+    void remove(@Nonnull ItemStack stack);
 
     /**
-     * Gets an item from the network, does not decrement its count like {@link IGroupedStorage#remove(ItemStack)} does.
+     * Gets an item from the network.
      *
      * @param stack The stack to find
      * @param flags The flags to compare on, see {@link CompareUtils}
-     * @return The {@link ItemStack}, do NOT modify
+     * @return Null if no item is found, or the {@link ItemStack}, do NOT modify
      */
-    ItemStack get(ItemStack stack, int flags);
+    @Nullable
+    ItemStack get(@Nonnull ItemStack stack, int flags);
 
     /**
-     * Gets an item from the network by ID.
+     * Gets an item from the network by hash.
      *
-     * @return The {@link ItemStack}, do NOT modify
+     * @return Null if no item is found matching the hash, or the {@link ItemStack}, do NOT modify
      */
-    ItemStack get(int id);
+    @Nullable
+    ItemStack get(int hash);
 
     /**
      * @return All items in this storage network

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

@@ -17,7 +17,7 @@ public interface IStorage {
     List<ItemStack> getItems();
 
     /**
-     * Inserts an item to this storage.
+     * Inserts an item to the storage network.
      *
      * @param stack    The stack prototype to insert, do NOT modify
      * @param size     The amount of that prototype that has to be inserted
@@ -28,8 +28,8 @@ public interface IStorage {
     ItemStack insertItem(@Nonnull ItemStack stack, int size, boolean simulate);
 
     /**
-     * Extracts an item from storage.
+     * Extracts an item from the storage network.
-     *
+     * <p>
      * If the stack we found in the system is smaller than the requested size, return the stack anyway.
      * For example: if this method is called for dirt (64x) while there is only dirt (32x), return the dirt (32x) anyway.
      *

src/main/java/refinedstorage/apiimpl/network/NetworkUtils.java

@@ -5,6 +5,8 @@ import refinedstorage.api.autocrafting.ICraftingPattern;
 import refinedstorage.api.network.INetworkMaster;
 import refinedstorage.api.storage.CompareUtils;
 
+// @TODO: Move this class to API
+// @TODO: Move IC2-specific stuff to special IC2 integration class, along with the IC2 wrapper class
 public final class NetworkUtils {
     public static int convertIC2ToRF(double amount) {
         return amount >= Double.POSITIVE_INFINITY ? Integer.MAX_VALUE : ((int) Math.floor(amount) * 4);

src/main/java/refinedstorage/apiimpl/storage/GroupedStorage.java

@@ -13,6 +13,8 @@ import refinedstorage.api.storage.IStorage;
 import refinedstorage.api.storage.IStorageProvider;
 import refinedstorage.apiimpl.network.NetworkUtils;
 
+import javax.annotation.Nonnull;
+import javax.annotation.Nullable;
 import java.util.ArrayList;
 import java.util.Collection;
 import java.util.List;
@@ -56,7 +58,7 @@ public class GroupedStorage implements IGroupedStorage {
     }
 
     @Override
-    public void add(ItemStack stack, boolean rebuilding) {
+    public void add(@Nonnull ItemStack stack, boolean rebuilding) {
         for (ItemStack otherStack : stacks.get(stack.getItem())) {
             if (CompareUtils.compareStackNoQuantity(otherStack, stack)) {
                 otherStack.stackSize += stack.stackSize;
@@ -77,7 +79,7 @@ public class GroupedStorage implements IGroupedStorage {
     }
 
     @Override
-    public void remove(ItemStack stack) {
+    public void remove(@Nonnull ItemStack stack) {
         for (ItemStack otherStack : stacks.get(stack.getItem())) {
             if (CompareUtils.compareStackNoQuantity(otherStack, stack)) {
                 otherStack.stackSize -= stack.stackSize;
@@ -96,7 +98,8 @@ public class GroupedStorage implements IGroupedStorage {
     }
 
     @Override
-    public ItemStack get(ItemStack stack, int flags) {
+    @Nullable
+    public ItemStack get(@Nonnull ItemStack stack, int flags) {
         for (ItemStack otherStack : stacks.get(stack.getItem())) {
             if (CompareUtils.compareStack(otherStack, stack, flags)) {
                 return otherStack;
@@ -107,9 +110,10 @@ public class GroupedStorage implements IGroupedStorage {
     }
 
     @Override
-    public ItemStack get(int id) {
+    @Nullable
+    public ItemStack get(int hash) {
         for (ItemStack stack : this.stacks.values()) {
-            if (NetworkUtils.getItemStackHashCode(stack) == id) {
+            if (NetworkUtils.getItemStackHashCode(stack) == hash) {
                 return stack;
             }
         }