Improve basic docs

9 files changed, 621 insertions, 32 deletions

diff --git a/api/src/main/java/me/shedaniel/rei/api/client/registry/display/DisplayCategory.java b/api/src/main/java/me/shedaniel/rei/api/client/registry/display/DisplayCategory.java
index 2fa319f7b..0e376aa9f 100644
--- a/api/src/main/java/me/shedaniel/rei/api/client/registry/display/DisplayCategory.java
+++ b/api/src/main/java/me/shedaniel/rei/api/client/registry/display/DisplayCategory.java
@@ -46,24 +46,23 @@ import java.util.List;
 @Environment(EnvType.CLIENT)
 public interface DisplayCategory<T extends Display> extends DisplayCategoryView<T>, Identifiable {
     /**
-     * Returns the renderer of the icon.
+     * Returns the renderer of the icon displayed in the category tab.
+     * <p>
+     * A simple implementation is the {@link me.shedaniel.rei.api.common.entry.EntryStack}.
      *
      * @return the renderer of the icon
      */
     Renderer getIcon();
     
     /**
-     * Returns the category title.
+     * Returns the category title for the category.
      *
      * @return the title
      */
     Component getTitle();
     
     /**
-     * Gets the recipe renderer for the category, used in {@link me.shedaniel.rei.impl.client.gui.CompositeRecipeViewingScreen} for rendering simple recipes
-     *
-     * @param display the display to render
-     * @return the display renderer
+     * {@inheritDoc}
      */
     @ApiStatus.OverrideOnly
     @Override
@@ -72,11 +71,7 @@ public interface DisplayCategory<T extends Display> extends DisplayCategoryView<
     }
     
     /**
-     * Setup the widgets for displaying the recipe
-     *
-     * @param display the recipe
-     * @param bounds  the bounds of the display, configurable with overriding the width, height methods.
-     * @return the list of widgets
+     * {@inheritDoc}
      */
     @ApiStatus.OverrideOnly
     @Override
