API doc improvements

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

@@ -10,20 +10,20 @@ import javax.annotation.Nullable;
  */
 public interface ISoldererRecipe {
     /**
-     * @param row The solderer row (between 0 - 2)
-     * @return A stack for the given row
+     * @param row The row in the solderer that we want the {@link ItemStack} for (between 0 - 2)
+     * @return A {@link ItemStack} for the given row
      */
     @Nullable
     ItemStack getRow(int row);
 
     /**
-     * @return The stack that this recipe gives back
+     * @return The {@link ItemStack} that this recipe gives back
      */
     @Nonnull
     ItemStack getResult();
 
     /**
-     * @return The duration in ticks
+     * @return The duration in ticks that this recipe takes to give the result back from {@link ISoldererRecipe#getResult()}
      */
     int getDuration();
 }

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

@@ -2,6 +2,8 @@ package refinedstorage.api.solderer;
 
 import net.minecraft.item.ItemStack;
 
+import javax.annotation.Nonnull;
+
 /**
  * A solderer recipe with basic behaviour.
  * Implement {@link ISoldererRecipe} for custom behaviour.
@@ -16,7 +18,7 @@ public class SoldererRecipeBasic implements ISoldererRecipe {
      * @param duration The duration in ticks
      * @param rows     The rows of this recipe, has to be 3 rows (null for an empty row)
      */
-    public SoldererRecipeBasic(ItemStack result, int duration, ItemStack... rows) {
+    public SoldererRecipeBasic(@Nonnull ItemStack result, int duration, ItemStack... rows) {
         if (rows.length != 3) {
             throw new IllegalArgumentException("Solderer recipe expects 3 rows, got " + rows.length + " rows");
         }

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

@@ -5,6 +5,7 @@ import net.minecraftforge.items.IItemHandler;
 import refinedstorage.RefinedStorageUtils;
 
 import javax.annotation.Nonnull;
+import javax.annotation.Nullable;
 import java.util.ArrayList;
 import java.util.List;
 
@@ -17,7 +18,7 @@ public class SoldererRegistry {
     /**
      * Adds a recipe to the registry.
      *
-     * @param recipe
+     * @param recipe The recipe to add
      */
     public static void addRecipe(@Nonnull ISoldererRecipe recipe) {
         recipes.add(recipe);
@@ -32,8 +33,9 @@ public class SoldererRegistry {
 
     /**
      * @param items An item handler, where slots 0 - 2 are the row slots
-     * @return The recipe
+     * @return The recipe, or null if no recipe was found
      */
+    @Nullable
     public static ISoldererRecipe getRecipe(@Nonnull IItemHandler items) {
         for (ISoldererRecipe recipe : recipes) {
             boolean found = true;

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

@@ -1,5 +1,8 @@
 package refinedstorage.api.storage;
 
+/**
+ * Comparison flags.
+ */
 public final class CompareFlags {
     public static final int COMPARE_DAMAGE = 1;
     public static final int COMPARE_NBT = 2;

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

@@ -11,7 +11,7 @@ import java.util.List;
  */
 public interface IStorage {
     /**
-     * Adds the items to the storage network.
+     * Adds the items in this storage to the storage network.
      * This is called every 20 ticks or when the storage changes, so don't make this method too resource intensive.
      *
      * @param items A list of previously added items
@@ -30,8 +30,8 @@ public interface IStorage {
 
     /**
      * Takes an item from storage.
-     * If the stack we found in the system is smaller then the requested size, return the stack anyway.
-     * For example: this function is called for dirt (64x) while there is only dirt (32x), return the dirt (32x) anyway.
+     * 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.
      *
      * @param stack A prototype of the stack to take, do NOT modify
      * @param size  The amount of that prototype that has to be taken

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

@@ -4,6 +4,7 @@ import java.util.List;
 
 /**
  * Should be implemented as a capability on tile entities.
+ * @see refinedstorage.api.RefinedStorageCapabilities#STORAGE_PROVIDER_CAPABILITY
  */
 public interface IStorageProvider {
     /**

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

@@ -17,7 +17,7 @@ import java.util.List;
  */
 public abstract class NBTStorage implements IStorage {
     /**
-     * The current save protocol Refined Storage uses, is set to every NBTStorage to allow for
+     * The current save protocol that is used. It's set to every {@link NBTStorage} to allow for
      * safe backwards compatibility breaks.
      */
     public static final int PROTOCOL = 1;
@@ -40,9 +40,9 @@ public abstract class NBTStorage implements IStorage {
     private List<ItemStack> stacks = new ArrayList<ItemStack>();
 
     /**
-     * @param tag      The NBT tag we are reading from and writing the amount stored to, has to be initialized with {@link NBTStorage#createNBT()}
+     * @param tag      The NBT tag we are reading from and writing the amount stored to, has to be initialized with {@link NBTStorage#createNBT()} if it doesn't exist yet
      * @param capacity The capacity of this storage
-     * @param tile     A tile that the NBT storage is in, will be marked dirty when storage changes
+     * @param tile     A {@link TileEntity} that the NBT storage is in, will be marked dirty when storage changes
      */
     public NBTStorage(NBTTagCompound tag, int capacity, @Nullable TileEntity tile) {
         this.tag = tag;
@@ -226,6 +226,9 @@ public abstract class NBTStorage implements IStorage {
         return tag.getInteger(NBT_STORED);
     }
 
+    /*
+     * @return A NBT tag initialized with the fields that {@link NBTStorage} uses
+     */
     public static NBTTagCompound createNBT() {
         NBTTagCompound tag = new NBTTagCompound();
 
@@ -236,6 +239,10 @@ public abstract class NBTStorage implements IStorage {
         return tag;
     }
 
+    /**
+     * @param stack The {@link ItemStack} to populate with the NBT tags from {@link NBTStorage#createNBT()}
+     * @return The provided {@link ItemStack} with NBT tags from {@link NBTStorage#createNBT()}
+     */
     public static ItemStack createStackWithNBT(ItemStack stack) {
         stack.setTagCompound(createNBT());