Add javadoc to config api v2

51 files changed, 657 insertions, 109 deletions

diff --git a/common/src/main/java/dev/isxander/yacl3/config/v2/api/ConfigClassHandler.java b/common/src/main/java/dev/isxander/yacl3/config/v2/api/ConfigClassHandler.java
index 645a8e8..470eba0 100644
--- a/common/src/main/java/dev/isxander/yacl3/config/v2/api/ConfigClassHandler.java
+++ b/common/src/main/java/dev/isxander/yacl3/config/v2/api/ConfigClassHandler.java
@@ -6,34 +6,88 @@ import net.minecraft.resources.ResourceLocation;
 
 import java.util.function.Function;
 
+/**
+ * Represents a handled config class.
+ *
+ * @param <T> the backing config class to be managed
+ */
 public interface ConfigClassHandler<T> {
+    /**
+     * Gets the working instance of the config class.
+     * This should be used to get and set fields like usual.
+     */
     T instance();
 
+    /**
+     * Gets a second instance of the config class that
+     * should be used to get default values only. No fields
+     * should be modified in this instance.
+     */
     T defaults();
 
+    /**
+     * Gets the class of the config.
+     */
     Class<T> configClass();
 
+    /**
+     * Get all eligible fields in the config class.
+     * They could either be annotated with {@link dev.isxander.yacl3.config.v2.api.autogen.AutoGen}
+     * or {@link SerialEntry}, do not assume that a field has both of these.
+     */
     ConfigField<?>[] fields();
 
+    /**
+     * The unique identifier of this config handler.
+     */
     ResourceLocation id();
 
+    /**
+     * Auto-generates a GUI for this config class.
+     * This throws an exception if auto-gen is not supported.
+     */
     YetAnotherConfigLib generateGui();
 
+    /**
+     * Whether this config class supports auto-gen.
+     * If on a dedicated server, this returns false.
+     */
     boolean supportsAutoGen();
 
+    /**
+     * The serializer for this config class.
+     * Manages saving and loading of the config with fields
+     * annotated with {@link SerialEntry}.
+     */
     ConfigSerializer<T> serializer();
 
+    /**
+     * Creates a builder for a config class.
+     *
+     * @param configClass the config class to build
+     * @param <T> the type of the config class
+     * @return the builder
+     */
     static <T> Builder<T> createBuilder(Class<T> configClass) {
         return new ConfigClassHandlerImpl.BuilderImpl<>(configClass);
     }
 
     interface Builder<T> {
+        /**
+         * The unique identifier of this config handler.
+         * The namespace should be your modid.
+         *
+         * @return this builder
+         */
         Builder<T> id(ResourceLocation id);
 
+        /**
+         * The function to create the serializer for this config class.
+         *
+         * @return this builder
+         */
         Builder<T> serializer(Function<ConfigClassHandler<T>, ConfigSerializer<T>> serializerFactory);
 
-        Builder<T> autoGen(boolean autoGen);
-
         ConfigClassHandler<T> build();
     }
 }
diff --git a/common/src/main/java/dev/isxander/yacl3/config/v2/api/ConfigField.java b/common/src/main/java/dev/isxander/yacl3/config/v2/api/ConfigField.java
index 1cd8739..181a4d4 100644
--- a/common/src/main/java/dev/isxander/yacl3/config/v2/api/ConfigField.java
+++ b/common/src/main/java/dev/isxander/yacl3/config/v2/api/ConfigField.java
@@ -4,14 +4,37 @@ import dev.isxander.yacl3.config.v2.api.autogen.AutoGenField;
 
 import java.util.Optional;
 
+/**
+ * Represents a field in a config class.
+ * This is used to get all metadata on a field,
+ * and access the field and its default value.
+ *
+ * @param <T> the field's type
+ */
 public interface ConfigField<T> {
+    /**
+     * Gets the accessor for the field on the main instance.
+     * (Accessed through {@link ConfigClassHandler#instance()})
+     */
     FieldAccess<T> access();
 
+    /**
+     * Gets the accessor for the field on the default instance.
+     */
     ReadOnlyFieldAccess<T> defaultAccess();
 
+    /**
+     * @return the parent config class handler that manages this field.
+     */
     ConfigClassHandler<?> parent();
 
+    /**
+     * The serial entry metadata for this field, if it exists.
+     */
     Optional<SerialField> serial();
 
-    Optional<AutoGenField<T>> autoGen();
+    /**
+     * The auto-gen metadata for this field, if it exists.
+     */
+    Optional<AutoGenField> autoGen();
 }
