Improve API documentation

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) {

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 {
 

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);
 }

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 {
 

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<ItemStack> 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<ItemStack> 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<ItemStack> 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<ItemStack> getItemListForModId(@Nonnull String modId);
 }

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 {
 	/**

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();

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);
 

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

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 {
 

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
  */

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
  */

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 {
 }

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<T extends GuiContainer> {
 	/**

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 {
 

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();

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
 	}

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);

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<FluidStack> {
 	/**

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<T> {
+	/**
+	 * The ingredient variation that is shown at this moment.
+	 * For ingredients that rotate through several values, this will change over time.
+	 */
 	@Nullable
 	IFocus<T> 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<T> 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);
 }

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<T> {
 	/**

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<ItemStack> {
 

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.

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();

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<T> {
-	/** Change the tooltip for an ingredient. */
+	/**
+	 * Change the tooltip for an ingredient.
+	 */
 	void onTooltip(int slotIndex, boolean input, T ingredient, List<String> tooltip);
 }

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;