From bb84852c0f00013c35189c72e35985cbcb461c50 Mon Sep 17 00:00:00 2001
From: shedaniel <daniel@shedaniel.me>
Date: Mon, 20 Jun 2022 23:01:46 +0800
Subject: Some JDocs for EntryComparator

---
 .../common/entry/comparison/EntryComparator.java   | 30 +++++++++++++++++++
 .../entry/comparison/EntryComparatorRegistry.java  | 35 ++++++++++++++++++++++
 .../entry/comparison/FluidComparatorRegistry.java  | 10 +++++++
 .../entry/comparison/ItemComparatorRegistry.java   | 10 +++++++
 .../shedaniel/rei/api/common/util/EntryStacks.java |  6 ++--
 5 files changed, 88 insertions(+), 3 deletions(-)

diff --git a/api/src/main/java/me/shedaniel/rei/api/common/entry/comparison/EntryComparator.java b/api/src/main/java/me/shedaniel/rei/api/common/entry/comparison/EntryComparator.java
index 0e20166fe..e24d41327 100644
--- a/api/src/main/java/me/shedaniel/rei/api/common/entry/comparison/EntryComparator.java
+++ b/api/src/main/java/me/shedaniel/rei/api/common/entry/comparison/EntryComparator.java
@@ -36,10 +36,21 @@ import java.util.Objects;
  */
 @FunctionalInterface
 public interface EntryComparator<T> {
+    /**
+     * Creates an {@link EntryComparator} that does not compare anything.
+     *
+     * @param <T> the type of the entry
+     * @return an {@link EntryComparator} that does not compare anything
+     */
     static <T> EntryComparator<T> noop() {
         return (context, stack) -> 1;
     }
     
+    /**
+     * Creates an {@link EntryComparator} that compares the {@link ItemStack}'s NBT.
+     *
+     * @return an {@link EntryComparator} that compares the {@link ItemStack}'s NBT
+     */
     static EntryComparator<ItemStack> itemNbt() {
         EntryComparator<Tag> nbtHasher = nbt("Count");
         return (context, stack) -> {
@@ -48,6 +59,11 @@ public interface EntryComparator<T> {
         };
     }
     
+    /**
+     * Creates an {@link EntryComparator} that compares the {@link FluidStack}'s NBT.
+     *
+     * @return an {@link EntryComparator} that compares the {@link FluidStack}'s NBT
+     */
     static EntryComparator<FluidStack> fluidNbt() {
         EntryComparator<Tag> nbtHasher = nbt("Amount");
         return (context, stack) -> {
@@ -56,10 +72,24 @@ public interface EntryComparator<T> {
         };
     }
     
+    /**
+     * Creates an {@link EntryComparator} that compares the nbt, but
+     * ignoring some given keys.
+     *
+     * @param ignoredKeys the keys to ignore
+     * @return an {@link EntryComparator} that compares the nbt
+     */
     static EntryComparator<Tag> nbt(String... ignoredKeys) {
         return Internals.getNbtHasher(ignoredKeys);
     }
     
+    /**
+     * Returns hash code of the {@link T} stack.
+     *
+     * @param context the context to use
+     * @param stack   the stack to hash code
+     * @return the hash code of the {@code context} context
+     */
     long hash(ComparisonContext context, T stack);
     
     default EntryComparator<T> onlyExact() {
diff --git a/api/src/main/java/me/shedaniel/rei/api/common/entry/comparison/EntryComparatorRegistry.java b/api/src/main/java/me/shedaniel/rei/api/common/entry/comparison/EntryComparatorRegistry.java
index 777ba34e6..f27b192e8 100644
--- a/api/src/main/java/me/shedaniel/rei/api/common/entry/comparison/EntryComparatorRegistry.java
+++ b/api/src/main/java/me/shedaniel/rei/api/common/entry/comparison/EntryComparatorRegistry.java
@@ -32,19 +32,54 @@ import me.shedaniel.rei.api.common.registry.Reloadable;
  * and nbt when exact.
  */
 public interface EntryComparatorRegistry<T, S> extends Reloadable<REIPlugin<?>> {
+    /**
+     * Registers an {@link EntryComparator} for the given entry {@link S}.
+     *
+     * @param comparator the comparator to register
+     * @param entry      the entry to register the comparator for
+     */
     void register(EntryComparator<T> comparator, S entry);
     
+    /**
+     * Registers an {@link EntryComparator} for the given entries {@link S}.
+     *
+     * @param comparator the comparator to register
+     * @param entries    the entries to register the comparator for
+     */
     default void register(EntryComparator<T> comparator, S... entries) {
         for (S entry : entries) {
             register(comparator, entry);
         }
     }
     
+    /**
+     * Registers an {@link EntryComparator} globally for all entries {@link S}.
+     *
+     * @param comparator the comparator to register
+     */
     void registerGlobal(EntryComparator<T> comparator);
     
+    /**
+     * Returns hash code of the {@link T} stack.
+     *
+     * @param context the context to use
+     * @param stack   the stack to hash code
+     * @return the hash code of the {@code context} context
+     */
     long hashOf(ComparisonContext context, T stack);
     
+    /**
+     * Returns whether there are any comparators registered for the {@link S} entry.
+     *
+     * @param entry the entry to check
+     * @return whether there are any comparators registered for the {@code entry} entry
+     */
     boolean containsComparator(S entry);
     
+    /**
+     * Returns the number of registered comparators for this registry.
+     *
+     * @return the number of registered comparators for this registry
+     */
     int comparatorSize();
 }
diff --git a/api/src/main/java/me/shedaniel/rei/api/common/entry/comparison/FluidComparatorRegistry.java b/api/src/main/java/me/shedaniel/rei/api/common/entry/comparison/FluidComparatorRegistry.java
index 387502002..f74c2380e 100644
--- a/api/src/main/java/me/shedaniel/rei/api/common/entry/comparison/FluidComparatorRegistry.java
+++ b/api/src/main/java/me/shedaniel/rei/api/common/entry/comparison/FluidComparatorRegistry.java
@@ -40,10 +40,20 @@ public interface FluidComparatorRegistry extends EntryComparatorRegistry<FluidSt
         return PluginManager.getInstance().get(FluidComparatorRegistry.class);
     }
     
+    /**
+     * Registers a fluid to compare via its nbt.
+     *
+     * @param fluid the fluid to compare
+     */
     default void registerNbt(Fluid fluid) {
         register(EntryComparator.fluidNbt(), fluid);
     }
     
+    /**
+     * Registers fluids to compare via their nbt.
+     *
+     * @param fluids the fluids to compare
+     */
     default void registerNbt(Fluid... fluids) {
         register(EntryComparator.fluidNbt(), fluids);
     }
diff --git a/api/src/main/java/me/shedaniel/rei/api/common/entry/comparison/ItemComparatorRegistry.java b/api/src/main/java/me/shedaniel/rei/api/common/entry/comparison/ItemComparatorRegistry.java
index dd791b53c..d3be4c8d3 100644
--- a/api/src/main/java/me/shedaniel/rei/api/common/entry/comparison/ItemComparatorRegistry.java
+++ b/api/src/main/java/me/shedaniel/rei/api/common/entry/comparison/ItemComparatorRegistry.java
@@ -40,10 +40,20 @@ public interface ItemComparatorRegistry extends EntryComparatorRegistry<ItemStac
         return PluginManager.getInstance().get(ItemComparatorRegistry.class);
     }
     
+    /**
+     * Registers an item to compare via its nbt.
+     *
+     * @param item the item to compare
+     */
     default void registerNbt(Item item) {
         register(EntryComparator.itemNbt(), item);
     }
     
+    /**
+     * Registers items to compare via their nbt.
+     *
+     * @param items the items to compare
+     */
     default void registerNbt(Item... items) {
         register(EntryComparator.itemNbt(), items);
     }
diff --git a/api/src/main/java/me/shedaniel/rei/api/common/util/EntryStacks.java b/api/src/main/java/me/shedaniel/rei/api/common/util/EntryStacks.java
index 979713683..c1ff54432 100644
--- a/api/src/main/java/me/shedaniel/rei/api/common/util/EntryStacks.java
+++ b/api/src/main/java/me/shedaniel/rei/api/common/util/EntryStacks.java
@@ -147,7 +147,7 @@ public final class EntryStacks {
     }
     
     /**
-     * Hash Code of the {@code context} context.
+     * Returns hash code of the {@code context} context.
      *
      * @param stack   the stack to hash code
      * @param context the context to use
@@ -159,7 +159,7 @@ public final class EntryStacks {
     }
     
     /**
-     * Hash Code of the {@link ComparisonContext#EXACT} context.
+     * Returns hash code of the {@link ComparisonContext#EXACT} context.
      * <p>
      * The exact context type denotes that the equivalent stacks should be <b>functionally</b> the same.
      * <p>
@@ -175,7 +175,7 @@ public final class EntryStacks {
     }
     
     /**
-     * Hash Code of the {@link ComparisonContext#FUZZY} context.
+     * Returns hash code of the {@link ComparisonContext#FUZZY} context.
      * <p>
      * The fuzzy context type denotes that the equivalent stacks should be <b>primarily</b> the same.
      * <p>
-- 
cgit