diff --git a/common/src/main/java/dev/isxander/yacl3/config/v2/api/ConfigSerializer.java b/common/src/main/java/dev/isxander/yacl3/config/v2/api/ConfigSerializer.java
index 999221d..13d6e08 100644
--- a/common/src/main/java/dev/isxander/yacl3/config/v2/api/ConfigSerializer.java
+++ b/common/src/main/java/dev/isxander/yacl3/config/v2/api/ConfigSerializer.java
@@ -1,5 +1,10 @@
 package dev.isxander.yacl3.config.v2.api;
 
+/**
+ * The base class for config serializers,
+ * offering a method to save and load.
+ * @param <T>
+ */
 public abstract class ConfigSerializer<T> {
     protected final ConfigClassHandler<T> config;
 
@@ -7,7 +12,15 @@ public abstract class ConfigSerializer<T> {
         this.config = config;
     }
 
-    public abstract void serialize();
+    /**
+     * Saves all fields in the config class.
+     * This can be done any way as it's abstract, but most
+     * commonly it is saved to a file.
+     */
+    public abstract void save();
 
-    public abstract void deserialize();
+    /**
+     * Loads all fields in the config class.
+     */
+    public abstract void load();
 }
diff --git a/common/src/main/java/dev/isxander/yacl3/config/v2/api/FieldAccess.java b/common/src/main/java/dev/isxander/yacl3/config/v2/api/FieldAccess.java
index a961172..ea30cd8 100644
--- a/common/src/main/java/dev/isxander/yacl3/config/v2/api/FieldAccess.java
+++ b/common/src/main/java/dev/isxander/yacl3/config/v2/api/FieldAccess.java
@@ -1,5 +1,14 @@
 package dev.isxander.yacl3.config.v2.api;
 
+/**
+ * A writable field instance access.
+ *
+ * @param <T> the type of the field
+ */
 public interface FieldAccess<T> extends ReadOnlyFieldAccess<T> {
+    /**
+     * Sets the value of the field.
+     * @param value the value to set
+     */
     void set(T value);
 }
diff --git a/common/src/main/java/dev/isxander/yacl3/config/v2/api/ReadOnlyFieldAccess.java b/common/src/main/java/dev/isxander/yacl3/config/v2/api/ReadOnlyFieldAccess.java
index 1146e68..1a1c29a 100644
--- a/common/src/main/java/dev/isxander/yacl3/config/v2/api/ReadOnlyFieldAccess.java
+++ b/common/src/main/java/dev/isxander/yacl3/config/v2/api/ReadOnlyFieldAccess.java
@@ -2,12 +2,31 @@ package dev.isxander.yacl3.config.v2.api;
 
 import java.lang.reflect.Type;
 
+/**
+ * An abstract interface for accessing properties of an instance of a field.
+ * You do not need to worry about exceptions as the implementation
+ * will handle them.
+ *
+ * @param <T> the type of the field
+ */
 public interface ReadOnlyFieldAccess<T> {
+    /**
+     * @return the current value of the field.
+     */
     T get();
 
+    /**
+     * @return the name of the field.
+     */
     String name();
 
+    /**
+     * @return the type of the field.
+     */
     Type type();
 
+    /**
+     * @return the class of the field.
+     */
     Class<T> typeClass();
 }
diff --git a/common/src/main/java/dev/isxander/yacl3/config/v2/api/SerialEntry.java b/common/src/main/java/dev/isxander/yacl3/config/v2/api/SerialEntry.java
index e5ba001..d87283a 100644
--- a/common/src/main/java/dev/isxander/yacl3/config/v2/api/SerialEntry.java
+++ b/common/src/main/java/dev/isxander/yacl3/config/v2/api/SerialEntry.java
@@ -5,10 +5,24 @@ import java.lang.annotation.Retention;
 import java.lang.annotation.RetentionPolicy;
 import java.lang.annotation.Target;
 
+/**
+ * Marks a field as serializable, so it can be used in a {@link ConfigSerializer}.
+ * Any field without this annotation will not be saved or loaded, but can still be turned
+ * into an auto-generated option.
+ */
 @Retention(RetentionPolicy.RUNTIME)
 @Target(ElementType.FIELD)
 public @interface SerialEntry {
+    /**
+     * The serial name of the field.
+     * If empty, the serializer will decide the name.
+     */
     String value() default "";
 
+    /**
+     * The comment to add to the field.
+     * Some serializers may not support this.
+     * If empty, the serializer will not add a comment.
+     */
     String comment() default "";
 }
