Add javadocs to new API methods, and address some of the simpler TODOs in the API package

Author: pupnewfster

src/api/java/mekanism/api/RelativeSide.java

@@ -23,15 +23,23 @@ public enum RelativeSide implements IHasTranslationKey, StringRepresentable {
     TOP(APILang.TOP),
     BOTTOM(APILang.BOTTOM);
 
-    //TODO - 1.20.5: DOCS
+    /**
+     * Codec for serializing sides based on their name.
+     *
+     * @since 10.6.0
+     */
     public static final Codec<RelativeSide> CODEC = StringRepresentable.fromEnum(RelativeSide::values);
     /**
-     * Gets a side by index.
+     * Gets a side by index, wrapping for out of bounds indices.
      *
      * @since 10.6.0
      */
     public static final IntFunction<RelativeSide> BY_ID = ByIdMap.continuous(RelativeSide::ordinal, values(), ByIdMap.OutOfBoundsStrategy.WRAP);
-    //TODO - 1.20.5: DOCS
+    /**
+     * Stream codec for syncing sides by index.
+     *
+     * @since 10.6.0
+     */
     public static final StreamCodec<ByteBuf, RelativeSide> STREAM_CODEC = ByteBufCodecs.idMapper(BY_ID, RelativeSide::ordinal);
 
     private final String serializedName;

src/api/java/mekanism/api/Upgrade.java

@@ -32,15 +32,23 @@ public enum Upgrade implements IHasTranslationKey, StringRepresentable {
     ANCHOR("anchor", APILang.UPGRADE_ANCHOR, APILang.UPGRADE_ANCHOR_DESCRIPTION, 1, EnumColor.DARK_GREEN),
     STONE_GENERATOR("stone_generator", APILang.UPGRADE_STONE_GENERATOR, APILang.UPGRADE_STONE_GENERATOR_DESCRIPTION, 1, EnumColor.ORANGE);
 
-    //TODO - 1.20.5: DOCS
+    /**
+     * Codec for serializing upgrades based on their name.
+     *
+     * @since 10.6.0
+     */
     public static final Codec<Upgrade> CODEC = StringRepresentable.fromEnum(Upgrade::values);
     /**
-     * Gets an upgrade by index.
+     * Gets an upgrade by index, wrapping for out of bounds indices.
      *
      * @since 10.6.0
      */
     public static final IntFunction<Upgrade> BY_ID = ByIdMap.continuous(Upgrade::ordinal, values(), ByIdMap.OutOfBoundsStrategy.WRAP);
-    //TODO - 1.20.5: DOCS
+    /**
+     * Stream codec for syncing upgrades by index.
+     *
+     * @since 10.6.0
+     */
     public static final StreamCodec<ByteBuf, Upgrade> STREAM_CODEC = ByteBufCodecs.idMapper(BY_ID, Upgrade::ordinal);
 
     private final String name;

src/api/java/mekanism/api/chemical/BasicChemicalTank.java

@@ -232,7 +232,7 @@ public CHEMICAL getType() {
      */
     @Override
     public boolean isTypeEqual(STACK other) {
-        return stored.isTypeEqual(other);
+        return ChemicalStack.isSameChemical(stored, other);
     }
 
     /**
@@ -276,16 +276,6 @@ public CompoundTag serializeNBT(HolderLookup.Provider provider) {
         return nbt;
     }
 
-    /**
-     * {@inheritDoc}
-     *
-     * @implNote Overwritten so that if we decide to change to returning a cached/copy of our stack in {@link #getStack()}, we can optimize out the copying.
-     */
-    @Override
-    public boolean isCompatible(IChemicalTank<CHEMICAL, STACK> other) {
-        return getClass() == other.getClass() && stored.equals(other.getStack());
-    }
-
     @Override
     public int getTanks() {
         return 1;

src/api/java/mekanism/api/chemical/ChemicalStack.java

@@ -62,7 +62,7 @@ protected static <CHEMICAL extends Chemical<CHEMICAL>> Codec<CHEMICAL> chemicalN
      */
     protected static <CHEMICAL extends Chemical<CHEMICAL>, STACK extends ChemicalStack<CHEMICAL>> MapCodec<STACK> codec(Codec<CHEMICAL> nonEmptyCodec,
           BiFunction<CHEMICAL, Long, STACK> constructor) {
-        //TODO - 1.20.%: Figure out if this needs to be lazily initialized. I don't think it does, but for fluids and items it is, probably because of components?
+        //TODO - 1.20.5: Figure out if this needs to be lazily initialized. I don't think it does, but for fluids and items it is, probably because of components?
         return RecordCodecBuilder.mapCodec(instance -> instance.group(
               nonEmptyCodec.fieldOf(NBTConstants.ID).forGetter(ChemicalStack::getChemical),
               SerializerHelper.POSITIVE_LONG_CODEC.fieldOf(JsonConstants.AMOUNT).forGetter(ChemicalStack::getAmount)
@@ -78,7 +78,7 @@ protected static <CHEMICAL extends Chemical<CHEMICAL>, STACK extends ChemicalSta
      */
     protected static <CHEMICAL extends Chemical<CHEMICAL>, STACK extends ChemicalStack<CHEMICAL>> Codec<STACK> fixedAmountCodec(
           Codec<CHEMICAL> chemicalNonEmptyCodec, BiFunction<CHEMICAL, Long, STACK> constructor, long amount) {
-        //TODO - 1.20.%: Figure out if this needs to be lazily initialized. I don't think it does, but for fluids and items it is, probably because of components?
+        //TODO - 1.20.5: Figure out if this needs to be lazily initialized. I don't think it does, but for fluids and items it is, probably because of components?
         return RecordCodecBuilder.create(instance -> instance.group(
               chemicalNonEmptyCodec.fieldOf(NBTConstants.ID).forGetter(ChemicalStack::getChemical)
         ).apply(instance, holder -> constructor.apply(holder, amount)));
@@ -169,7 +169,7 @@ public void encode(RegistryFriendlyByteBuf buf, STACK stack) {
      * @see mekanism.api.chemical.merged.BoxedChemicalStack
      * @since 10.6.0
      */
-    //TODO - 1.20.5: Re-evaluate if we wan this defaulting to an empty gas stack or to try and get the same stack type as it was?
+    //TODO - 1.20.5: Re-evaluate if we want this defaulting to an empty gas stack or to try and get the same stack type as it was?
     public static final Codec<ChemicalStack<?>> BOXED_OPTIONAL_CODEC = ExtraCodecs.optionalEmptyMap(BOXED_CODEC).xmap(optional -> optional.orElse(GasStack.EMPTY),
           stack -> stack.isEmpty() ? Optional.empty() : Optional.of(stack));
     /**
@@ -251,6 +251,8 @@ protected ChemicalStack(@Nullable Void unused) {
 
     /**
      * Creates a copy of this stack with {@code 0} amount.
+     *
+     * @since 10.6.0
      */
     public abstract ChemicalStack<CHEMICAL> copyAndClear();
 
@@ -306,6 +308,8 @@ public boolean is(CHEMICAL chemical) {
      * @param predicate - Predicate to test
      *
      * @return if the ChemicalStack's type matches the given predicate
+     *
+     * @since 10.6.0
      */
     public boolean is(Predicate<Holder<CHEMICAL>> predicate) {
         return predicate.test(getChemicalHolder());
@@ -317,6 +321,8 @@ public boolean is(Predicate<Holder<CHEMICAL>> predicate) {
      * @param holder - Chemical holder to check
      *
      * @return if the ChemicalStack's type is the same as the given holder's chemical
+     *
+     * @since 10.6.0
      */
     public boolean is(Holder<CHEMICAL> holder) {
         return is(holder.value());
@@ -344,18 +350,6 @@ public Stream<TagKey<CHEMICAL>> getTags() {
         return getChemicalHolder().tags();
     }
 
-    /**
-     * Whether this ChemicalStack's chemical type is equal to the other defined ChemicalStack.
-     *
-     * @param stack - ChemicalStack to check
-     *
-     * @return if the ChemicalStacks contain the same chemical type
-     */
-    public boolean isTypeEqual(ChemicalStack<CHEMICAL> stack) {
-        //TODO - 1.20.5: Should we replace this with the static method?
-        return is(stack.getChemical());
-    }
-
     /**
      * Saves this stack to a tag, directly writing the keys into the passed tag.
      *
@@ -374,6 +368,8 @@ public boolean isTypeEqual(ChemicalStack<CHEMICAL> stack) {
 
     /**
      * Saves this stack to a new tag. Empty stacks are supported and will be saved as an empty tag.
+     *
+     * @since 10.6.0
      */
     public Tag saveOptional(HolderLookup.Provider lookupProvider) {
         return isEmpty() ? new CompoundTag() : save(lookupProvider);
@@ -548,6 +544,8 @@ public String getTranslationKey() {
      * Checks if the two chemical stacks have the same chemical type. Ignores amount.
      *
      * @return {@code true} if the two chemical stacks have the same chemical
+     *
+     * @since 10.6.0 Previously was isTypeEqual
      */
     public static <CHEMICAL extends Chemical<CHEMICAL>> boolean isSameChemical(ChemicalStack<CHEMICAL> first, ChemicalStack<CHEMICAL> second) {
         return first.is(second.getChemical());

src/api/java/mekanism/api/chemical/ChemicalType.java

@@ -50,9 +50,23 @@ public enum ChemicalType implements StringRepresentable {
         }
     }
 
-    //TODO - 1.20.5: Docs
+    /**
+     * Codec for serializing chemical types based on their name.
+     *
+     * @since 10.6.0
+     */
     public static final Codec<ChemicalType> CODEC = StringRepresentable.fromEnum(ChemicalType::values);
+    /**
+     * Gets a chemical type by index, wrapping for out of bounds indices.
+     *
+     * @since 10.6.0
+     */
     public static final IntFunction<ChemicalType> BY_ID = ByIdMap.continuous(ChemicalType::ordinal, values(), ByIdMap.OutOfBoundsStrategy.WRAP);
+    /**
+     * Stream codec for syncing chemical types by index.
+     *
+     * @since 10.6.0
+     */
     public static final StreamCodec<ByteBuf, ChemicalType> STREAM_CODEC = ByteBufCodecs.idMapper(BY_ID, ChemicalType::ordinal);
 
     private final Predicate<Chemical<?>> instanceCheck;

src/api/java/mekanism/api/chemical/ChemicalUtils.java

@@ -45,7 +45,7 @@ public static <CHEMICAL extends Chemical<CHEMICAL>, STACK extends ChemicalStack<
             STACK inTank = inTankGetter.getStored(tank, side);
             if (inTank.isEmpty()) {
                 emptyTanks.add(tank);
-            } else if (inTank.isTypeEqual(stack)) {
+            } else if (ChemicalStack.isSameChemical(inTank, stack)) {
                 STACK remainder = insertChemical.interact(tank, toInsert, side, action);
                 if (remainder.isEmpty()) {
                     //If we have no remaining chemical, return that we fit it all
@@ -131,7 +131,7 @@ public static <CHEMICAL extends Chemical<CHEMICAL>, STACK extends ChemicalStack<
         STACK extracted = empty;
         long toDrain = amount;
         for (int tank = 0; tank < tanks; tank++) {
-            if (extracted.isEmpty() || extracted.isTypeEqual(inTankGetter.getStored(tank, side))) {
+            if (extracted.isEmpty() || ChemicalStack.isSameChemical(extracted, inTankGetter.getStored(tank, side))) {
                 //If there is chemical in the tank that matches the type we have started draining, or we haven't found a type yet
                 STACK drained = extractChemical.interact(tank, toDrain, side, action);
                 if (!drained.isEmpty()) {
@@ -211,15 +211,15 @@ public static <CHEMICAL extends Chemical<CHEMICAL>, STACK extends ChemicalStack<
             return empty;
         } else if (tanks == 1) {
             STACK inTank = inTankGetter.getStored(0, side);
-            if (inTank.isEmpty() || !inTank.isTypeEqual(stack)) {
+            if (inTank.isEmpty() || !ChemicalStack.isSameChemical(inTank, stack)) {
                 return empty;
             }
             return extractChemical.interact(0, stack.getAmount(), side, action);
         }
         STACK extracted = empty;
         long toDrain = stack.getAmount();
         for (int tank = 0; tank < tanks; tank++) {
-            if (stack.isTypeEqual(inTankGetter.getStored(tank, side))) {
+            if (ChemicalStack.isSameChemical(stack, inTankGetter.getStored(tank, side))) {
                 //If there is chemical in the tank that matches the type we are trying to drain, try to drain from it
                 STACK drained = extractChemical.interact(tank, toDrain, side, action);
                 if (!drained.isEmpty()) {

src/api/java/mekanism/api/chemical/IChemicalTank.java

@@ -303,7 +303,7 @@ default CHEMICAL getType() {
      * @implNote If your implementation of {@link #getStack()} returns a copy, this should be overridden to directly check against the internal stack.
      */
     default boolean isTypeEqual(STACK other) {
-        return getStack().isTypeEqual(other);
+        return ChemicalStack.isSameChemical(getStack(), other);
     }
 
     /**
@@ -336,17 +336,4 @@ default CompoundTag serializeNBT(HolderLookup.Provider provider) {
         }
         return nbt;
     }
-
-    /**
-     * Checks if this chemical tank is equivalent to another one for the purposes of attachments.
-     *
-     * @param other Chemical tank to compare to.
-     *
-     * @return {@code true} If this chemical tank can be considered equivalent and compatible with the other tank.
-     *
-     * @since 10.5.0
-     */
-    default boolean isCompatible(IChemicalTank<CHEMICAL, STACK> other) {
-        return getClass() == other.getClass() && getStack().equals(other.getStack());
-    }
 }

src/api/java/mekanism/api/chemical/merged/BoxedChemical.java

@@ -18,7 +18,7 @@
 import net.minecraft.network.codec.StreamCodec;
 
 /**
- *
+ * Helper class to keep track of chemicals and what specific type they are
  */
 @NothingNullByDefault
 public class BoxedChemical implements IHasTextComponent {
@@ -27,10 +27,33 @@ public class BoxedChemical implements IHasTextComponent {
      * Empty Boxed Chemical instance.
      */
     public static final BoxedChemical EMPTY = new BoxedChemical(ChemicalType.GAS, MekanismAPI.EMPTY_GAS);
-    //TODO - 1.20.5: Docs
+    /**
+     * Codec to get any kind of chemical (that does not accept empty types) as a boxed chemical.
+     *
+     * @see Chemical#BOXED_CODEC
+     * @since 10.6.0
+     */
     public static final Codec<BoxedChemical> CODEC = Chemical.BOXED_CODEC.xmap(BoxedChemical::box, BoxedChemical::getChemical);
+    /**
+     * Codec to get any kind of chemical as a boxed chemical.
+     *
+     * @see Chemical#BOXED_OPTIONAL_CODEC
+     * @since 10.6.0
+     */
     public static final Codec<BoxedChemical> OPTIONAL_CODEC = Chemical.BOXED_OPTIONAL_CODEC.xmap(BoxedChemical::box, BoxedChemical::getChemical);
+    /**
+     * StreamCodec to get any kind of chemical (that does not accept the empty type) as a boxed chemical.
+     *
+     * @see Chemical#BOXED_STREAM_CODEC
+     * @since 10.6.0
+     */
     public static final StreamCodec<RegistryFriendlyByteBuf, BoxedChemical> STREAM_CODEC = Chemical.BOXED_STREAM_CODEC.map(BoxedChemical::box, BoxedChemical::getChemical);
+    /**
+     * StreamCodec to get any kind of chemical as a boxed chemical.
+     *
+     * @see Chemical#BOXED_OPTIONAL_STREAM_CODEC
+     * @since 10.6.0
+     */
     public static final StreamCodec<RegistryFriendlyByteBuf, BoxedChemical> OPTIONAL_STREAM_CODEC = Chemical.BOXED_OPTIONAL_STREAM_CODEC.map(BoxedChemical::box, BoxedChemical::getChemical);
 
     /**
@@ -119,6 +142,8 @@ public Tag save(Provider lookupProvider) {
 
     /**
      * Saves this boxed chemical to a new tag. Empty boxed chemical are supported and will be saved as an empty tag.
+     *
+     * @since 10.6.0
      */
     public Tag saveOptional(HolderLookup.Provider lookupProvider) {
         return isEmpty() ? new CompoundTag() : save(lookupProvider);
@@ -140,8 +165,7 @@ public Component getTextComponent() {
     public boolean equals(Object o) {
         if (this == o) {
             return true;
-        }
-        if (o == null || getClass() != o.getClass()) {
+        } else if (o == null || getClass() != o.getClass()) {
             return false;
         }
         BoxedChemical other = (BoxedChemical) o;

src/api/java/mekanism/api/chemical/merged/BoxedChemicalStack.java

@@ -18,17 +18,43 @@
 import net.minecraft.network.codec.StreamCodec;
 import org.jetbrains.annotations.NotNull;
 
+/**
+ * Helper class to keep track of chemical stacks and what specific type they are
+ */
 public class BoxedChemicalStack implements IHasTextComponent {
 
     /**
      * Empty Boxed Chemical Stack instance.
      */
     public static final BoxedChemicalStack EMPTY = new BoxedChemicalStack(ChemicalType.GAS, GasStack.EMPTY);
 
-    //TODO - 1.20.5: Docs
-    //TODO - 1.20.5: Do we want Codec variant of OPTIONAL_CODEC?
+    /**
+     * Codec to get any kind of chemical stack (that does not accept empty stacks) as a boxed chemical stack.
+     *
+     * @see ChemicalStack#BOXED_CODEC
+     * @since 10.6.0
+     */
     public static final Codec<BoxedChemicalStack> CODEC = ChemicalStack.BOXED_CODEC.xmap(BoxedChemicalStack::box, BoxedChemicalStack::getChemicalStack);
+    /**
+     * Codec to get any kind of chemical stack as a boxed chemical stack.
+     *
+     * @see ChemicalStack#BOXED_OPTIONAL_CODEC
+     * @since 10.6.0
+     */
+    public static final Codec<BoxedChemicalStack> OPTIONAL_CODEC = ChemicalStack.BOXED_OPTIONAL_CODEC.xmap(BoxedChemicalStack::box, BoxedChemicalStack::getChemicalStack);
+    /**
+     * StreamCodec to get any kind of chemical stack (that does not accept empty stacks) as a boxed chemical stack.
+     *
+     * @see ChemicalStack#BOXED_STREAM_CODEC
+     * @since 10.6.0
+     */
     public static final StreamCodec<RegistryFriendlyByteBuf, BoxedChemicalStack> STREAM_CODEC = ChemicalStack.BOXED_STREAM_CODEC.map(BoxedChemicalStack::box, BoxedChemicalStack::getChemicalStack);
+    /**
+     * StreamCodec to get any kind of chemical stack as a boxed chemical stack.
+     *
+     * @see ChemicalStack#BOXED_OPTIONAL_STREAM_CODEC
+     * @since 10.6.0
+     */
     public static final StreamCodec<RegistryFriendlyByteBuf, BoxedChemicalStack> OPTIONAL_STREAM_CODEC = ChemicalStack.BOXED_OPTIONAL_STREAM_CODEC.map(BoxedChemicalStack::box, BoxedChemicalStack::getChemicalStack);
 
     /**
@@ -127,6 +153,8 @@ public Tag save(Provider lookupProvider) {
 
     /**
      * Saves this stack to a new tag. Empty stacks are supported and will be saved as an empty tag.
+     *
+     * @since 10.6.0
      */
     public Tag saveOptional(HolderLookup.Provider lookupProvider) {
         return isEmpty() ? new CompoundTag() : save(lookupProvider);
@@ -156,8 +184,7 @@ public BoxedChemicalStack copy() {
     public boolean equals(Object o) {
         if (this == o) {
             return true;
-        }
-        if (o == null || getClass() != o.getClass()) {
+        } else if (o == null || getClass() != o.getClass()) {
             return false;
         }
         BoxedChemicalStack other = (BoxedChemicalStack) o;