From dafbdbc06b5195a2662aae0b7070cbff82dae5c6 Mon Sep 17 00:00:00 2001 From: mezz Date: Tue, 2 Aug 2016 00:43:33 -0700 Subject: [PATCH] Improve API documentation --- .../java/mezz/jei/api/BlankModPlugin.java | 4 ++ src/main/java/mezz/jei/api/IGuiHelper.java | 1 + .../java/mezz/jei/api/IItemBlacklist.java | 11 +++- .../java/mezz/jei/api/IItemListOverlay.java | 1 + src/main/java/mezz/jei/api/IItemRegistry.java | 17 ++++-- src/main/java/mezz/jei/api/IJeiHelpers.java | 2 +- src/main/java/mezz/jei/api/IJeiRuntime.java | 5 +- src/main/java/mezz/jei/api/IModPlugin.java | 9 +-- src/main/java/mezz/jei/api/IModRegistry.java | 5 +- .../java/mezz/jei/api/IRecipeRegistry.java | 2 +- src/main/java/mezz/jei/api/IRecipesGui.java | 1 + .../java/mezz/jei/api/ISubtypeRegistry.java | 2 +- src/main/java/mezz/jei/api/JEIPlugin.java | 2 +- .../mezz/jei/api/gui/IAdvancedGuiHandler.java | 4 +- .../mezz/jei/api/gui/ICraftingGridHelper.java | 6 +- src/main/java/mezz/jei/api/gui/IDrawable.java | 11 ++++ .../mezz/jei/api/gui/IDrawableAnimated.java | 16 ++++++ .../mezz/jei/api/gui/IDrawableStatic.java | 3 + .../mezz/jei/api/gui/IGuiFluidStackGroup.java | 4 +- .../java/mezz/jei/api/gui/IGuiIngredient.java | 25 +++++++++ .../mezz/jei/api/gui/IGuiIngredientGroup.java | 5 +- .../mezz/jei/api/gui/IGuiItemStackGroup.java | 2 + .../java/mezz/jei/api/gui/IRecipeLayout.java | 8 +++ .../java/mezz/jei/api/gui/ITickTimer.java | 5 +- .../mezz/jei/api/gui/ITooltipCallback.java | 9 ++- src/main/java/mezz/jei/api/package-info.java | 2 +- .../jei/api/recipe/BlankRecipeCategory.java | 3 + .../jei/api/recipe/BlankRecipeWrapper.java | 3 + src/main/java/mezz/jei/api/recipe/IFocus.java | 16 ++++++ .../mezz/jei/api/recipe/IRecipeCategory.java | 25 ++++++--- .../mezz/jei/api/recipe/IRecipeHandler.java | 24 +++++++- .../mezz/jei/api/recipe/IRecipeWrapper.java | 25 +++++++-- .../mezz/jei/api/recipe/IStackHelper.java | 2 + .../api/recipe/VanillaRecipeCategoryUid.java | 55 ++++++++++++++++++- .../recipe/transfer/IRecipeTransferError.java | 12 +++- .../transfer/IRecipeTransferHandler.java | 4 +- .../IRecipeTransferHandlerHelper.java | 15 +++-- .../recipe/transfer/IRecipeTransferInfo.java | 6 +- .../transfer/IRecipeTransferRegistry.java | 2 + .../wrapper/ICraftingRecipeWrapper.java | 7 +++ .../wrapper/IShapedCraftingRecipeWrapper.java | 9 +++ 41 files changed, 318 insertions(+), 52 deletions(-) diff --git a/src/main/java/mezz/jei/api/BlankModPlugin.java b/src/main/java/mezz/jei/api/BlankModPlugin.java index 42af48f25..956273afa 100644 --- a/src/main/java/mezz/jei/api/BlankModPlugin.java +++ b/src/main/java/mezz/jei/api/BlankModPlugin.java @@ -2,6 +2,10 @@ import javax.annotation.Nonnull; +/** + * An {@link IModPlugin} that does nothing, inherit from this to avoid implementing methods you don't need. + * IModPlugin implementations must have the {@link JEIPlugin} annotation to get loaded by JEI. + */ public abstract class BlankModPlugin implements IModPlugin { @Override public void register(@Nonnull IModRegistry registry) { diff --git a/src/main/java/mezz/jei/api/IGuiHelper.java b/src/main/java/mezz/jei/api/IGuiHelper.java index 82773ff05..c1c81a5b0 100644 --- a/src/main/java/mezz/jei/api/IGuiHelper.java +++ b/src/main/java/mezz/jei/api/IGuiHelper.java @@ -11,6 +11,7 @@ /** * Helps with the implementation of GUIs. + * Get the instance from {@link IJeiHelpers#getGuiHelper()}. */ public interface IGuiHelper { diff --git a/src/main/java/mezz/jei/api/IItemBlacklist.java b/src/main/java/mezz/jei/api/IItemBlacklist.java index 9da6a5083..7b82c5881 100644 --- a/src/main/java/mezz/jei/api/IItemBlacklist.java +++ b/src/main/java/mezz/jei/api/IItemBlacklist.java @@ -3,11 +3,16 @@ import javax.annotation.Nonnull; import net.minecraft.item.ItemStack; +import net.minecraftforge.oredict.OreDictionary; +/** + * The Item Blacklist allows mods to hide their items from JEI's item list. + * Get the instance from {@link IJeiHelpers#getItemBlacklist()}. + */ public interface IItemBlacklist { /** * Stop JEI from displaying a specific item in the item list. - * Use OreDictionary.WILDCARD_VALUE meta for wildcard. + * Use {@link OreDictionary#WILDCARD_VALUE} meta for wildcard. * Items blacklisted with this API can't be seen in the config or in edit mode. */ void addItemToBlacklist(@Nonnull ItemStack itemStack); @@ -19,6 +24,8 @@ public interface IItemBlacklist { */ void removeItemFromBlacklist(@Nonnull ItemStack itemStack); - /** Returns true if the item is blacklisted and will not be displayed in the item list. */ + /** + * Returns true if the item is blacklisted and will not be displayed in the item list. + */ boolean isItemBlacklisted(@Nonnull ItemStack itemStack); } diff --git a/src/main/java/mezz/jei/api/IItemListOverlay.java b/src/main/java/mezz/jei/api/IItemListOverlay.java index 151c74aaf..e5770f56d 100644 --- a/src/main/java/mezz/jei/api/IItemListOverlay.java +++ b/src/main/java/mezz/jei/api/IItemListOverlay.java @@ -11,6 +11,7 @@ /** * The IItemListOverlay is JEI's gui that displays all the items next to an open container gui. * Use this interface to get information from and interact with it. + * Get the instance from {@link IJeiRuntime#getItemListOverlay()}. */ public interface IItemListOverlay { diff --git a/src/main/java/mezz/jei/api/IItemRegistry.java b/src/main/java/mezz/jei/api/IItemRegistry.java index 1f88cad85..25e606c00 100644 --- a/src/main/java/mezz/jei/api/IItemRegistry.java +++ b/src/main/java/mezz/jei/api/IItemRegistry.java @@ -8,7 +8,7 @@ /** * The IItemRegistry is provided by JEI and has some useful functions related to items. - * Get it from IModRegistry, which is available to IModPlugins. + * Get the instance from {@link IModRegistry#getItemRegistry()}. */ public interface IItemRegistry { @@ -18,18 +18,27 @@ public interface IItemRegistry { @Nonnull ImmutableList getItemList(); - /** Returns a list of all the ItemStacks that can be used as fuel in a vanilla furnace. */ + /** + * Returns a list of all the ItemStacks that can be used as fuel in a vanilla furnace. + */ @Nonnull ImmutableList getFuels(); - /** Returns a list of all the ItemStacks that return true to isPotionIngredient. */ + /** + * Returns a list of all the ItemStacks that return true to isPotionIngredient. + */ @Nonnull ImmutableList getPotionIngredients(); - /** Returns a mod name for the given item. */ + /** + * Returns a mod name for the given item. + */ @Nonnull String getModNameForItem(@Nonnull Item item); + /** + * Returns all the items registered by a specific mod. + */ @Nonnull ImmutableList getItemListForModId(@Nonnull String modId); } diff --git a/src/main/java/mezz/jei/api/IJeiHelpers.java b/src/main/java/mezz/jei/api/IJeiHelpers.java index ac80a8890..07929dd6b 100644 --- a/src/main/java/mezz/jei/api/IJeiHelpers.java +++ b/src/main/java/mezz/jei/api/IJeiHelpers.java @@ -7,7 +7,7 @@ /** * IJeiHelpers provides helpers and tools for addon mods. - * Get it from IModRegistry, which is available to IModPlugins. + * Get the instance from {@link IModRegistry#getJeiHelpers()}. */ public interface IJeiHelpers { /** diff --git a/src/main/java/mezz/jei/api/IJeiRuntime.java b/src/main/java/mezz/jei/api/IJeiRuntime.java index b87016f30..6186e76a3 100644 --- a/src/main/java/mezz/jei/api/IJeiRuntime.java +++ b/src/main/java/mezz/jei/api/IJeiRuntime.java @@ -2,7 +2,10 @@ import javax.annotation.Nonnull; -/** Gives access to JEI functions that are available once everything has loaded */ +/** + * Gives access to JEI functions that are available once everything has loaded. + * The IJeiRuntime instance is passed to your mod plugin in {@link IModPlugin#onRuntimeAvailable(IJeiRuntime)}. + */ public interface IJeiRuntime { @Nonnull IRecipeRegistry getRecipeRegistry(); diff --git a/src/main/java/mezz/jei/api/IModPlugin.java b/src/main/java/mezz/jei/api/IModPlugin.java index 2df1bc80f..b368f7809 100644 --- a/src/main/java/mezz/jei/api/IModPlugin.java +++ b/src/main/java/mezz/jei/api/IModPlugin.java @@ -3,15 +3,16 @@ import javax.annotation.Nonnull; /** - * The main class for a plugin. Everything communicated between a mod and JEI is through this class. - * IModPlugins must have the @JEIPlugin annotation to get loaded by JEI. + * The main class to implement to create a JEI plugin. Everything communicated between a mod and JEI is through this class. + * IModPlugins must have the {@link JEIPlugin} annotation to get loaded by JEI. * This class must not import anything that could be missing at runtime (i.e. code from any other mod). + * + * @see BlankModPlugin */ public interface IModPlugin { /** * Register this mod plugin with the mod registry. - * Called just before the game launches. - * Will be called again if config + * Called when the player joins the world and any time JEI reloads (like for a config change). */ void register(@Nonnull IModRegistry registry); diff --git a/src/main/java/mezz/jei/api/IModRegistry.java b/src/main/java/mezz/jei/api/IModRegistry.java index f1eec08c9..81bdfe42f 100644 --- a/src/main/java/mezz/jei/api/IModRegistry.java +++ b/src/main/java/mezz/jei/api/IModRegistry.java @@ -11,12 +11,13 @@ import java.util.List; /** - * Passed to IModPlugins so they can register themselves. + * Entry point for the JEI API, functions for registering recipes are available from here. + * The IModRegistry instance is passed to your mod plugin in {@link IModPlugin#register(IModRegistry)}. */ public interface IModRegistry { /** - * Get helpers and tools for addon mods. + * Get helpers and tools for implementing JEI plugins. * @since JEI 2.27.0 */ @Nonnull diff --git a/src/main/java/mezz/jei/api/IRecipeRegistry.java b/src/main/java/mezz/jei/api/IRecipeRegistry.java index a70425388..07d9192f6 100644 --- a/src/main/java/mezz/jei/api/IRecipeRegistry.java +++ b/src/main/java/mezz/jei/api/IRecipeRegistry.java @@ -13,7 +13,7 @@ /** * The IRecipeManager offers several functions for retrieving and handling recipes. * The IRecipeManager instance is provided in JEIManager. - * Available to IModPlugins + * Get the instance from {@link IJeiRuntime#getRecipeRegistry()}. */ public interface IRecipeRegistry { diff --git a/src/main/java/mezz/jei/api/IRecipesGui.java b/src/main/java/mezz/jei/api/IRecipesGui.java index 5796088b2..1d1b05d2c 100644 --- a/src/main/java/mezz/jei/api/IRecipesGui.java +++ b/src/main/java/mezz/jei/api/IRecipesGui.java @@ -8,6 +8,7 @@ /** * JEI's gui for displaying recipes. Use this interface to open recipes. + * Get the instance from {@link IJeiRuntime#getRecipesGui()}. * * @since JEI 3.2.12 */ diff --git a/src/main/java/mezz/jei/api/ISubtypeRegistry.java b/src/main/java/mezz/jei/api/ISubtypeRegistry.java index d6315afac..5d55bebfa 100644 --- a/src/main/java/mezz/jei/api/ISubtypeRegistry.java +++ b/src/main/java/mezz/jei/api/ISubtypeRegistry.java @@ -14,7 +14,7 @@ * * Replaces {@link INbtIgnoreList}. * - * Get the instance from {@link IJeiHelpers#getSubtypeRegistry()} + * Get the instance from {@link IJeiHelpers#getSubtypeRegistry()}. * * @since 3.6.4 */ diff --git a/src/main/java/mezz/jei/api/JEIPlugin.java b/src/main/java/mezz/jei/api/JEIPlugin.java index 5c08838f9..7dcdc26bb 100644 --- a/src/main/java/mezz/jei/api/JEIPlugin.java +++ b/src/main/java/mezz/jei/api/JEIPlugin.java @@ -2,7 +2,7 @@ /** * This annotation lets JEI detect mod plugins. - * All IModPlugins must have this annotation and a constructor with no arguments. + * All {@link IModPlugin} must have this annotation and a constructor with no arguments. */ public @interface JEIPlugin { } diff --git a/src/main/java/mezz/jei/api/gui/IAdvancedGuiHandler.java b/src/main/java/mezz/jei/api/gui/IAdvancedGuiHandler.java index d8b86e319..9fa6efd5d 100644 --- a/src/main/java/mezz/jei/api/gui/IAdvancedGuiHandler.java +++ b/src/main/java/mezz/jei/api/gui/IAdvancedGuiHandler.java @@ -5,10 +5,12 @@ import java.awt.Rectangle; import java.util.List; +import mezz.jei.api.IModRegistry; import net.minecraft.client.gui.inventory.GuiContainer; /** - * Allows mods to change how JEI is displayed next to their gui. + * Allows plugins to change how JEI is displayed next to their mod's guis. + * Register your implementation with {@link IModRegistry#addAdvancedGuiHandlers(IAdvancedGuiHandler[])}. */ public interface IAdvancedGuiHandler { /** diff --git a/src/main/java/mezz/jei/api/gui/ICraftingGridHelper.java b/src/main/java/mezz/jei/api/gui/ICraftingGridHelper.java index 1ff4a1cfa..78944ab55 100644 --- a/src/main/java/mezz/jei/api/gui/ICraftingGridHelper.java +++ b/src/main/java/mezz/jei/api/gui/ICraftingGridHelper.java @@ -3,11 +3,13 @@ import javax.annotation.Nonnull; import java.util.List; +import mezz.jei.api.IGuiHelper; import net.minecraft.item.ItemStack; /** - * Helps set crafting-grid-style GuiItemStackGroup. - * Get an instance from IGuiHelper. + * Helps set crafting-grid-style {@link IGuiItemStackGroup}. + * This places smaller recipes in the grid in a consistent way. + * Get an instance from {@link IGuiHelper#createCraftingGridHelper(int, int)}. */ public interface ICraftingGridHelper { diff --git a/src/main/java/mezz/jei/api/gui/IDrawable.java b/src/main/java/mezz/jei/api/gui/IDrawable.java index 3e83968a2..5022202d2 100644 --- a/src/main/java/mezz/jei/api/gui/IDrawable.java +++ b/src/main/java/mezz/jei/api/gui/IDrawable.java @@ -2,8 +2,19 @@ import javax.annotation.Nonnull; +import mezz.jei.api.IGuiHelper; +import mezz.jei.api.recipe.IRecipeCategory; +import mezz.jei.api.recipe.IRecipeWrapper; import net.minecraft.client.Minecraft; +/** + * Represents something to be drawn on screen. + * Useful for drawing miscellaneous things in {@link IRecipeCategory#drawExtras(Minecraft)} and {@link IRecipeWrapper#drawInfo(Minecraft, int, int, int, int)}. + * {@link IGuiHelper} has many functions to create IDrawables. + * + * @see IDrawableAnimated + * @see IDrawableStatic + */ public interface IDrawable { int getWidth(); diff --git a/src/main/java/mezz/jei/api/gui/IDrawableAnimated.java b/src/main/java/mezz/jei/api/gui/IDrawableAnimated.java index 7ac9e15c9..a4f0e9d18 100644 --- a/src/main/java/mezz/jei/api/gui/IDrawableAnimated.java +++ b/src/main/java/mezz/jei/api/gui/IDrawableAnimated.java @@ -1,6 +1,22 @@ package mezz.jei.api.gui; +import mezz.jei.api.IGuiHelper; +import mezz.jei.api.recipe.IRecipeCategory; +import mezz.jei.api.recipe.IRecipeWrapper; +import net.minecraft.client.Minecraft; + +/** + * An animated {@link IDrawable}, useful for showing a gui animation like furnace flames or progress arrows. + * Useful for drawing miscellaneous things in {@link IRecipeCategory#drawAnimations(Minecraft)} and {@link IRecipeWrapper#drawAnimations(Minecraft, int, int)}. + * + * To create an instance, use {@link IGuiHelper#createAnimatedDrawable(IDrawableStatic, int, StartDirection, boolean)}. + * Internally, these use an {@link ITickTimer} to simulate tick-driven animations. + */ public interface IDrawableAnimated extends IDrawable { + /** + * The direction that the animation starts from. + * @see IGuiHelper#createAnimatedDrawable(IDrawableStatic, int, StartDirection, boolean) + */ enum StartDirection { TOP, BOTTOM, LEFT, RIGHT } diff --git a/src/main/java/mezz/jei/api/gui/IDrawableStatic.java b/src/main/java/mezz/jei/api/gui/IDrawableStatic.java index 13eae2a6d..5cb2b5126 100644 --- a/src/main/java/mezz/jei/api/gui/IDrawableStatic.java +++ b/src/main/java/mezz/jei/api/gui/IDrawableStatic.java @@ -4,6 +4,9 @@ import net.minecraft.client.Minecraft; +/** + * An extension of {@link IDrawable} that allows masking parts of the image. + */ public interface IDrawableStatic extends IDrawable { /** Draw only part of the image, by masking off parts of it */ void draw(@Nonnull Minecraft minecraft, int xOffset, int yOffset, int maskTop, int maskBottom, int maskLeft, int maskRight); diff --git a/src/main/java/mezz/jei/api/gui/IGuiFluidStackGroup.java b/src/main/java/mezz/jei/api/gui/IGuiFluidStackGroup.java index 5edc3c797..b6e3d0b2e 100644 --- a/src/main/java/mezz/jei/api/gui/IGuiFluidStackGroup.java +++ b/src/main/java/mezz/jei/api/gui/IGuiFluidStackGroup.java @@ -7,9 +7,11 @@ import net.minecraftforge.fluids.FluidStack; /** - * IGuiFluidStackGroup displays FluidStacks in a gui. + * IGuiFluidStackGroup displays one or more {@link FluidStack} in a gui. * * If multiple FluidStacks are set, they will be displayed in rotation. + * + * Get an instance from {@link IRecipeLayout#getFluidStacks()}. */ public interface IGuiFluidStackGroup extends IGuiIngredientGroup { /** diff --git a/src/main/java/mezz/jei/api/gui/IGuiIngredient.java b/src/main/java/mezz/jei/api/gui/IGuiIngredient.java index ddcd87c24..76fff9867 100644 --- a/src/main/java/mezz/jei/api/gui/IGuiIngredient.java +++ b/src/main/java/mezz/jei/api/gui/IGuiIngredient.java @@ -3,19 +3,44 @@ import javax.annotation.Nonnull; import javax.annotation.Nullable; import java.awt.*; +import java.util.Collection; import java.util.List; import mezz.jei.api.recipe.IFocus; +import mezz.jei.api.recipe.transfer.IRecipeTransferHandler; +import mezz.jei.api.recipe.transfer.IRecipeTransferHandlerHelper; import net.minecraft.client.Minecraft; +/** + * Represents one drawn ingredient that is part of a recipe. + * Useful for implementing {@link IRecipeTransferHandler} and some other advanced cases. + * Get these from {@link IGuiIngredientGroup#getGuiIngredients()}. + */ public interface IGuiIngredient { + /** + * The ingredient variation that is shown at this moment. + * For ingredients that rotate through several values, this will change over time. + */ @Nullable IFocus getCurrentlyDisplayed(); + /** + * All ingredient variations that can be shown. + * For ingredients that rotate through several values, this will have them all even if a focus is set. + */ @Nonnull List getAllIngredients(); + /** + * Returns true if this ingredient is an input for the recipe, otherwise it is an output. + */ boolean isInput(); + /** + * Draws a highlight on background of this ingredient. + * This is used by recipe transfer errors to turn missing ingredient backgrounds to red, but can be used for other purposes. + * + * @see IRecipeTransferHandlerHelper#createUserErrorForSlots(String, Collection). + */ void drawHighlight(@Nonnull Minecraft minecraft, Color color, int xOffset, int yOffset); } diff --git a/src/main/java/mezz/jei/api/gui/IGuiIngredientGroup.java b/src/main/java/mezz/jei/api/gui/IGuiIngredientGroup.java index fa06fedbf..0ed2273a2 100644 --- a/src/main/java/mezz/jei/api/gui/IGuiIngredientGroup.java +++ b/src/main/java/mezz/jei/api/gui/IGuiIngredientGroup.java @@ -11,7 +11,10 @@ * * If multiple ingredients are set for one index, they will be displayed in rotation. * - * @see IGuiItemStackGroup and IGuiFluidStackGroup + * Get an instance from {@link IRecipeLayout}. + * + * @see IGuiItemStackGroup + * @see IGuiFluidStackGroup */ public interface IGuiIngredientGroup { /** diff --git a/src/main/java/mezz/jei/api/gui/IGuiItemStackGroup.java b/src/main/java/mezz/jei/api/gui/IGuiItemStackGroup.java index 0d9fada14..3bda4ae4b 100644 --- a/src/main/java/mezz/jei/api/gui/IGuiItemStackGroup.java +++ b/src/main/java/mezz/jei/api/gui/IGuiItemStackGroup.java @@ -11,6 +11,8 @@ * * If multiple ItemStacks are set, they will be displayed in rotation. * ItemStacks with subtypes and wildcard metadata will be displayed as multiple ItemStacks. + * + * Get an instance from {@link IRecipeLayout#getItemStacks()}. */ public interface IGuiItemStackGroup extends IGuiIngredientGroup { diff --git a/src/main/java/mezz/jei/api/gui/IRecipeLayout.java b/src/main/java/mezz/jei/api/gui/IRecipeLayout.java index c729032d0..40d4d8fa2 100644 --- a/src/main/java/mezz/jei/api/gui/IRecipeLayout.java +++ b/src/main/java/mezz/jei/api/gui/IRecipeLayout.java @@ -2,6 +2,14 @@ import javax.annotation.Nonnull; +import mezz.jei.api.recipe.IRecipeCategory; +import mezz.jei.api.recipe.IRecipeWrapper; + +/** + * Represents the layout of one recipe on-screen. + * Plugins interpret a recipe wrapper to set the properties here. + * It is passed to plugins in {@link IRecipeCategory#setRecipe(IRecipeLayout, IRecipeWrapper)}. + */ public interface IRecipeLayout { /** * Contains all the itemStacks displayed on this recipe layout. diff --git a/src/main/java/mezz/jei/api/gui/ITickTimer.java b/src/main/java/mezz/jei/api/gui/ITickTimer.java index 4861851f1..7930fa8f1 100644 --- a/src/main/java/mezz/jei/api/gui/ITickTimer.java +++ b/src/main/java/mezz/jei/api/gui/ITickTimer.java @@ -1,8 +1,11 @@ package mezz.jei.api.gui; +import mezz.jei.api.IGuiHelper; + /** * A timer to help render things that normally depend on ticks. - * Get an instance from the IGuiHelper + * Get an instance from {@link IGuiHelper#createTickTimer(int, int, boolean)}. + * These are used in the internal implementation of {@link IDrawableAnimated}. */ public interface ITickTimer { int getValue(); diff --git a/src/main/java/mezz/jei/api/gui/ITooltipCallback.java b/src/main/java/mezz/jei/api/gui/ITooltipCallback.java index 989f1cfa6..e67e25fe0 100644 --- a/src/main/java/mezz/jei/api/gui/ITooltipCallback.java +++ b/src/main/java/mezz/jei/api/gui/ITooltipCallback.java @@ -2,7 +2,14 @@ import java.util.List; +/** + * Used to add tooltips to ingredients drawn on a recipe. + * Implement a tooltip callback and set it with {@link IGuiIngredientGroup#addTooltipCallback(ITooltipCallback)}. + * Note that this works on anything that implements {@link IGuiIngredientGroup}, like {@link IGuiItemStackGroup} and {@link IGuiFluidStackGroup}. + */ public interface ITooltipCallback { - /** Change the tooltip for an ingredient. */ + /** + * Change the tooltip for an ingredient. + */ void onTooltip(int slotIndex, boolean input, T ingredient, List tooltip); } diff --git a/src/main/java/mezz/jei/api/package-info.java b/src/main/java/mezz/jei/api/package-info.java index 5da816a48..209aac4d5 100644 --- a/src/main/java/mezz/jei/api/package-info.java +++ b/src/main/java/mezz/jei/api/package-info.java @@ -1,4 +1,4 @@ -@API(apiVersion = "4.0.0", owner = "JEI", provides = "JustEnoughItemsAPI") +@API(apiVersion = "4.0.1", owner = "JEI", provides = "JustEnoughItemsAPI") package mezz.jei.api; import net.minecraftforge.fml.common.API; diff --git a/src/main/java/mezz/jei/api/recipe/BlankRecipeCategory.java b/src/main/java/mezz/jei/api/recipe/BlankRecipeCategory.java index 022918a8c..ae94a7589 100644 --- a/src/main/java/mezz/jei/api/recipe/BlankRecipeCategory.java +++ b/src/main/java/mezz/jei/api/recipe/BlankRecipeCategory.java @@ -4,6 +4,9 @@ import javax.annotation.Nonnull; +/** + * An {@link IRecipeCategory} that does nothing, inherit from this to avoid implementing methods you don't need. + */ public abstract class BlankRecipeCategory implements IRecipeCategory { @Override public void drawExtras(@Nonnull Minecraft minecraft) { diff --git a/src/main/java/mezz/jei/api/recipe/BlankRecipeWrapper.java b/src/main/java/mezz/jei/api/recipe/BlankRecipeWrapper.java index 405880ac5..9998ec821 100644 --- a/src/main/java/mezz/jei/api/recipe/BlankRecipeWrapper.java +++ b/src/main/java/mezz/jei/api/recipe/BlankRecipeWrapper.java @@ -8,6 +8,9 @@ import java.util.Collections; import java.util.List; +/** + * An {@link IRecipeWrapper} that does nothing, inherit from this to avoid implementing methods you don't need. + */ public abstract class BlankRecipeWrapper implements IRecipeWrapper { @Override @Nonnull diff --git a/src/main/java/mezz/jei/api/recipe/IFocus.java b/src/main/java/mezz/jei/api/recipe/IFocus.java index 4eb530595..06ad01d0a 100644 --- a/src/main/java/mezz/jei/api/recipe/IFocus.java +++ b/src/main/java/mezz/jei/api/recipe/IFocus.java @@ -3,17 +3,33 @@ import javax.annotation.Nonnull; import javax.annotation.Nullable; +import mezz.jei.api.gui.IGuiIngredient; +import mezz.jei.api.gui.IGuiIngredientGroup; + /** * The current search focus. Set by the player when they look up the recipe. The object being looked up is the focus. + * + * @see IGuiIngredient#getCurrentlyDisplayed() + * @see IGuiIngredientGroup#getFocus() */ public interface IFocus { enum Mode { INPUT, OUTPUT, NONE } + /** + * The object being focused on. + * When the mode is {@link Mode#NONE} there is no focused object, it is null. + */ @Nullable V getValue(); + /** + * The focus mode. + * When a player looks up the recipes to make an item, that item is an {@link Mode#OUTPUT} focus. + * When a player looks up the uses for an item, that item is an {@link Mode#INPUT} focus. + * When the mode is {@link Mode#NONE} there is no focus, the recipe is being browsed as part of a category. + */ @Nonnull Mode getMode(); } diff --git a/src/main/java/mezz/jei/api/recipe/IRecipeCategory.java b/src/main/java/mezz/jei/api/recipe/IRecipeCategory.java index b9a096012..6e71b08fd 100644 --- a/src/main/java/mezz/jei/api/recipe/IRecipeCategory.java +++ b/src/main/java/mezz/jei/api/recipe/IRecipeCategory.java @@ -1,20 +1,28 @@ package mezz.jei.api.recipe; +import mezz.jei.api.IGuiHelper; import mezz.jei.api.gui.IDrawable; +import mezz.jei.api.gui.IDrawableAnimated; import mezz.jei.api.gui.IRecipeLayout; import net.minecraft.client.Minecraft; import javax.annotation.Nonnull; /** - * Defines a category of recipe, (i.e. Crafting Table Recipe, Furnace Recipe) - * and handles setting up the GUI for its recipe category. + * Defines a category of recipe, (i.e. Crafting Table Recipe, Furnace Recipe). + * Handles setting up the GUI for its recipe category in {@link #setRecipe(IRecipeLayout, IRecipeWrapper)}. + * Also draws elements that are common to all recipes in the category like the background. + * + * @see BlankRecipeCategory */ public interface IRecipeCategory { /** * Returns a unique ID for this recipe category. * Referenced from recipes to identify which recipe category they belong to. + * + * @see IRecipeHandler#getRecipeCategoryUid(Object) + * @see VanillaRecipeCategoryUid */ @Nonnull String getUid(); @@ -22,30 +30,33 @@ public interface IRecipeCategory { /** * Returns the localized name for this recipe type. * Drawn at the top of the recipe GUI pages for this category. - * Called every frame, so make sure to store it in a field. */ @Nonnull String getTitle(); /** * Returns the drawable background for a single recipe in this category. - * Called multiple times per frame, so make sure to store it in a field. */ @Nonnull IDrawable getBackground(); /** - * Optionally draw anything else that might be necessary, icons or extra slots. + * Draw any extra elements that might be necessary, icons or extra slots. + * @see IDrawable for a simple class for drawing things. + * @see IGuiHelper for useful functions. */ void drawExtras(@Nonnull Minecraft minecraft); /** - * Optionally draw animations like progress bars. These animations can be disabled in the config. + * Draw any animations like progress bars or flashy effects. + * Essentially the same as {@link #drawExtras(Minecraft)} but these can be disabled in the config. + * @see IDrawableAnimated for a simple class for drawing animated things. + * @see IGuiHelper for useful functions. */ void drawAnimations(@Nonnull Minecraft minecraft); /** - * Set the IRecipeLayout properties from the IRecipeWrapper. + * Set the {@link IRecipeLayout} properties from the {@link IRecipeWrapper}. */ void setRecipe(@Nonnull IRecipeLayout recipeLayout, @Nonnull T recipeWrapper); diff --git a/src/main/java/mezz/jei/api/recipe/IRecipeHandler.java b/src/main/java/mezz/jei/api/recipe/IRecipeHandler.java index 5281d8796..e36e475aa 100644 --- a/src/main/java/mezz/jei/api/recipe/IRecipeHandler.java +++ b/src/main/java/mezz/jei/api/recipe/IRecipeHandler.java @@ -2,12 +2,23 @@ import javax.annotation.Nonnull; +import mezz.jei.api.IModRegistry; +import mezz.jei.api.IRecipeRegistry; + /** * An IRecipeHandler provides information about one Recipe Class. + * + * Its main purpose is to tie recipe classes to an {@link IRecipeCategory} + * and convert recipes to {@link IRecipeWrapper} with {@link #getRecipeWrapper(Object)}. + * + * Plugins implement these to handle their recipes, and register them with {@link IModRegistry#addRecipeHandlers(IRecipeHandler[])}. + * You can find the registered Recipe Handler for a recipe class with {@link IRecipeRegistry#getRecipeHandler(Class)} */ public interface IRecipeHandler { - /** Returns the class of the Recipe handled by this IRecipeHandler. */ + /** + * Returns the class of the Recipe handled by this IRecipeHandler. + */ @Nonnull Class getRecipeClass(); @@ -24,14 +35,21 @@ public interface IRecipeHandler { * Returns this recipe's unique category id. * * @since 3.5.0 + * + * @see IRecipeCategory#getUid() + * @see VanillaRecipeCategoryUid */ @Nonnull String getRecipeCategoryUid(@Nonnull T recipe); - /** Returns a recipe wrapper for the given recipe. */ + /** + * Returns a recipe wrapper for the given recipe. + */ @Nonnull IRecipeWrapper getRecipeWrapper(@Nonnull T recipe); - /** Returns true if a recipe is valid and can be used. */ + /** + * Returns true if a recipe is valid and can be used. + */ boolean isRecipeValid(@Nonnull T recipe); } diff --git a/src/main/java/mezz/jei/api/recipe/IRecipeWrapper.java b/src/main/java/mezz/jei/api/recipe/IRecipeWrapper.java index 101336e15..7f4f62b37 100644 --- a/src/main/java/mezz/jei/api/recipe/IRecipeWrapper.java +++ b/src/main/java/mezz/jei/api/recipe/IRecipeWrapper.java @@ -1,5 +1,8 @@ package mezz.jei.api.recipe; +import mezz.jei.api.IGuiHelper; +import mezz.jei.api.gui.IDrawable; +import mezz.jei.api.gui.IDrawableAnimated; import net.minecraft.client.Minecraft; import net.minecraftforge.fluids.FluidStack; @@ -9,7 +12,11 @@ /** * A wrapper around a normal recipe with methods that allow JEI can make sense of it. - * Implementers will have to create a wrapper for each type of recipe they have. + * Plugins implement these to wrap each type of recipe they have. + * + * Normal recipes are converted to wrapped recipes by {@link IRecipeHandler#getRecipeWrapper(Object)}. + * + * @see BlankRecipeWrapper */ public interface IRecipeWrapper { @@ -25,10 +32,14 @@ public interface IRecipeWrapper { */ List getOutputs(); - /** Return a list of recipe fluid inputs. */ + /** + * Return a list of recipe fluid inputs. + */ List getFluidInputs(); - /** Return a list of recipe fluid outputs. */ + /** + * Return a list of recipe fluid outputs. + */ List getFluidOutputs(); /** @@ -39,10 +50,16 @@ public interface IRecipeWrapper { * @param mouseX the X position of the mouse, relative to the recipe. * @param mouseY the Y position of the mouse, relative to the recipe. * @since JEI 2.19.0 + * @see IDrawable for a simple class for drawing things. + * @see IGuiHelper for useful functions. */ void drawInfo(@Nonnull Minecraft minecraft, int recipeWidth, int recipeHeight, int mouseX, int mouseY); - /** Draw animations involving the recipe. Can be disabled in the config. */ + /** + * Draw animations involving the recipe. Can be disabled in the config. + * @see IDrawableAnimated for a simple class for drawing animated things. + * @see IGuiHelper for useful functions. + */ void drawAnimations(@Nonnull Minecraft minecraft, int recipeWidth, int recipeHeight); /** diff --git a/src/main/java/mezz/jei/api/recipe/IStackHelper.java b/src/main/java/mezz/jei/api/recipe/IStackHelper.java index 760cd6dbb..825c98b75 100644 --- a/src/main/java/mezz/jei/api/recipe/IStackHelper.java +++ b/src/main/java/mezz/jei/api/recipe/IStackHelper.java @@ -4,10 +4,12 @@ import javax.annotation.Nullable; import java.util.List; +import mezz.jei.api.IJeiHelpers; import net.minecraft.item.ItemStack; /** * Helps get ItemStacks from common formats used in recipes. + * Get the instance from {@link IJeiHelpers#getStackHelper()}. */ public interface IStackHelper { /** diff --git a/src/main/java/mezz/jei/api/recipe/VanillaRecipeCategoryUid.java b/src/main/java/mezz/jei/api/recipe/VanillaRecipeCategoryUid.java index 0e24b1401..e107e0416 100644 --- a/src/main/java/mezz/jei/api/recipe/VanillaRecipeCategoryUid.java +++ b/src/main/java/mezz/jei/api/recipe/VanillaRecipeCategoryUid.java @@ -1,17 +1,70 @@ package mezz.jei.api.recipe; +import java.util.List; + +import mezz.jei.api.IItemRegistry; +import mezz.jei.api.IModRegistry; +import mezz.jei.api.recipe.wrapper.ICraftingRecipeWrapper; +import mezz.jei.api.recipe.wrapper.IShapedCraftingRecipeWrapper; +import net.minecraft.item.ItemStack; +import net.minecraft.item.crafting.FurnaceRecipes; +import net.minecraft.item.crafting.ShapedRecipes; +import net.minecraft.item.crafting.ShapelessRecipes; +import net.minecraft.potion.PotionHelper; +import net.minecraft.tileentity.TileEntityFurnace; +import net.minecraftforge.common.brewing.BrewingOreRecipe; +import net.minecraftforge.common.brewing.BrewingRecipe; +import net.minecraftforge.common.brewing.BrewingRecipeRegistry; +import net.minecraftforge.oredict.ShapedOreRecipe; +import net.minecraftforge.oredict.ShapelessOreRecipe; + /** - * List of vanilla recipe category UIDs, so that addons with their own vanilla recipe handlers can use them. + * List of built-in recipe category UIDs, so that plugins with their own recipe handlers can use them. */ public class VanillaRecipeCategoryUid { private VanillaRecipeCategoryUid() { } + /** + * The crafting recipe category. + * + * Automatically includes all {@link ShapedRecipes}, {@link ShapelessRecipes}, {@link ShapedOreRecipe}, and {@link ShapelessOreRecipe}. + * + * To add your recipe wrapper to this category, it must implement either {@link ICraftingRecipeWrapper} or {@link IShapedCraftingRecipeWrapper}. + */ public static final String CRAFTING = "minecraft.crafting"; + + /** + * The smelting recipe category. + * + * Automatically includes everything from {@link FurnaceRecipes#getSmeltingList()}. + */ public static final String SMELTING = "minecraft.smelting"; + + /** + * The fuel recipe category. + * + * Automatically includes everything that returns a value from {@link TileEntityFurnace#getItemBurnTime(ItemStack)}. + */ public static final String FUEL = "minecraft.fuel"; + + /** + * The brewing recipe category. + * + * Automatically tries to generate all potion variations from the basic ingredients, determined by {@link PotionHelper#isReagent(ItemStack)}. + * You can get the list of known potion reagents from {@link IItemRegistry#getPotionIngredients()}. + * + * Also automatically adds modded potions from {@link BrewingRecipeRegistry#getRecipes()}. + * JEI can only understand modded potion recipes that are {@link BrewingRecipe} or {@link BrewingOreRecipe}. + */ public static final String BREWING = "minecraft.brewing"; + /** + * The JEI description recipe category. + * + * This is a built-in category, you can add new recipes with + * {@link IModRegistry#addDescription(ItemStack, String...)} or {@link IModRegistry#addDescription(List, String...)} + */ public static final String DESCRIPTION = "jei.description"; } diff --git a/src/main/java/mezz/jei/api/recipe/transfer/IRecipeTransferError.java b/src/main/java/mezz/jei/api/recipe/transfer/IRecipeTransferError.java index 9ccdc9ea5..d565dc7f3 100644 --- a/src/main/java/mezz/jei/api/recipe/transfer/IRecipeTransferError.java +++ b/src/main/java/mezz/jei/api/recipe/transfer/IRecipeTransferError.java @@ -4,10 +4,14 @@ import mezz.jei.api.gui.IRecipeLayout; import net.minecraft.client.Minecraft; +import net.minecraft.entity.player.EntityPlayer; +import net.minecraft.inventory.Container; /** - * A reason that the recipe transfer couldn't happen. - * See {@link Type#INTERNAL} and {@link Type#USER_FACING}. + * A reason that a recipe transfer couldn't happen. + * + * Recipe transfer errors can be created with {@link IRecipeTransferHandlerHelper} or you can implement your own. + * These errors are returned from {@link IRecipeTransferHandler#transferRecipe(Container, IRecipeLayout, EntityPlayer, boolean, boolean)}. */ public interface IRecipeTransferError { enum Type { @@ -27,6 +31,8 @@ enum Type { @Nonnull Type getType(); - /** Called on USER_FACING errors */ + /** + * Called on {@link Type#USER_FACING} errors. + */ void showError(@Nonnull Minecraft minecraft, int mouseX, int mouseY, @Nonnull IRecipeLayout recipeLayout, int recipeX, int recipeY); } diff --git a/src/main/java/mezz/jei/api/recipe/transfer/IRecipeTransferHandler.java b/src/main/java/mezz/jei/api/recipe/transfer/IRecipeTransferHandler.java index 31442e1f6..b22ea9438 100644 --- a/src/main/java/mezz/jei/api/recipe/transfer/IRecipeTransferHandler.java +++ b/src/main/java/mezz/jei/api/recipe/transfer/IRecipeTransferHandler.java @@ -12,7 +12,9 @@ * A recipe transfer handler moves items into a crafting area, based on the items in a recipe. * * Implementing this interface gives full control over the recipe transfer process. - * Mods that use a regular slotted inventory can use IRecipeTransferInfo instead, which is much simpler. + * Mods that use a regular slotted inventory can use {@link IRecipeTransferInfo} instead, which is much simpler. + * + * Useful functions for implementing a recipe transfer handler can be found in {@link IRecipeTransferHandlerHelper}. */ public interface IRecipeTransferHandler { /** diff --git a/src/main/java/mezz/jei/api/recipe/transfer/IRecipeTransferHandlerHelper.java b/src/main/java/mezz/jei/api/recipe/transfer/IRecipeTransferHandlerHelper.java index fa24b0427..307651779 100644 --- a/src/main/java/mezz/jei/api/recipe/transfer/IRecipeTransferHandlerHelper.java +++ b/src/main/java/mezz/jei/api/recipe/transfer/IRecipeTransferHandlerHelper.java @@ -3,29 +3,34 @@ import javax.annotation.Nonnull; import java.util.Collection; +import mezz.jei.api.IJeiHelpers; +import mezz.jei.api.gui.IGuiItemStackGroup; +import mezz.jei.api.recipe.transfer.IRecipeTransferError.Type; + /** - * Helper functions for implementing an IRecipeTransferHandler + * Helper functions for implementing an {@link IRecipeTransferHandler}. + * Get the instance from {@link IJeiHelpers#recipeTransferHandlerHelper()}. */ public interface IRecipeTransferHandlerHelper { /** - * Create an error with type INTERNAL. + * Create an error with {@link Type#INTERNAL}. * It is recommended that you also log a message to the console. */ IRecipeTransferError createInternalError(); /** - * Create an error with type USER_FACING that shows a tooltip. + * Create an error with type {@link Type#USER_FACING} that shows a tooltip. * * @param tooltipMessage the message to show on the tooltip for the recipe transfer button. */ IRecipeTransferError createUserErrorWithTooltip(@Nonnull String tooltipMessage); /** - * Create an error with type USER_FACING that shows a tooltip and highlights missing item slots. + * Create an error with type {@link Type#USER_FACING} that shows a tooltip and highlights missing item slots. * * @param tooltipMessage the message to show on the tooltip for the recipe transfer button. * @param missingItemSlots the slot indexes for items that are missing. Must not be empty. - * Slots are indexed according to itemStackGroup.getGuiIngredients() + * Slots are indexed according to {@link IGuiItemStackGroup#getGuiIngredients()}. */ IRecipeTransferError createUserErrorForSlots(@Nonnull String tooltipMessage, @Nonnull Collection missingItemSlots); } diff --git a/src/main/java/mezz/jei/api/recipe/transfer/IRecipeTransferInfo.java b/src/main/java/mezz/jei/api/recipe/transfer/IRecipeTransferInfo.java index 0a357bb68..846eae523 100644 --- a/src/main/java/mezz/jei/api/recipe/transfer/IRecipeTransferInfo.java +++ b/src/main/java/mezz/jei/api/recipe/transfer/IRecipeTransferInfo.java @@ -8,13 +8,13 @@ /** * Gives JEI the information it needs to transfer recipes from a slotted inventory into the crafting area. * - * Most plugins should create new IRecipeTransferInfo instances with IModRegistry.createRecipeTransferHelper. + * Most plugins with normal inventories can use the simpler {@link IRecipeTransferRegistry#addRecipeTransferHandler(Class, String, int, int, int, int)}. * Containers with slot ranges that contain gaps or other oddities can implement this interface directly. - * Containers that need full control over the recipe transfer or do not use slots can implement IRecipeTransferHandler. + * Containers that need full control over the recipe transfer or do not use slots can implement {@link IRecipeTransferHandler}. */ public interface IRecipeTransferInfo { /** - * Return the container class that this recipe transfer helper supports + * Return the container class that this recipe transfer helper supports. */ Class getContainerClass(); diff --git a/src/main/java/mezz/jei/api/recipe/transfer/IRecipeTransferRegistry.java b/src/main/java/mezz/jei/api/recipe/transfer/IRecipeTransferRegistry.java index 769df9c69..efcfb2528 100644 --- a/src/main/java/mezz/jei/api/recipe/transfer/IRecipeTransferRegistry.java +++ b/src/main/java/mezz/jei/api/recipe/transfer/IRecipeTransferRegistry.java @@ -2,10 +2,12 @@ import javax.annotation.Nonnull; +import mezz.jei.api.IModRegistry; import net.minecraft.inventory.Container; /** * Register recipe transfer handlers here to give JEI the information it needs to transfer recipes into the crafting area. + * Get the instance from {@link IModRegistry#getRecipeTransferRegistry()}. */ public interface IRecipeTransferRegistry { /** diff --git a/src/main/java/mezz/jei/api/recipe/wrapper/ICraftingRecipeWrapper.java b/src/main/java/mezz/jei/api/recipe/wrapper/ICraftingRecipeWrapper.java index 805877a47..919cd42e5 100644 --- a/src/main/java/mezz/jei/api/recipe/wrapper/ICraftingRecipeWrapper.java +++ b/src/main/java/mezz/jei/api/recipe/wrapper/ICraftingRecipeWrapper.java @@ -1,11 +1,18 @@ package mezz.jei.api.recipe.wrapper; import mezz.jei.api.recipe.IRecipeWrapper; +import mezz.jei.api.recipe.VanillaRecipeCategoryUid; import net.minecraft.item.ItemStack; import javax.annotation.Nonnull; import java.util.List; +/** + * Implement this interface instead of just {@link IRecipeWrapper} to have your recipe wrapper work as part of the + * {@link VanillaRecipeCategoryUid#CRAFTING} recipe category as a shapeless recipe. + * + * For shaped recipes, use {@link IShapedCraftingRecipeWrapper}. + */ public interface ICraftingRecipeWrapper extends IRecipeWrapper { @Nonnull diff --git a/src/main/java/mezz/jei/api/recipe/wrapper/IShapedCraftingRecipeWrapper.java b/src/main/java/mezz/jei/api/recipe/wrapper/IShapedCraftingRecipeWrapper.java index 4cd4f09be..b9c423dd8 100644 --- a/src/main/java/mezz/jei/api/recipe/wrapper/IShapedCraftingRecipeWrapper.java +++ b/src/main/java/mezz/jei/api/recipe/wrapper/IShapedCraftingRecipeWrapper.java @@ -1,5 +1,14 @@ package mezz.jei.api.recipe.wrapper; +import mezz.jei.api.recipe.IRecipeWrapper; +import mezz.jei.api.recipe.VanillaRecipeCategoryUid; + +/** + * Implement this interface instead of just {@link IRecipeWrapper} to have your recipe wrapper work as part of the + * {@link VanillaRecipeCategoryUid#CRAFTING} recipe category as a shaped recipe. + * + * For shapeless recipes, use {@link ICraftingRecipeWrapper}. + */ public interface IShapedCraftingRecipeWrapper extends ICraftingRecipeWrapper { int getWidth();