Documentation (18/44, 0/35)

5 files changed, 127 insertions, 9 deletions

diff --git a/src/main/java/shcm/shsupercm/fabric/citresewn/pack/format/PropertiesGroupAdapter.java b/src/main/java/shcm/shsupercm/fabric/citresewn/pack/format/PropertiesGroupAdapter.java
index 4912a71..0375079 100644
--- a/src/main/java/shcm/shsupercm/fabric/citresewn/pack/format/PropertiesGroupAdapter.java
+++ b/src/main/java/shcm/shsupercm/fabric/citresewn/pack/format/PropertiesGroupAdapter.java
@@ -1,6 +1,7 @@
 package shcm.shsupercm.fabric.citresewn.pack.format;
 
 import net.minecraft.util.Identifier;
+import net.minecraft.util.InvalidIdentifierException;
 
 import java.io.*;
 import java.nio.charset.StandardCharsets;
@@ -18,7 +19,7 @@ public class PropertiesGroupAdapter extends PropertyGroup {
     }
 
     @Override
-    public PropertyGroup load(String packName, Identifier identifier, InputStream is) throws IOException {
+    public PropertyGroup load(String packName, Identifier identifier, InputStream is) throws IOException, InvalidIdentifierException {
         try (BufferedReader reader = new BufferedReader(new InputStreamReader(is, StandardCharsets.UTF_8))) {
             String line;
             int linePos = 0, multilineSkip = 0;
diff --git a/src/main/java/shcm/shsupercm/fabric/citresewn/pack/format/PropertyGroup.java b/src/main/java/shcm/shsupercm/fabric/citresewn/pack/format/PropertyGroup.java
index 1f21ed5..8d185fd 100644
--- a/src/main/java/shcm/shsupercm/fabric/citresewn/pack/format/PropertyGroup.java
+++ b/src/main/java/shcm/shsupercm/fabric/citresewn/pack/format/PropertyGroup.java
@@ -7,9 +7,29 @@ import java.io.IOException;
 import java.io.InputStream;
 import java.util.*;
 
+/**
+ * Storage agnostic map of keys and values.<br>
+ * Keys are stored as {@link PropertyKey}s holding the mod id of the property type.<br>
+ * A key can have multiple values associated with it as they are stored in an ordered set.
+ *
+ * @see PropertyKey
+ * @see PropertyValue
+ * @see PropertiesGroupAdapter
+ */
 public abstract class PropertyGroup {
+    /**
+     * The internal map that backs this property group.
+     */
     public final Map<PropertyKey, Set<PropertyValue>> properties = new LinkedHashMap<>();
+
+    /**
+     * This group's location in its resourcepack.
+     */
     public final Identifier identifier;
+
+    /**
+     * The file name of the resourcepack that this property group is in.
+     */
     public final String packName;
 
     protected PropertyGroup(String packName, Identifier identifier) {
@@ -17,17 +37,63 @@ public abstract class PropertyGroup {
         this.identifier = identifier;
     }
 
+    /**
+     * Tries to parse a group out of a stream.
+     * @see #load(String, Identifier, InputStream)
+     * @see #getExtension()
+     * @see PropertiesGroupAdapter
+     * @param packName {@link #packName}
+     * @param identifier {@link #identifier}, needed for extension matching
+     * @param is a stream containing properties as specified by implementation
+     * @return the parsed group or null if could not match an adapter
+     * @throws IOException if errored while parsing the group
+     */
+    public static PropertyGroup tryParseGroup(String packName, Identifier identifier, InputStream is) throws IOException {
+        PropertyGroup group = null;
+        if (identifier.getPath().endsWith(PropertiesGroupAdapter.EXTENSION))
+            group = new PropertiesGroupAdapter(packName, identifier);
+
+        return group == null ? null : group.load(packName, identifier, is);
+    }
+
+    /**
+     * @return file suffix for this property group's implementation
+     */
     public abstract String getExtension();
 
+    /**
+     * Reads the given input stream into the group.
+     * @param packName {@link #packName}
+     * @param identifier {@link #identifier}
+     * @param is a stream containing properties as specified by implementation
+     * @return this
+     * @throws IOException if errored while reading the stream
+     * @throws InvalidIdentifierException if encountered a malformed {@link Identifier} while reading
+     */
     public abstract PropertyGroup load(String packName, Identifier identifier, InputStream is) throws IOException, InvalidIdentifierException;
 
-    protected void put(int position, String packName, Identifier propertiesIdentifier, String key, String keyMetadata, PropertySeparator separator, String value) throws InvalidIdentifierException {
+    /**
+     * Adds the given value to the group.
+     * @param position implementation specific interpretation of the value's position in the group, has no effect on internal order
+     * @param packName the value's resourcepack file name
+     * @param propertiesIdentifier the value's property group location identifier
+     * @param key the value's key name
+     * @param keyMetadata nullable, implementation specific metadata for this value's key
+     * @param separator implementation specific connection between the key and the value
+     * @param value string representation of the value to be parsed by the group's user
+     */
+    protected void put(int position, String packName, Identifier propertiesIdentifier, String key, String keyMetadata, PropertySeparator separator, String value) {
         Objects.requireNonNull(key);
         Objects.requireNonNull(value);
 
         this.properties.computeIfAbsent(PropertyKey.of(key), id -> new LinkedHashSet<>()).add(new PropertyValue(keyMetadata, value, separator, position, propertiesIdentifier, packName));
     }
 
+    /**
+     * @param namespace the key's namespace(should be the value type's modid by convention)
+     * @param pathAliases all key name aliases to check for
+     * @return all values associated with the given key by alias>insertion order
+     */
     public Set<PropertyValue> get(String namespace, String... pathAliases) {
         Set<PropertyValue> values = new LinkedHashSet<>();
 
@@ -40,6 +106,12 @@ public abstract class PropertyGroup {
         return values;
     }
 
+    /**
+     * @see #getLastWithoutMetadataOrDefault(String, String, String...)
+     * @param namespace the key's namespace(should be the value type's modid by convention)
+     * @param pathAliases all key name aliases to check for
+     * @return the last value associated with the key(by insertion order) that has a null key metadata or null if the key is not present in the group
+     */
     public PropertyValue getLastWithoutMetadata(String namespace, String... pathAliases) {
         PropertyValue value = null;
         for (PropertyValue next : get(namespace, pathAliases))
@@ -49,6 +121,13 @@ public abstract class PropertyGroup {
         return value;
     }
 
+    /**
+     * @see #getLastWithoutMetadata(String, String...)
+     * @param defaultValue the dummy value to return if not present in the group
+     * @param namespace the key's namespace(should be the value type's modid by convention)
+     * @param pathAliases all key name aliases to check for
+     * @return the last value associated with the key(by insertion order) that has a null key metadata or the wrapped default value if the key is not present in the group
+     */
     public PropertyValue getLastWithoutMetadataOrDefault(String defaultValue, String namespace, String... pathAliases) {
         PropertyValue property = getLastWithoutMetadata(namespace, pathAliases);
         if (property == null)
@@ -57,15 +136,22 @@ public abstract class PropertyGroup {
         return property;
     }
 
+    /**
+     * @see #getExtension()
+     * @see #identifier
+     * @return the name of this group without its path or extension
+     */
     public String stripName() {
         return identifier.getPath().substring(identifier.getPath().lastIndexOf('/') + 1, identifier.getPath().length() - getExtension().length());
     }
 
-    public static PropertyGroup tryParseGroup(String packName, Identifier identifier, InputStream is) throws IOException {
-        PropertyGroup group = null;
-        if (identifier.getPath().endsWith(PropertiesGroupAdapter.EXTENSION))
-            group = new PropertiesGroupAdapter(packName, identifier);
-
-        return group == null ? null : group.load(packName, identifier, is);
+    /**
+     * Compiles a message with attached info on a value's origin.
+     * @param message message to add descriptor to
+     * @param position implementation specific position of
+     * @return the formatted message
+     */
+    public String messageWithDescriptorOf(String message, int position) {
+        return message + (position != -1 ? " @L" + position : "") + " in " + this.identifier.toString() + " from " + this.packName;
     }
 }
diff --git a/src/main/java/shcm/shsupercm/fabric/citresewn/pack/format/PropertyKey.java b/src/main/java/shcm/shsupercm/fabric/citresewn/pack/format/PropertyKey.java
index 37a698d..7bc2cdc 100644
--- a/src/main/java/shcm/shsupercm/fabric/citresewn/pack/format/PropertyKey.java
+++ b/src/main/java/shcm/shsupercm/fabric/citresewn/pack/format/PropertyKey.java
@@ -1,6 +1,18 @@
 package shcm.shsupercm.fabric.citresewn.pack.format;
 
+import net.minecraft.util.Identifier;
+
+/**
+ * Namespace/path pair of strings. Similar to {@link Identifier} but without validity restrictions.
+ * @see Identifier
+ */
 public record PropertyKey(String namespace, String path) {
+    /**
+     * Attempts to split a given string into a namespace and path by the first occurrence of a colon.<br>
+     * If a namespace cannot be extracted from the given string, "citresewn" is set instead.
+     * @param key key to parse
+     * @return parsed property key
+     */
     public static PropertyKey of(String key) {
         String[] split = new String[] {"citresewn", key};
         int i = key.indexOf(':');
diff --git a/src/main/java/shcm/shsupercm/fabric/citresewn/pack/format/PropertySeparator.java b/src/main/java/shcm/shsupercm/fabric/citresewn/pack/format/PropertySeparator.java
index 612d83f..ce4ebab 100644
--- a/src/main/java/shcm/shsupercm/fabric/citresewn/pack/format/PropertySeparator.java
+++ b/src/main/java/shcm/shsupercm/fabric/citresewn/pack/format/PropertySeparator.java
@@ -1,8 +1,18 @@
 package shcm.shsupercm.fabric.citresewn.pack.format;
 
+/**
+ * Marker for the connection between a {@link PropertyKey} and its {@link PropertyValue}.
+ */
 public enum PropertySeparator {
-    EQUALS("=");
+    /**
+     * Marks either a check for equality or an action to set a value.
+     */
+    EQUALS("=")
+    ;
 
+    /**
+     * String representation of the separator.
+     */
     public final String separator;
 
     PropertySeparator(String separator) {
diff --git a/src/main/java/shcm/shsupercm/fabric/citresewn/pack/format/PropertyValue.java b/src/main/java/shcm/shsupercm/fabric/citresewn/pack/format/PropertyValue.java
index fe126d7..f41119f 100644
--- a/src/main/java/shcm/shsupercm/fabric/citresewn/pack/format/PropertyValue.java
+++ b/src/main/java/shcm/shsupercm/fabric/citresewn/pack/format/PropertyValue.java
@@ -2,6 +2,15 @@ package shcm.shsupercm.fabric.citresewn.pack.format;
 
 import net.minecraft.util.Identifier;
 
+/**
+ * Wrapped representation of a property group's value with additional attached metadata.
+ * @param keyMetadata nullable, implementation specific metadata for this value's key
+ * @param value string representation of the value to be parsed by the group's user
+ * @param separator implementation specific connection between the key and the value
+ * @param position implementation specific interpretation of the value's position in the group, has no effect on internal order
+ * @param propertiesIdentifier the value's property group location identifier
+ * @param packName the value's resourcepack file name
+ */
 public record PropertyValue(String keyMetadata,
                             String value,
                             PropertySeparator separator,