Documentation (29/44, 0/35)

7 files changed, 218 insertions, 9 deletions

diff --git a/defaults/src/main/java/shcm/shsupercm/fabric/citresewn/defaults/cit/types/TypeItem.java b/defaults/src/main/java/shcm/shsupercm/fabric/citresewn/defaults/cit/types/TypeItem.java
index 21e1ab0..aa4df72 100644
--- a/defaults/src/main/java/shcm/shsupercm/fabric/citresewn/defaults/cit/types/TypeItem.java
+++ b/defaults/src/main/java/shcm/shsupercm/fabric/citresewn/defaults/cit/types/TypeItem.java
@@ -40,8 +40,11 @@ import java.util.*;
 import java.util.stream.Collectors;
 
 /**
- * Do not go through this class, it looks awful because it was ported from a "proof of concept".<br>
- * The whole type will be rewritten at some point.
+ * ///// PORTED FROM BETA \\\\\
+ * This shit was ported from the
+ * beta and will be rewritten at
+ * some point!
+ * \\\\\                  /////
  */
 public class TypeItem extends CITType {
     @Entrypoint(CITTypeContainer.ENTRYPOINT)
diff --git a/src/main/java/shcm/shsupercm/fabric/citresewn/cit/CIT.java b/src/main/java/shcm/shsupercm/fabric/citresewn/cit/CIT.java
index 3bc708f..7c7ba5b 100644
--- a/src/main/java/shcm/shsupercm/fabric/citresewn/cit/CIT.java
+++ b/src/main/java/shcm/shsupercm/fabric/citresewn/cit/CIT.java
@@ -2,11 +2,34 @@ package shcm.shsupercm.fabric.citresewn.cit;
 
 import net.minecraft.util.Identifier;
 
+/**
+ * Runtime representation of a CIT, holding its type and conditions as well as additional metadata.
+ */
 public class CIT<T extends CITType> {
+    /**
+     * The full location of this CIT in its resourcepack.
+     */
     public final Identifier propertiesIdentifier;
+
+    /**
+     * Name of the resourcepack that contains this CIT.
+     */
     public final String packName;
+
+    /**
+     * The CIT's type.
+     * @see CITType
+     */
     public final T type;
+
+    /**
+     * Conditions that must be met for this CIT to work.
+     */
     public final CITCondition[] conditions;
+
+    /**
+     * The weight of this CIT to be used when resolving multiple CIT matching conflicts.
+     */
     public final int weight;
 
     public CIT(Identifier propertiesIdentifier, String packName, T type, CITCondition[] conditions, int weight) {
@@ -17,6 +40,13 @@ public class CIT<T extends CITType> {
         this.weight = weight;
     }
 
+    /**
+     * Tests the given context against all of this CIT's conditions.
+     *
+     * @see #conditions
+     * @param context context to check
+     * @return true if none of this CIT's {@link #conditions} tested false
+     */
     public boolean test(CITContext context) {
         try {
             for (CITCondition condition : conditions)
diff --git a/src/main/java/shcm/shsupercm/fabric/citresewn/cit/CITCache.java b/src/main/java/shcm/shsupercm/fabric/citresewn/cit/CITCache.java
index 5fc6f5a..31ccf04 100644
--- a/src/main/java/shcm/shsupercm/fabric/citresewn/cit/CITCache.java
+++ b/src/main/java/shcm/shsupercm/fabric/citresewn/cit/CITCache.java
@@ -1,5 +1,6 @@
 package shcm.shsupercm.fabric.citresewn.cit;
 
+import net.minecraft.item.ItemStack;
 import shcm.shsupercm.fabric.citresewn.config.CITResewnConfig;
 
 import java.lang.ref.WeakReference;
@@ -7,17 +8,42 @@ import java.util.ArrayList;
 import java.util.List;
 import java.util.function.Function;
 
+/**
+ * Runtime cache for a CIT type to be stored in type implementation specific locations. (usually ducked onto {@link ItemStack}s)
+ * @see Single
+ * @see MultiList
+ */
 public abstract class CITCache<T extends CITType> {
+    /**
+     * The last time in epoch milliseconds that this cache invalidated its stored CIT.
+     */
     public long lastCachedStamp = 0;
 
+    /**
+     * Common implementation of a single CIT per holder({@link ItemStack}) caching.
+     */
     public static class Single<T extends CITType> extends CITCache<T> {
-        public WeakReference<CIT<T>> cit = null;
-        public final Function<CITContext, CIT<T>> realtime;
+        /**
+         * A reload-safe reference to the CIT that was last selected for this holder.
+         */
+        protected WeakReference<CIT<T>> cit = null;
+
+        /**
+         * Real time Context -> CIT supplier for this cache for invalidated holders.
+         */
+        protected final Function<CITContext, CIT<T>> realtime;
 
         public Single(Function<CITContext, CIT<T>> realtime) {
             this.realtime = realtime;
         }
 
+        /**
+         * Retrieves the CIT reference associated with this cache and invalidates it every config-defined interval.
+         *
+         * @see CITResewnConfig#cache_ms
+         * @param context context to check
+         * @return reference to the CIT or reference to null if no CIT applied
+         */
         public WeakReference<CIT<T>> get(CITContext context) {
             if (this.cit == null || System.currentTimeMillis() - this.lastCachedStamp >= CITResewnConfig.INSTANCE.cache_ms) {
                 this.cit = new WeakReference<>(this.realtime.apply(context));
@@ -28,14 +54,31 @@ public abstract class CITCache<T extends CITType> {
         }
     }
 
+    /**
+     * Common implementation of multiple CITs per holder({@link ItemStack}) caching.
+     */
     public static class MultiList<T extends CITType> extends CITCache<T> {
-        public List<WeakReference<CIT<T>>> cit = null;
-        public final Function<CITContext, List<CIT<T>>> realtime;
+        /**
+         * List of reload-safe references to CITs that were last selected for this holder.
+         */
+        protected List<WeakReference<CIT<T>>> cit = null;
+
+        /**
+         * Real time Context -> CIT list supplier for this cache for invalidated holders.
+         */
+        protected final Function<CITContext, List<CIT<T>>> realtime;
 
         public MultiList(Function<CITContext, List<CIT<T>>> realtime) {
             this.realtime = realtime;
         }
 
+        /**
+         * Retrieves the CIT references associated with this cache and invalidates them every config-defined interval.
+         *
+         * @see CITResewnConfig#cache_ms
+         * @param context context to check
+         * @return list of references to CITs or empty list no CIT applied
+         */
         public List<WeakReference<CIT<T>>> get(CITContext context) {
             if (this.cit == null || System.currentTimeMillis() - this.lastCachedStamp >= CITResewnConfig.INSTANCE.cache_ms) {
                 this.cit = new ArrayList<>();
diff --git a/src/main/java/shcm/shsupercm/fabric/citresewn/cit/CITCondition.java b/src/main/java/shcm/shsupercm/fabric/citresewn/cit/CITCondition.java
index fd00ac6..cd4cb9d 100644
--- a/src/main/java/shcm/shsupercm/fabric/citresewn/cit/CITCondition.java
+++ b/src/main/java/shcm/shsupercm/fabric/citresewn/cit/CITCondition.java
@@ -1,6 +1,8 @@
 package shcm.shsupercm.fabric.citresewn.cit;
 
 import shcm.shsupercm.fabric.citresewn.CITResewn;
+import shcm.shsupercm.fabric.citresewn.api.CITConditionContainer;
+import shcm.shsupercm.fabric.citresewn.config.CITResewnConfig;
 import shcm.shsupercm.fabric.citresewn.ex.CITParsingException;
 import shcm.shsupercm.fabric.citresewn.pack.format.PropertyGroup;
 import shcm.shsupercm.fabric.citresewn.pack.format.PropertyValue;
@@ -8,19 +10,53 @@ import shcm.shsupercm.fabric.citresewn.pack.format.PropertyValue;
 import java.util.Collections;
 import java.util.Set;
 
+/**
+ * Instanced parent for CIT Types that are applied to items when conditions pass.<br>
+ * Common condition types are available under {@link shcm.shsupercm.fabric.citresewn.cit.builtin.conditions}.
+ * @see CITConditionContainer
+ * @see CIT
+ */
 public abstract class CITCondition {
+    /**
+     * Parses the given property value into the condition.
+     * @param value value to read
+     * @param properties the group containing value
+     * @throws CITParsingException if errored while parsing the condition
+     */
     public abstract void load(PropertyValue value, PropertyGroup properties) throws CITParsingException;
 
+    /**
+     * @return a set of classes of conditions that have integration with this condition
+     */
     public Set<Class<? extends CITCondition>> siblingConditions() {
         return Collections.emptySet();
     }
 
+    /**
+     * Modifies the given sibling if present in the CIT and declared in {@link #siblingConditions()}.
+     * @param sibling sibling to modify or be modified by
+     * @return the sibling or null to remove it from the CIT.
+     */
     public <T extends CITCondition> T modifySibling(T sibling) {
         return sibling;
     }
 
+    /**
+     * Tests the given context against this condition.
+     * @param context context to check
+     * @return true if the given context passes
+     */
     public abstract boolean test(CITContext context);
 
+    /**
+     * Logs a warning with the given value's descriptor if enabled in config.
+     *
+     * @see CITResewn#logWarnLoading(String)
+     * @see CITResewnConfig#mute_warns
+     * @param message warning message
+     * @param value value associated with the warning
+     * @param properties property group associated with the warning
+     */
     protected void warn(String message, PropertyValue value, PropertyGroup properties) {
         CITResewn.logWarnLoading("Warning: " + properties.messageWithDescriptorOf(message, value.position()));
     }
diff --git a/src/main/java/shcm/shsupercm/fabric/citresewn/cit/CITContext.java b/src/main/java/shcm/shsupercm/fabric/citresewn/cit/CITContext.java
index c5f1922..cfc10f8 100644
--- a/src/main/java/shcm/shsupercm/fabric/citresewn/cit/CITContext.java
+++ b/src/main/java/shcm/shsupercm/fabric/citresewn/cit/CITContext.java
@@ -11,23 +11,47 @@ import net.minecraft.nbt.NbtElement;
 import net.minecraft.util.Identifier;
 import net.minecraft.world.World;
 
+import javax.annotation.Nullable;
 import java.util.LinkedHashMap;
 import java.util.Map;
 import java.util.Objects;
 
+/**
+ * Holds momentary information to be used for CITs' condition matching and type effects.
+ */
 public class CITContext {
+    /**
+     * The main item stack to check for the CIT.
+     */
     public final ItemStack stack;
+
+    /**
+     * The item's containing world(defaults to {@link MinecraftClient#world} if null)
+     */
     public final World world;
+
+    /**
+     * The item's associated living entity if present. (null if not relevant)
+     */
+    @Nullable
     public final LivingEntity entity;
 
+    /**
+     * Cached enchantment map from {@link #stack}.
+     * @see #enchantments()
+     */
     private Map<Identifier, Integer> enchantments = null;
 
-    public CITContext(ItemStack stack, World world, LivingEntity entity) {
+    public CITContext(ItemStack stack, @Nullable World world, @Nullable LivingEntity entity) {
         this.stack = stack;
         this.world = world == null ? MinecraftClient.getInstance().world : world;
         this.entity = entity;
     }
 
+    /**
+     * @see #enchantments
+     * @return a map of this context item's enchantments
+     */
     public Map<Identifier, Integer> enchantments() {
         if (this.enchantments == null) {
             this.enchantments = new LinkedHashMap<>();
diff --git a/src/main/java/shcm/shsupercm/fabric/citresewn/cit/CITRegistry.java b/src/main/java/shcm/shsupercm/fabric/citresewn/cit/CITRegistry.java
index d8454a0..bf7c2ca 100644
--- a/src/main/java/shcm/shsupercm/fabric/citresewn/cit/CITRegistry.java
+++ b/src/main/java/shcm/shsupercm/fabric/citresewn/cit/CITRegistry.java
@@ -7,6 +7,7 @@ import shcm.shsupercm.fabric.citresewn.api.CITTypeContainer;
 import shcm.shsupercm.fabric.citresewn.cit.builtin.conditions.ConstantCondition;
 import shcm.shsupercm.fabric.citresewn.ex.CITParsingException;
 import shcm.shsupercm.fabric.citresewn.ex.UnknownCITTypeException;
+import shcm.shsupercm.fabric.citresewn.pack.PackParser;
 import shcm.shsupercm.fabric.citresewn.pack.format.PropertyGroup;
 import shcm.shsupercm.fabric.citresewn.pack.format.PropertyKey;
 import shcm.shsupercm.fabric.citresewn.pack.format.PropertyValue;
@@ -16,13 +17,38 @@ import java.util.*;
 import static shcm.shsupercm.fabric.citresewn.CITResewn.info;
 import static shcm.shsupercm.fabric.citresewn.CITResewn.logWarnLoading;
 
-public class CITRegistry {
+/**
+ * Holds a static registry runtime for all types and conditions.
+ * @see PackParser
+ * @see CITTypeContainer
+ * @see CITConditionContainer
+ */
+public final class CITRegistry { private CITRegistry(){}
+    /**
+     * Currently registered CIT types.
+     */
     public static final Map<Identifier, CITTypeContainer<? extends CITType>> TYPES = new HashMap<>();
+    /**
+     * Currently registered condition types.
+     */
     public static final Map<PropertyKey, CITConditionContainer<? extends CITCondition>> CONDITIONS = new HashMap<>();
 
+    /**
+     * Fast id lookup map for types.
+     * @see #idOfType(Class)
+     */
     private static final Map<Class<? extends CITType>, Identifier> TYPE_TO_ID = new IdentityHashMap<>();
+    /**
+     * Fast id lookup map for conditions.
+     * @see #idOfCondition(Class)
+     */
     private static final Map<Class<? extends CITCondition>, PropertyKey> CONDITION_TO_ID = new IdentityHashMap<>();
 
+    /**
+     * Loads all available CIT and condition types to registry. (internal use only)
+     * @see CITTypeContainer
+     * @see CITConditionContainer
+     */
     public static void registerAll() {
         info("Registering CIT Conditions");
         for (var entrypointContainer : FabricLoader.getInstance().getEntrypointContainers(CITConditionContainer.ENTRYPOINT, CITConditionContainer.class)) {
@@ -53,6 +79,15 @@ public class CITRegistry {
         }
     }
 
+    /**
+     * Parses a condition from the given property.<br>
+     *
+     * @param key the condition's key in the group
+     * @param value the condition's value
+     * @param properties the containing property group
+     * @return the parsed condition or an always-failing {@link ConstantCondition} if unrecognized
+     * @throws CITParsingException if errored while parsing hte condition
+     */
     public static CITCondition parseCondition(PropertyKey key, PropertyValue value, PropertyGroup properties) throws CITParsingException {
         CITConditionContainer<? extends CITCondition> conditionContainer = CONDITIONS.get(key);
         if (conditionContainer == null) {
@@ -65,7 +100,14 @@ public class CITRegistry {
         return condition;
     }
 
-    public static CITType parseType(PropertyGroup properties) throws CITParsingException {
+    /**
+     * Parses a CIT type from the given property group.<br>
+     * If the group does not contain a "citresewn:type" property, defaults to "citresewn:item".
+     * @param properties group of properties to parse the CIT type from
+     * @return a new instance of the group's CIT type
+     * @throws UnknownCITTypeException if the given type is unrecognized in the registry
+     */
+    public static CITType parseType(PropertyGroup properties) throws UnknownCITTypeException {
         Identifier type = new Identifier("citresewn", "item");
 
         PropertyValue propertiesType = properties.getLastWithoutMetadata("citresewn", "type");
@@ -84,10 +126,18 @@ public class CITRegistry {
         return typeContainer.createType.get();
     }
 
+    /**
+     * @see #TYPE_TO_ID
+     * @return the id of the given CIT type's class.
+     */
     public static Identifier idOfType(Class<? extends CITType> clazz) {
         return TYPE_TO_ID.get(clazz);
     }
 
+    /**
+     * @see #CONDITION_TO_ID
+     * @return the first key of the given condition's class.
+     */
     public static PropertyKey idOfCondition(Class<? extends CITCondition> clazz) {
         return CONDITION_TO_ID.get(clazz);
     }
diff --git a/src/main/java/shcm/shsupercm/fabric/citresewn/cit/CITType.java b/src/main/java/shcm/shsupercm/fabric/citresewn/cit/CITType.java
index b35d26c..65b3097 100644
--- a/src/main/java/shcm/shsupercm/fabric/citresewn/cit/CITType.java
+++ b/src/main/java/shcm/shsupercm/fabric/citresewn/cit/CITType.java
@@ -3,6 +3,7 @@ package shcm.shsupercm.fabric.citresewn.cit;
 import net.minecraft.resource.ResourceManager;
 import net.minecraft.util.Identifier;
 import shcm.shsupercm.fabric.citresewn.CITResewn;
+import shcm.shsupercm.fabric.citresewn.api.CITTypeContainer;
 import shcm.shsupercm.fabric.citresewn.ex.CITParsingException;
 import shcm.shsupercm.fabric.citresewn.pack.format.PropertyGroup;
 import shcm.shsupercm.fabric.citresewn.pack.format.PropertyKey;
@@ -10,9 +11,25 @@ import shcm.shsupercm.fabric.citresewn.pack.format.PropertyValue;
 
 import java.util.*;
 
+/**
+ * Instanced parent for CIT Types that are applied to items when conditions pass.
+ * @see CITTypeContainer
+ * @see CIT
+ */
 public abstract class CITType {
+    /**
+     * Used to determine which property keys are not conditions.
+     * @return a set of property keys used by this type
+     */
     public abstract Set<PropertyKey> typeProperties();
 
+    /**
+     * Loads the given property group into the type.
+     * @param conditions conditions that were parsed out of the property group
+     * @param properties group of properties to be read into this type
+     * @param resourceManager the CIT's containing resource manager
+     * @throws CITParsingException if errored while parsing the type
+     */
     public abstract void load(List<CITCondition> conditions, PropertyGroup properties, ResourceManager resourceManager) throws CITParsingException;
 
     protected void warn(String message, PropertyValue value, PropertyGroup properties) {
@@ -20,6 +37,12 @@ public abstract class CITType {
     }
 
     /**
+     * ///// PORTED FROM BETA \\\\\
+     * This shit was ported from the
+     * beta and will be rewritten at
+     * some point!
+     * \\\\\                  /////
+     *
      * Takes a defined path and resolves it to an identifier pointing to the resourcepack's path of the specified extension(returns null if no path can be resolved).<br>
      * If definedPath is null, will try to resolve a relative file with the same name as the rootIdentifier with the extension, otherwise: <br>
      * definedPath will be formatted to replace "\\" with "/" the extension will be appended if not there already. <br>