diff --git a/common/src/main/java/dev/isxander/yacl3/config/v2/api/SerialField.java b/common/src/main/java/dev/isxander/yacl3/config/v2/api/SerialField.java
index 01c00d6..6337565 100644
--- a/common/src/main/java/dev/isxander/yacl3/config/v2/api/SerialField.java
+++ b/common/src/main/java/dev/isxander/yacl3/config/v2/api/SerialField.java
@@ -2,6 +2,9 @@ package dev.isxander.yacl3.config.v2.api;
 
 import java.util.Optional;
 
+/**
+ * The backing interface for the {@link SerialEntry} annotation.
+ */
 public interface SerialField {
     String serialName();
 
diff --git a/common/src/main/java/dev/isxander/yacl3/config/v2/api/autogen/AutoGen.java b/common/src/main/java/dev/isxander/yacl3/config/v2/api/autogen/AutoGen.java
index 8abcb60..4187caf 100644
--- a/common/src/main/java/dev/isxander/yacl3/config/v2/api/autogen/AutoGen.java
+++ b/common/src/main/java/dev/isxander/yacl3/config/v2/api/autogen/AutoGen.java
@@ -5,10 +5,28 @@ import java.lang.annotation.Retention;
 import java.lang.annotation.RetentionPolicy;
 import java.lang.annotation.Target;
 
+/**
+ * Any field that is annotated with this will generate a config option
+ * in the auto-generated config GUI. This should be paired with an
+ * {@link OptionFactory} annotation to define how to create the option.
+ * Some examples of this are {@link TickBox}, {@link FloatSlider}, {@link Label} or {@link StringField}.
+ */
 @Retention(RetentionPolicy.RUNTIME)
 @Target(ElementType.FIELD)
 public @interface AutoGen {
+    /**
+     * Should be the id of the category. This is used to group options.
+     * The translation keys also use this. Category IDs can be set as a
+     * {@code private static final String} and used in the annotation to prevent
+     * repeating yourself.
+     */
     String category();
 
+    /**
+     * If left blank, the option will go in the root group, where it is
+     * listed at the top of the category with no group header. If set,
+     * this also appends to the translation key. Group IDs can be reused
+     * between multiple categories.
+     */
     String group() default "";
 }
diff --git a/common/src/main/java/dev/isxander/yacl3/config/v2/api/autogen/AutoGenField.java b/common/src/main/java/dev/isxander/yacl3/config/v2/api/autogen/AutoGenField.java
index 48db22d..7f751fb 100644
--- a/common/src/main/java/dev/isxander/yacl3/config/v2/api/autogen/AutoGenField.java
+++ b/common/src/main/java/dev/isxander/yacl3/config/v2/api/autogen/AutoGenField.java
@@ -2,7 +2,10 @@ package dev.isxander.yacl3.config.v2.api.autogen;
 
 import java.util.Optional;
 
-public interface AutoGenField<T> {
+/**
+ * Backing interface for the {@link AutoGen} annotation.
+ */
+public interface AutoGenField {
     String category();
 
     Optional<String> group();
diff --git a/common/src/main/java/dev/isxander/yacl3/config/v2/api/autogen/Boolean.java b/common/src/main/java/dev/isxander/yacl3/config/v2/api/autogen/Boolean.java
index bb948ac..5598389 100644
--- a/common/src/main/java/dev/isxander/yacl3/config/v2/api/autogen/Boolean.java
+++ b/common/src/main/java/dev/isxander/yacl3/config/v2/api/autogen/Boolean.java
@@ -5,6 +5,12 @@ import java.lang.annotation.Retention;
 import java.lang.annotation.RetentionPolicy;
 import java.lang.annotation.Target;
 
+/**
+ * An option factory.
+ * <p>
+ * This creates a regular option with a
+ * {@link dev.isxander.yacl3.api.controller.BooleanControllerBuilder} controller.
+ */
 @Retention(RetentionPolicy.RUNTIME)
 @Target(ElementType.FIELD)
 public @interface Boolean {
@@ -12,10 +18,24 @@ public @interface Boolean {
         YES_NO,
         TRUE_FALSE,
         ON_OFF,
+        /**
+         * Uses the translation keys:
+         * <ul>
+         *     <li>true: {@code yacl3.config.$configId.$fieldName.fmt.true}</li>
+         *     <li>false: {@code yacl3.config.$configId.$fieldName.fmt.false}</li>
+         * </ul>
+         */
         CUSTOM,
     }
 
+    /**
+     * The format used to display the boolean.
+     */
     Formatter formatter() default Formatter.TRUE_FALSE;
 
+    /**
+     * Whether to color the formatted text green and red
+     * depending on the value: true or false respectively.
+     */
     boolean colored() default false;
 }
diff --git a/common/src/main/java/dev/isxander/yacl3/config/v2/api/autogen/ColorRGBA.java b/common/src/main/java/dev/isxander/yacl3/config/v2/api/autogen/ColorRGBA.java
index dc5b8ff..7e76e27 100644
--- a/common/src/main/java/dev/isxander/yacl3/config/v2/api/autogen/ColorRGBA.java
+++ b/common/src/main/java/dev/isxander/yacl3/config/v2/api/autogen/ColorRGBA.java
@@ -5,8 +5,17 @@ import java.lang.annotation.Retention;
 import java.lang.annotation.RetentionPolicy;
 import java.lang.annotation.Target;
 
+/**
+ * An option factory.
+ * <p>
+ * This creates a regular option with a
+ * {@link dev.isxander.yacl3.api.controller.ColorControllerBuilder} controller.
+ */
 @Retention(RetentionPolicy.RUNTIME)
 @Target(ElementType.FIELD)
 public @interface ColorRGBA {
+    /**
+     * Whether to show/allow the alpha channel in the color field.
+     */
     boolean allowAlpha() default false;
 }
diff --git a/common/src/main/java/dev/isxander/yacl3/config/v2/api/autogen/DoubleField.java b/common/src/main/java/dev/isxander/yacl3/config/v2/api/autogen/DoubleField.java
index 225fe8e..963cefd 100644
--- a/common/src/main/java/dev/isxander/yacl3/config/v2/api/autogen/DoubleField.java
+++ b/common/src/main/java/dev/isxander/yacl3/config/v2/api/autogen/DoubleField.java
@@ -5,12 +5,42 @@ import java.lang.annotation.Retention;
 import java.lang.annotation.RetentionPolicy;
 import java.lang.annotation.Target;
 
+/**
+ * A regular option factory.
+ * <p>
+ * This creates a regular option with a
+ * {@link dev.isxander.yacl3.api.controller.DoubleFieldControllerBuilder} controller.
+ */
 @Retention(RetentionPolicy.RUNTIME)
 @Target(ElementType.FIELD)
 public @interface DoubleField {
-    double min();
+    /**
+     * The minimum value of the field. If a user enters a value less
+     * than this, it will be clamped to this value.
+     * <p>
+     * If this is set to {@code -Double.MAX_VALUE}, there will be no minimum.
+     * <p>
+     * If the current value is at this minimum, if available,
+     * the translation key {@code yacl3.config.$configId.$fieldName.fmt.min}
+     * will be used.
+     */
+    double min() default -Double.MAX_VALUE;
 
-    double max();
+    /**
+     * The maximum value of the field. If a user enters a value more
+     * than this, it will be clamped to this value.
+     * <p>
+     * If this is set to {@code Double.MAX_VALUE}, there will be no minimum.
+     * <p>
+     * If the current value is at this maximum, if available,
+     * the translation key {@code yacl3.config.$configId.$fieldName.fmt.max}
+     * will be used.
+     */
+    double max() default Double.MAX_VALUE;
 
+    /**
+     * The format used to display the double.
+     * This is the syntax used in {@link String#format(String, Object...)}.
+     */
     String format() default "%.2f";
 }
diff --git a/common/src/main/java/dev/isxander/yacl3/config/v2/api/autogen/DoubleSlider.java b/common/src/main/java/dev/isxander/yacl3/config/v2/api/autogen/DoubleSlider.java
index 47c7b00..268f6a4 100644
--- a/common/src/main/java/dev/isxander/yacl3/config/v2/api/autogen/DoubleSlider.java
+++ b/common/src/main/java/dev/isxander/yacl3/config/v2/api/autogen/DoubleSlider.java
@@ -5,14 +5,44 @@ import java.lang.annotation.Retention;
 import java.lang.annotation.RetentionPolicy;
 import java.lang.annotation.Target;
 
+/**