@@ -85,19 +80,19 @@ public interface DisplayCategory<T extends Display> extends DisplayCategoryView<
     }
     
     /**
-     * Gets the recipe display height
+     * Returns the display height, the display height is consistent between all displays in the category.
      *
-     * @return the recipe display height
+     * @return the display height
      */
     default int getDisplayHeight() {
         return 66;
     }
     
     /**
-     * Gets the display width
+     * Returns the display width, the display width can be display-dependent.
      *
-     * @param display the recipe display
-     * @return the recipe display width
+     * @param display the display
+     * @return the display width
      */
     default int getDisplayWidth(T display) {
         return 150;
@@ -115,19 +110,40 @@ public interface DisplayCategory<T extends Display> extends DisplayCategoryView<
     /**
      * Gets the fixed number of displays per page.
      *
-     * @return the number of displays, returns -1 if not fixed
+     * @return the number of displays, or {@code -1} if not fixed
      */
     default int getFixedDisplaysPerPage() {
         return -1;
     }
     
+    /**
+     * Returns the identifier of this {@link DisplayCategory}.
+     * This identifier must be the same one used to register the category
+     * in {@link me.shedaniel.rei.api.client.registry.category.CategoryRegistry}.
+     *
+     * @return the identifier of this category
+     */
     CategoryIdentifier<? extends T> getCategoryIdentifier();
     
+    /**
+     * Returns the display merger for this category.
+     * <p>
+     * A display merger is used to determine whether two displays can be merged together.
+     *
+     * @return the display merger, or {@code null}
+     * @see DisplayCategory#getContentMerger() for a basic merger based on checking the inputs and outputs
+     */
     @Nullable
     default DisplayMerger<T> getDisplayMerger() {
         return null;
     }
     
+    /**
+     * Creates a content merger for this category that is dependent on the inputs and outputs of the displays.
+     *
+     * @param <T> the type of the display
+     * @return the content merger
+     */
     static <T extends Display> DisplayMerger<T> getContentMerger() {
         return new DisplayMerger<T>() {
             @Override
@@ -145,6 +161,9 @@ public interface DisplayCategory<T extends Display> extends DisplayCategoryView<
         };
     }
     
+    /**
+     * {@inheritDoc}
+     */
     @Override
     default ResourceLocation getIdentifier() {
         return getCategoryIdentifier().getIdentifier();
diff --git a/api/src/main/java/me/shedaniel/rei/api/client/registry/display/DisplayCategoryView.java b/api/src/main/java/me/shedaniel/rei/api/client/registry/display/DisplayCategoryView.java
index 38db66c28..435a96569 100644
--- a/api/src/main/java/me/shedaniel/rei/api/client/registry/display/DisplayCategoryView.java
+++ b/api/src/main/java/me/shedaniel/rei/api/client/registry/display/DisplayCategoryView.java
@@ -23,18 +23,30 @@
 
 package me.shedaniel.rei.api.client.registry.display;
 
+import me.shedaniel.math.Point;
 import me.shedaniel.math.Rectangle;
 import me.shedaniel.rei.api.client.gui.DisplayRenderer;
-import me.shedaniel.rei.api.client.gui.widgets.Widget;
+import me.shedaniel.rei.api.client.gui.DrawableConsumer;
+import me.shedaniel.rei.api.client.gui.widgets.*;
 import me.shedaniel.rei.api.common.display.Display;
+import me.shedaniel.rei.api.common.entry.EntryStack;
+import net.minecraft.client.gui.components.events.GuiEventListener;
+import net.minecraft.network.chat.Component;
 import org.jetbrains.annotations.ApiStatus;
 
+import java.util.Collection;
 import java.util.List;
 
+/**
+ * A view that displays a {@link Display}.
+ *
+ * @param <T> the type of display
+ */
 @ApiStatus.Experimental
 public interface DisplayCategoryView<T extends Display> {
     /**
-     * Gets the recipe renderer for the category, used in {@link me.shedaniel.rei.impl.client.gui.CompositeRecipeViewingScreen} for rendering simple recipes
+     * Returns the recipe renderer for the display, used
+     * in {@link me.shedaniel.rei.impl.client.gui.screen.CompositeDisplayViewingScreen} for rendering simple recipes.
      *
      * @param display the display to render
      * @return the display renderer
@@ -43,9 +55,33 @@ public interface DisplayCategoryView<T extends Display> {
     DisplayRenderer getDisplayRenderer(T display);
     
     /**
-     * Setup the widgets for displaying the recipe
+     * Returns the list of widgets for displaying the display.
+     * <p>
+     * For consistency, the widgets list should start with a {@link Widgets#createRecipeBase(Rectangle)} widget.
+     * <p>
+     * Slots may be added with {@link Widgets#createSlot(Point)}, the content of the slot
+     * can be set with either {@link Slot#entry(EntryStack)} or {@link Slot#entries(Collection)}.
+     * <p>
+     * To configure the tooltips of the slots, you may take a look at {@link EntryStack#getTooltip(TooltipContext, boolean)}
+     * for how the tooltip is resolved.
+     * <p>
+     * It is recommended to mark these slots for I/O using {@link Slot#markInput()} and {@link Slot#markOutput()},
+     * and the background of the slots may be disabled using {@link Slot#disableBackground()}.
+     * <p>
+     * Arbitrary text may be added to the widgets list with {@link Widgets#createLabel(Point, Component)},
+     * you may configure the horizontal alignment of the text using {@link Label#centered()},
+     * {@link Label#leftAligned()} and {@link Label#rightAligned()}.<br>
+     * It is recommended to remove the shadow of the label with {@link Label#noShadow()}, and
+     * set the color of the label to {@code 0xFF404040} under light mode and {@code 0xFFBBBBBB} under dark mode,
+     * you may use {@link Label#color(int, int)} for setting the label color depending on the color theme.
+     * <p>
+     * Lastly, {@link Widgets} contains many methods for the most common widgets,
+     * such as adding tooltips, creating texture rectangles, arrows, burning fire, buttons, etc.
+     * <p>
+     * You may use {@link Widgets#createDrawableWidget(DrawableConsumer)} for rendering anything you want, or
+     * wrap vanilla widgets using {@link Widgets#wrapVanillaWidget(GuiEventListener)}.
      *
-     * @param display the recipe
+     * @param display the display
      * @param bounds  the bounds of the display, configurable with overriding the width, height methods.
      * @return the list of widgets
      */
diff --git a/api/src/main/java/me/shedaniel/rei/api/common/display/Display.java b/api/src/main/java/me/shedaniel/rei/api/common/display/Display.java
index bf6dc0cef..e13e3c4e2 100644
--- a/api/src/main/java/me/shedaniel/rei/api/common/display/Display.java
+++ b/api/src/main/java/me/shedaniel/rei/api/common/display/Display.java
@@ -41,13 +41,16 @@ import java.util.Optional;
 
 /**
  * A display, holds ingredients and information for {@link me.shedaniel.rei.api.client.registry.display.DisplayCategory}
- * to setup widgets for.
+ * to set-up widgets for.
  *
  * @see me.shedaniel.rei.api.common.display.basic.BasicDisplay
  * @see me.shedaniel.rei.api.client.registry.display.DisplayRegistry
  */
 public interface Display extends DisplaySpec {
     /**
+     * Returns the list of inputs for this display. This only affects the stacks resolving for the display,
+     * and not necessarily the stacks that are displayed.
+     *
      * @return a list of inputs
      */
     List<EntryIngredient> getInputEntries();
@@ -57,26 +60,37 @@ public interface Display extends DisplaySpec {
         return getInputEntries();
     }
     
+    /**
+     * Returns the list of inputs for this display, aligned for the menu. This only affects the stacks resolving for the display,
+     * and not necessarily the stacks that are displayed.
+     * <p>
+     * Each ingredient is also provided with the corresponding index slot-wise. The order of the list does not matter.
+     *
+     * @return a list of inputs
+     */
     default List<InputIngredient<EntryStack<?>>> getInputIngredients(MenuSerializationContext<?, ?, ?> context, MenuInfo<?, ?> info, boolean fill) {
         return CollectionUtils.mapIndexed(getInputEntries(context, info, fill), InputIngredient::of);
     }
     
     /**
+     * Returns the list of outputs for this display. This only affects the stacks resolving for the display,
+     * and not necessarily the stacks that are displayed.
+     *
      * @return a list of outputs
      */
     List<EntryIngredient> getOutputEntries();
     
     /**
-     * Gets the required items used in craftable filters
+     * Returns the list of required inputs for this display. This only affects the craftable filter.
      *
-     * @return the list of required items
+     * @return a list of required inputs
      */
     default List<EntryIngredient> getRequiredEntries() {
         return getInputEntries();
     }
     
     /**
-     * Gets the display display category identifier
+     * Returns the identifier of the category this display belongs to.
      *
      * @return the identifier of the category
      */
diff --git a/api/src/main/java/me/shedaniel/rei/api/common/entry/EntryIngredient.java b/api/src/main/java/me/shedaniel/rei/api/common/entry/EntryIngredient.java
index efdc401df..6e7862a55 100644
--- a/api/src/main/java/me/shedaniel/rei/api/common/entry/EntryIngredient.java
+++ b/api/src/main/java/me/shedaniel/rei/api/common/entry/EntryIngredient.java
@@ -23,6 +23,7 @@
 
 package me.shedaniel.rei.api.common.entry;
 
+import me.shedaniel.rei.api.common.entry.type.EntryDefinition;
 import me.shedaniel.rei.impl.Internals;
 import net.minecraft.nbt.CompoundTag;
 import net.minecraft.nbt.ListTag;
@@ -38,32 +39,79 @@ import java.util.stream.Collectors;
  * An immutable representation of a list of {@link EntryStack}.
  */
 public interface EntryIngredient extends List<EntryStack<?>> {
+    /**
+     * Returns an empty entry ingredient. This is the singleton instance of {@link EntryIngredient} that is
+     * built-in to the implementation.
+     *
+     * @return the empty entry ingredient
+     */
     static EntryIngredient empty() {
         return Internals.getEntryIngredientProvider().empty();
     }
     
+    /**
+     * Creates a singleton {@link EntryIngredient} from the given {@link EntryStack}.
+     *
+     * @param stack the stack to create the {@link EntryIngredient} from
+     * @param <T>   the type of entry
+     * @return the singleton {@link EntryIngredient}
+     */
     static <T> EntryIngredient of(EntryStack<T> stack) {
         return Internals.getEntryIngredientProvider().of(stack);
     }
     
+    /**
+     * Creates a list-backed {@link EntryIngredient} from the given array of {@link EntryStack}.
+     *
+     * @param stacks the stacks to create the {@link EntryIngredient} from
+     * @param <T>    the type of entry
+     * @return the list-backed {@link EntryIngredient}
+     */
     @SafeVarargs
     static <T> EntryIngredient of(EntryStack<T>... stacks) {
         return Internals.getEntryIngredientProvider().of(stacks);
     }
     
+    /**
+     * Creates a list-backed {@link EntryIngredient} from the given list of {@link EntryStack}.
+     *
+     * @param stacks the stacks to create the {@link EntryIngredient} from
+     * @param <T>    the type of entry
+     * @return the list-backed {@link EntryIngredient}
+     */
     @SuppressWarnings({"RedundantCast", "rawtypes"})
     static <T> EntryIngredient of(Iterable<? extends EntryStack<? extends T>> stacks) {
         return Internals.getEntryIngredientProvider().of((Iterable<EntryStack<?>>) (Iterable) stacks);
     }
     
+    /**
+     * Creates a builder for {@link EntryIngredient}.
+     *
+     * @return the builder
+     */
     static Builder builder() {
         return Internals.getEntryIngredientProvider().builder();
     }
     
+    /**
+     * Creates a builder for {@link EntryIngredient} with the given initial capacity.
+     *
+     * @param initialCapacity the initial capacity
+     * @return the builder
+     */
     static Builder builder(int initialCapacity) {
         return Internals.getEntryIngredientProvider().builder(initialCapacity);
     }
     
+    /**
+     * Reads an {@link EntryIngredient} from the given {@link ListTag}.
+     *
+     * @param tag the tag
+     * @return the read {@link EntryIngredient}
+     * @throws NullPointerException          if an {@link EntryDefinition} is not found
+     * @throws UnsupportedOperationException if an {@link EntryDefinition} does not support reading from a tag
+     * @see EntryStack#read(CompoundTag)
+     */
     static EntryIngredient read(ListTag tag) {
         if (tag.isEmpty()) return empty();
         EntryStack<?>[] stacks = new EntryStack[tag.size()];
@@ -77,15 +125,53 @@ public interface EntryIngredient extends List<EntryStack<?>> {
         return Collectors.collectingAndThen(Collectors.toList(), EntryIngredient::of);
     }
     
+    /**
+     * Saves the entry ingredient to a {@link ListTag}. This is only supported if every entry stack has a serializer.
+     *
+     * @return the saved tag
+     * @throws UnsupportedOperationException if an {@link EntryDefinition} does not support saving to a tag
+     * @see EntrySerializer#supportSaving()
+     * @see EntryStack#saveStack()
+     */
     ListTag save();
     
-    @SuppressWarnings("rawtypes")
+    /**
+     * Casts this {@link EntryStack} to a list of {@link EntryStack} of the given type.
+     *
+     * @param <T> the type of entry
+     * @return the casted list of {@link EntryStack}
+     * @deprecated use {@link #castAsList()} instead
+     */
+    @Deprecated(forRemoval = true)
     default <T> List<EntryStack<T>> cast() {
+        return castAsList();
+    }
+    
+    /**
+     * Casts this {@link EntryStack} to a list of {@link EntryStack} of the given type.
+     *
+     * @param <T> the type of entry
+     * @return the casted list of {@link EntryStack}
+     */
+    @SuppressWarnings("rawtypes")
+    default <T> List<EntryStack<T>> castAsList() {
         return (List<EntryStack<T>>) (List) this;
     }
     
+    /**
+     * Filters this {@link EntryIngredient} to only contain {@link EntryStack} that match the given {@link Predicate}.
+     *
+     * @param filter the filter
+     * @return the filtered {@link EntryIngredient}
+     */
     EntryIngredient filter(Predicate<EntryStack<?>> filter);
     
+    /**
+     * Transforms values of this {@link EntryIngredient} by applying the given {@link UnaryOperator}.
+     *
+     * @param transformer the transformer
+     * @return the transformed {@link EntryIngredient}
+     */
     EntryIngredient map(UnaryOperator<EntryStack<?>> transformer);
     
     @ApiStatus.NonExtendable
diff --git a/api/src/main/java/me/shedaniel/rei/api/common/entry/EntrySerializer.java b/api/src/main/java/me/shedaniel/rei/api/common/entry/EntrySerializer.java
index 4388cbe06..780dd3ce5 100644
--- a/api/src/main/java/me/shedaniel/rei/api/common/entry/EntrySerializer.java
+++ b/api/src/main/java/me/shedaniel/rei/api/common/entry/EntrySerializer.java
@@ -31,11 +31,34 @@ import net.minecraft.nbt.CompoundTag;
  * @param <T> the type of object to serialize
  */
 public interface EntrySerializer<T> {
+    /**
+     * Whether this serializer supports saving.
+     *
+     * @return whether this serializer supports saving
+     */
     boolean supportSaving();
     
+    /**
+     * Whether this serializer supports reading.
+     *
+     * @return whether this serializer supports reading
+     */
     boolean supportReading();
     
+    /**
+     * Serializes the given object into a {@link CompoundTag}.
+     *
+     * @param entry the entry stack
+     * @param value the value to serialize
+     * @return the serialized tag
+     */
     CompoundTag save(EntryStack<T> entry, T value);
     
+    /**
+     * Deserializes the given tag into an object.
+     *
+     * @param tag the tag to deserialize
+     * @return the deserialized object
+     */
     T read(CompoundTag tag);
 }
diff --git a/api/src/main/java/me/shedaniel/rei/api/common/entry/EntryStack.java b/api/src/main/java/me/shedaniel/rei/api/common/entry/EntryStack.java
index 5119140aa..bdc47362b 100644
--- a/api/src/main/java/me/shedaniel/rei/api/common/entry/EntryStack.java
+++ b/api/src/main/java/me/shedaniel/rei/api/common/entry/EntryStack.java
@@ -32,6 +32,7 @@ import me.shedaniel.rei.api.client.entry.renderer.EntryRendererRegistry;
 import me.shedaniel.rei.api.client.gui.Renderer;
 import me.shedaniel.rei.api.client.gui.widgets.Tooltip;
 import me.shedaniel.rei.api.client.gui.widgets.TooltipContext;
+import me.shedaniel.rei.api.common.entry.comparison.ComparisonContext;
 import me.shedaniel.rei.api.common.entry.type.EntryDefinition;
 import me.shedaniel.rei.api.common.entry.type.EntryType;
 import me.shedaniel.rei.api.common.entry.type.EntryTypeRegistry;
@@ -40,6 +41,7 @@ import me.shedaniel.rei.impl.Internals;
 import net.fabricmc.api.EnvType;
 import net.fabricmc.api.Environment;
 import net.minecraft.nbt.CompoundTag;
+import net.minecraft.nbt.ListTag;
 import net.minecraft.network.chat.Component;
 import net.minecraft.resources.ResourceLocation;
 import net.minecraft.tags.TagKey;
@@ -54,22 +56,77 @@ import java.util.function.Function;
 import java.util.stream.Stream;
 
 /**
- * @see me.shedaniel.rei.api.common.util.EntryStacks
+ * A basic entry stack. An entry stack is a pair of an {@link EntryDefinition} and a {@link T}.
+ * <p>
+ * Settings may be applied to the entry stack.
+ * You may want to use {@link me.shedaniel.rei.api.client.util.ClientEntryStacks} for applying
+ * rendering specific settings.
+ *
+ * @param <T> the type of entry
+ * @see EntryStack#empty() for getting the singleton empty entry stack
+ * @see me.shedaniel.rei.api.common.util.EntryStacks for creating entry stacks from vanilla items and fluids
+ * @see me.shedaniel.rei.api.client.util.ClientEntryStacks for creating entry stacks from renderers
  */
 @ApiStatus.NonExtendable
 public interface EntryStack<T> extends TextRepresentable, Renderer {
+    /**
+     * Returns an empty entry stack. This is the singleton instance of {@link EntryStack} that is
+     * built-in to the implementation.
+     * <p>
+     * The entry stack has a type of {@link me.shedaniel.rei.api.common.entry.type.BuiltinEntryTypes#EMPTY}.
+     *
+     * @return the empty entry stack
+     */
     static EntryStack<Unit> empty() {
         return Internals.getEntryStackProvider().empty();
     }
     
+    /**
+     * Creates an {@link EntryStack} from the given {@link EntryDefinition} and {@link T}.
+     * <p>
+     * Whether {@param value} accepts {@code null} depends on {@link EntryDefinition#acceptsNull()}.
+     *
+     * @param definition the entry definition
+     * @param value      the value
+     * @param <T>        the type of entry
+     * @return the entry stack
+     */
     static <T> EntryStack<T> of(EntryDefinition<T> definition, T value) {
         return Internals.getEntryStackProvider().of(definition, value);
     }
     
+    /**
+     * Creates an {@link EntryStack} from the given {@link EntryType} and {@link T}.
+     * <p>
+     * The {@link EntryDefinition} deferred from the type <b>must</b> be registered,
+     * this method is not deferred.
+     * <p>
+     * Whether {@param value} accepts {@code null} depends on {@link EntryDefinition#acceptsNull()}.
+     *
+     * @param type  the entry type
+     * @param value the value
+     * @param <T>   the type of entry
+     * @return the entry stack
+     * @throws NullPointerException     if the {@link EntryDefinition} is not found
+     * @throws IllegalArgumentException if the {@link EntryDefinition} does not accept {@code null}, and {@code value} is {@code null}
+     */
     static <T> EntryStack<T> of(EntryType<T> type, T value) {
         return of(type.getDefinition(), value);
     }
     
+    /**
+     * Reads an {@link EntryStack} from the given {@link CompoundTag}.
+     * <p>
+     * The compound tag must contain "type" for resolving the {@link EntryDefinition} for
+     * the {@link EntryStack}.
+     *
+     * @param tag the tag
+     * @return the entry stack
+     * @throws NullPointerException          if the {@link EntryDefinition} is not found
+     * @throws UnsupportedOperationException if the {@link EntryDefinition} does not support reading from a tag
+     * @see EntrySerializer#supportReading()
+     * @see EntryIngredient#read(ListTag)
+     */
     static EntryStack<?> read(CompoundTag tag) {
         ResourceLocation type = new ResourceLocation(tag.getString("type"));
         EntryDefinition<?> definition = EntryTypeRegistry.getInstance().get(type);
@@ -81,7 +138,30 @@ public interface EntryStack<T> extends TextRepresentable, Renderer {
         throw new UnsupportedOperationException(definition.getType().getId() + " does not support deserialization!");
     }
     
+    /**
+     * Saves the entry stack to a {@link CompoundTag}. This is only supported if the entry stack has a serializer.
+     *
+     * @return the saved tag
+     * @throws UnsupportedOperationException if the {@link EntryDefinition} does not support saving to a tag
+     * @see EntrySerializer#supportSaving()
+     * @see EntryIngredient#save()
+     */
+    @Nullable
+    default CompoundTag saveStack() {
+        return save();
+    }
+    
+    /**
+     * Saves the entry stack to a {@link CompoundTag}. This is only supported if the entry stack has a serializer.
+     *
+     * @return the saved tag
+     * @throws UnsupportedOperationException if the {@link EntryDefinition} does not support saving to a tag
+     * @see EntrySerializer#supportSaving()
+     * @see EntryIngredient#save()
+     * @deprecated use {@link #saveStack()} instead
+     */
     @Nullable
+    @Deprecated(forRemoval = true)
     default CompoundTag save() {
         if (supportSaving()) {
             CompoundTag tag = getDefinition().getSerializer().save(this, getValue());
@@ -91,59 +171,179 @@ public interface EntryStack<T> extends TextRepresentable, Renderer {
         throw new UnsupportedOperationException(getType().getId() + " does not support serialization!");
     }
     
+    /**
+     * Returns whether the {@link EntryDefinition} of this {@link EntryStack} supports saving to a tag.
+     *
+     * @return whether the {@link EntryDefinition} of this {@link EntryStack} supports saving to a tag
+     */
     default boolean supportSaving() {
         EntrySerializer<T> serializer = getDefinition().getSerializer();
         return serializer != null && serializer.supportSaving();
     }
     
+    /**
+     * Returns the tooltip for this {@link EntryStack}, can be {@code null}.
+     * <p>
+     * The base implementation depends on {@link EntryRenderer#getTooltip(EntryStack, TooltipContext)},
+     * see {@link EntryStack#getRenderer()} to see how the renderer is resolved.
+     * <p>
+     * It is possible to process the base tooltip at a per {@link EntryType} level
+     * using {@link EntryRendererRegistry#transformTooltip(EntryType, EntryRendererRegistry.TooltipTransformer)}.
+     * <p>
+     * This tooltip can be appended by {@link EntryStack#tooltip(Component...)},
+     * and further processed by {@link me.shedaniel.rei.api.client.util.ClientEntryStacks#setTooltipProcessor(EntryStack, BiFunction)}.
+     *
+     * @param mouse         the mouse position
+     * @param appendModName whether to append the mod name
+     * @return the tooltip, can be {@code null}
+     * @deprecated use {@link #getTooltip(TooltipContext, boolean)} instead
+     */
     @Nullable
     @Environment(EnvType.CLIENT)
+    @Deprecated(forRemoval = true)
     default Tooltip getTooltip(Point mouse, boolean appendModName) {
         return getTooltip(TooltipContext.of(mouse), appendModName);
     }
     
+    /**
+     * Returns the tooltip for this {@link EntryStack}, can be {@code null}.
+     * <p>
+     * The base implementation depends on {@link EntryRenderer#getTooltip(EntryStack, TooltipContext)},
+     * see {@link EntryStack#getRenderer()} to see how the renderer is resolved.
+     * <p>
+     * It is possible to process the base tooltip at a per {@link EntryType} level
+     * using {@link EntryRendererRegistry#transformTooltip(EntryType, EntryRendererRegistry.TooltipTransformer)}.
+     * <p>
+     * This tooltip can be appended by {@link EntryStack#tooltip(Component...)},
+     * and further processed by {@link me.shedaniel.rei.api.client.util.ClientEntryStacks#setTooltipProcessor(EntryStack, BiFunction)}.
+     *
+     * @param context       the tooltip context
+     * @param appendModName whether to append the mod name
+     * @return the tooltip, can be {@code null}
+     */
     @Nullable
     @Environment(EnvType.CLIENT)
     Tooltip getTooltip(TooltipContext context, boolean appendModName);
     
+    /**
+     * Returns the tooltip for this {@link EntryStack}, can be {@code null}.
+     * <p>
+     * The base implementation depends on {@link EntryRenderer#getTooltip(EntryStack, TooltipContext)},
+     * see {@link EntryStack#getRenderer()} to see how the renderer is resolved.
+     * <p>
+     * It is possible to process the base tooltip at a per {@link EntryType} level
+     * using {@link EntryRendererRegistry#transformTooltip(EntryType, EntryRendererRegistry.TooltipTransformer)}.
+     * <p>
+     * This tooltip can be appended by {@link EntryStack#tooltip(Component...)},
+     * and further processed by {@link me.shedaniel.rei.api.client.util.ClientEntryStacks#setTooltipProcessor(EntryStack, BiFunction)}.
+     *
+     * @param mouse the mouse position
+     * @return the tooltip, can be {@code null}
+     * @deprecated use {@link #getTooltip(TooltipContext)} instead
+     */
     @Override
     @Nullable
     default Tooltip getTooltip(Point mouse) {
         return getTooltip(mouse, ConfigObject.getInstance().shouldAppendModNames());
     }
     
+    /**
+     * Returns the tooltip for this {@link EntryStack}, can be {@code null}.
+     * <p>
+     * The base implementation depends on {@link EntryRenderer#getTooltip(EntryStack, TooltipContext)},
+     * see {@link EntryStack#getRenderer()} to see how the renderer is resolved.
+     * <p>
+     * It is possible to process the base tooltip at a per {@link EntryType} level
+     * using {@link EntryRendererRegistry#transformTooltip(EntryType, EntryRendererRegistry.TooltipTransformer)}.
+     * <p>
+     * This tooltip can be appended by {@link EntryStack#tooltip(Component...)},
+     * and further processed by {@link me.shedaniel.rei.api.client.util.ClientEntryStacks#setTooltipProcessor(EntryStack, BiFunction)}.
+     *
+     * @param context the tooltip context
+     * @return the tooltip, can be {@code null}
+     */
     @Override
     @Nullable
     default Tooltip getTooltip(TooltipContext context) {
         return getTooltip(context, ConfigObject.getInstance().shouldAppendModNames());
     }
     
+    /**
+     * Returns the {@link EntryDefinition} of this {@link EntryStack}.
+     *
+     * @return the {@link EntryDefinition} of this {@link EntryStack}
+     */
     EntryDefinition<T> getDefinition();
     
+    /**
+     * Returns the {@link EntryType} of this {@link EntryStack}.
+     *
+     * @return the {@link EntryType} of this {@link EntryStack}
+     */
     default EntryType<T> getType() {
         return getDefinition().getType();
     }
     
+    /**
+     * Returns the base {@link Class} type from the {@link EntryType} of this {@link EntryStack}.
+     *
+     * @return the base {@link Class} type
+     */
     default Class<T> getValueType() {
         return getDefinition().getValueType();
     }
     
+    /**
+     * Returns the {@link EntryRenderer} of this {@link EntryStack}.
+     * <p>
+     * The base implementation is at {@link EntryDefinition#getRenderer()},
+     * then is processed by {@link EntryRendererRegistry}.
+     * <p>
+     * To modify the renderer at a per stack level,
+     * use {@link me.shedaniel.rei.api.client.util.ClientEntryStacks#setRenderer(EntryStack, EntryRenderer)}.
+     *
+     * @return the {@link EntryRenderer} of this {@link EntryStack}
+     */
     @Environment(EnvType.CLIENT)
     default EntryRenderer<T> getRenderer() {
         EntryRenderer<?> renderer = get(Settings.RENDERER).apply(this);
         return renderer == null ? EntryRenderer.empty() : renderer.cast();
     }
     
+    /**
+     * Returns the identifier for this {@link EntryStack}, used in identifier search argument type.
+     *
+     * @return the identifier for this {@link EntryStack}, can be {@code null}
+     * @see EntryDefinition#getIdentifier(EntryStack, Object)
+     */
     @Nullable
     ResourceLocation getIdentifier();
     
+    /**
+     * Returns the container namespace of this {@link EntryStack}, used for determining the
+     * responsible mod for the entry.
+     * <p>
+     * It is possible to modify this at a per {@link EntryStack} level using {@link Settings#CONTAINING_NS},
+     * however it isn't recommended to do so.
+     *
+     * @return the container namespace for this {@link EntryStack}, can be {@code null}
+     * @see EntryDefinition#getContainingNamespace(EntryStack, Object)
+     */
     @Nullable
     String getContainingNamespace();
     
+    /**
+     * Returns whether this {@link EntryStack} is empty, empty entries are not displayed,
+     * and are considered invalid.
+     * Empty entries will be treated equally to {@link EntryStack#empty()}.
+     *
+     * @return whether this {@link EntryStack} is empty
+     * @see EntryDefinition#isEmpty(EntryStack, Object)
+     */
     boolean isEmpty();
     
     /**
-     * Returns a copy of this stack.
+