docs: new api

shared/src/main/java/net/blay09/mods/cookingforblockheads/api/IngredientToken.java

@@ -2,9 +2,27 @@
 
 import net.minecraft.world.item.ItemStack;
 
+/**
+ * Ingredient tokens are references towards ingredients to be used in a crafting operation.
+ * <p>
+ * You should return a custom implementation of this interface with properties specific to your context, i.e. a slot index or similar.
+ */
 public interface IngredientToken {
+    /**
+     * @return the item stack referenced by this token, but without removing it from its source
+     */
     ItemStack peek();
+
+    /**
+     * @return the item stack referenced by this token, consuming it from its source. Remember to use a substack or return copy if you're going to shrink() the source.
+     */
     ItemStack consume();
+
+    /**
+     * This is both used for failed operations (e.g. oven already full), as well as returning remaining items of operations.
+     * @param itemStack the item to be returned to the source inventory
+     * @return the rest that could not be returned to the source inventory, or ItemStack.EMPTY if all was returned
+     */
     ItemStack restore(ItemStack itemStack);
 
     IngredientToken EMPTY = new IngredientToken() {

shared/src/main/java/net/blay09/mods/cookingforblockheads/api/KitchenItemProcessor.java

@@ -5,6 +5,11 @@
 
 import java.util.List;
 
+/**
+ * Item processors are able to define custom logic for processing recipes.
+ * <p>
+ * This is used by the oven for example, in order to allow smelting recipes to be moved to the oven when crafted.
+ */
 public interface KitchenItemProcessor {
     boolean canProcess(RecipeType<?> recipeType);
 

shared/src/main/java/net/blay09/mods/cookingforblockheads/api/KitchenItemProvider.java

@@ -5,8 +5,27 @@
 
 import java.util.Collection;
 
+/**
+ * Item Providers are responsible for locating and supplying ingredients to recipes.
+ * <p>
+ * If your block is a simple storage container providing either a Container or ItemHandler,
+ * you can tag it <code>cookingforblockheads:kitchen_item_providers</code> to have it automatically
+ * use the default implementation.
+ * <p>
+ * This interface is specifically for cases where you want to provide custom logic for locating ingredients.
+ */
 public interface KitchenItemProvider {
+    /**
+     * @param ingredient the ingredient to find
+     * @param ingredientTokens the ingredient tokens that have already been provided by this provider
+     * @return an ingredient token that matches the given ingredient, or null if none was found
+     */
     IngredientToken findIngredient(Ingredient ingredient, Collection<IngredientToken> ingredientTokens);
 
+    /**
+     * @param itemStack the item to find
+     * @param ingredientTokens the ingredient tokens that have already been provided by this provider
+     * @return an ingredient token that matches the given ingredient, or null if none was found
+     */
     IngredientToken findIngredient(ItemStack itemStack, Collection<IngredientToken> ingredientTokens);
 }

shared/src/main/java/net/blay09/mods/cookingforblockheads/api/KitchenOperation.java

@@ -1,5 +1,8 @@
 package net.blay09.mods.cookingforblockheads.api;
 
+/**
+ * Not currently used for anything, feel free to just use EMPTY.
+ */
 public interface KitchenOperation {
     KitchenOperation EMPTY = new KitchenOperation() {
     };