From eadfe56d5ab1dbcd6fee172cebf8f349f38447eb Mon Sep 17 00:00:00 2001 From: Raoul Van den Berge Date: Sun, 12 Jun 2016 10:57:44 +0200 Subject: [PATCH] API doc improvements --- .../api/solderer/ISoldererRecipe.java | 8 ++++---- .../api/solderer/SoldererRecipeBasic.java | 4 +++- .../api/solderer/SoldererRegistry.java | 6 ++++-- .../refinedstorage/api/storage/CompareFlags.java | 3 +++ .../java/refinedstorage/api/storage/IStorage.java | 6 +++--- .../api/storage/IStorageProvider.java | 1 + .../java/refinedstorage/api/storage/NBTStorage.java | 13 ++++++++++--- 7 files changed, 28 insertions(+), 13 deletions(-) diff --git a/src/main/java/refinedstorage/api/solderer/ISoldererRecipe.java b/src/main/java/refinedstorage/api/solderer/ISoldererRecipe.java index 1ccc01bcf..e14a0a650 100755 --- a/src/main/java/refinedstorage/api/solderer/ISoldererRecipe.java +++ b/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(); } diff --git a/src/main/java/refinedstorage/api/solderer/SoldererRecipeBasic.java b/src/main/java/refinedstorage/api/solderer/SoldererRecipeBasic.java index 1ba619df1..5962738fa 100755 --- a/src/main/java/refinedstorage/api/solderer/SoldererRecipeBasic.java +++ b/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"); } diff --git a/src/main/java/refinedstorage/api/solderer/SoldererRegistry.java b/src/main/java/refinedstorage/api/solderer/SoldererRegistry.java index bd8a3d1c8..5bc187c8a 100755 --- a/src/main/java/refinedstorage/api/solderer/SoldererRegistry.java +++ b/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; diff --git a/src/main/java/refinedstorage/api/storage/CompareFlags.java b/src/main/java/refinedstorage/api/storage/CompareFlags.java index 1a65c46f1..fa5d62d08 100755 --- a/src/main/java/refinedstorage/api/storage/CompareFlags.java +++ b/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; diff --git a/src/main/java/refinedstorage/api/storage/IStorage.java b/src/main/java/refinedstorage/api/storage/IStorage.java index be7b6ff28..f3407b154 100755 --- a/src/main/java/refinedstorage/api/storage/IStorage.java +++ b/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 diff --git a/src/main/java/refinedstorage/api/storage/IStorageProvider.java b/src/main/java/refinedstorage/api/storage/IStorageProvider.java index 5cb1f93f1..240b88194 100755 --- a/src/main/java/refinedstorage/api/storage/IStorageProvider.java +++ b/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 { /** diff --git a/src/main/java/refinedstorage/api/storage/NBTStorage.java b/src/main/java/refinedstorage/api/storage/NBTStorage.java index aa84cfd51..3cdac83ea 100755 --- a/src/main/java/refinedstorage/api/storage/NBTStorage.java +++ b/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 stacks = new ArrayList(); /** - * @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());