javadoc!

added LongSliderController
renamed Control -> Controller
add minecraft simple option binding constructor

1 files changed, 84 insertions, 9 deletions

diff --git a/src/main/java/dev/isxander/yacl/api/Option.java b/src/main/java/dev/isxander/yacl/api/Option.java
index 5a98d50..6598b80 100644
--- a/src/main/java/dev/isxander/yacl/api/Option.java
+++ b/src/main/java/dev/isxander/yacl/api/Option.java
@@ -5,7 +5,6 @@ import net.minecraft.text.MutableText;
 import net.minecraft.text.Text;
 import org.apache.commons.lang3.Validate;
 import org.jetbrains.annotations.NotNull;
-import org.jetbrains.annotations.Nullable;
 
 import java.util.ArrayList;
 import java.util.List;
@@ -14,27 +13,70 @@ import java.util.function.Function;
 import java.util.function.Supplier;
 
 public interface Option<T> {
+    /**
+     * Name of the option
+     */
     @NotNull Text name();
 
-    @Nullable Text tooltip();
-
-    @NotNull Control<T> control();
-
+    /**
+     * Tooltip (or description) of the option.
+     * Rendered on hover.
+     */
+    @NotNull Text tooltip();
+
+    /**
+     * Widget provider for a type of option.
+     *
+     * @see dev.isxander.yacl.gui.controllers
+     */
+    @NotNull Controller<T> controller();
+
+    /**
+     * Binding for the option.
+     * Controls setting, getting and default value.
+     *
+     * @see Binding
+     */
     @NotNull Binding<T> binding();
 
+    /**
+     * Checks if the pending value is not equal to the current set value
+     */
     boolean changed();
 
-    T pendingValue();
+    /**
+     * Value in the GUI, ready to set the actual bound value or be undone.
+     */
+    @NotNull T pendingValue();
 
+    /**
+     * Sets the pending value
+     */
     void requestSet(T value);
 
+    /**
+     * Applies the pending value to the bound value.
+     * Cannot be undone.
+     */
     void applyValue();
 
+    /**
+     * Sets the pending value to the bound value.
+     */
     void forgetPendingValue();
 
+    /**
+     * Sets the pending value to the default bound value.
+     */
     void requestSetDefault();
 
-    static <T> Builder<T> createBuilder(Class<T> clazz) {
+    /**
+     * Creates a builder to construct an {@link Option}
+     *
+     * @param <T> type of the option's value
+     * @param typeClass used to capture the type
+     */
+    static <T> Builder<T> createBuilder(Class<T> typeClass) {
         return new Builder<>();
     }
 
@@ -43,7 +85,7 @@ public interface Option<T> {
 
         private final List<Text> tooltipLines = new ArrayList<>();
 
-        private Function<Option<T>, Control<T>> controlGetter;
+        private Function<Option<T>, Controller<T>> controlGetter;
 
         private Binding<T> binding;
 
@@ -51,6 +93,11 @@ public interface Option<T> {
 
         }
 
+        /**
+         * Sets the name to be used by the option.
+         *
+         * @see Option#name()
+         */
         public Builder<T> name(@NotNull Text name) {
             Validate.notNull(name, "`name` cannot be null");
 
@@ -58,6 +105,13 @@ public interface Option<T> {
             return this;
         }
 
+        /**
+         * Sets the tooltip to be used by the option.
+         * Can be invoked twice to append more lines.
+         * No need to wrap the text yourself, the gui does this itself.
+         *
+         * @param tooltips text lines - merged with a new-line on {@link Builder#build()}.
+         */
         public Builder<T> tooltip(@NotNull Text... tooltips) {
             Validate.notEmpty(tooltips, "`tooltips` cannot be empty");
 
@@ -65,13 +119,25 @@ public interface Option<T> {
             return this;
         }
 
-        public Builder<T> controller(@NotNull Function<Option<T>, Control<T>> control) {
+        /**
+         * Sets the controller for the option.
+         * This is how you interact and change the options.
+         *
+         * @see dev.isxander.yacl.gui.controllers
+         */
+        public Builder<T> controller(@NotNull Function<Option<T>, Controller<T>> control) {
             Validate.notNull(control, "`control` cannot be null");
 
             this.controlGetter = control;
             return this;
         }
 
+        /**
+         * Sets the binding for the option.
+         * Used for default, getter and setter.
+         *
+         * @see Binding
+         */
         public Builder<T> binding(@NotNull Binding<T> binding) {
             Validate.notNull(binding, "`binding` cannot be null");
 
@@ -79,6 +145,15 @@ public interface Option<T> {
             return this;
         }
 
+        /**
+         * Sets the binding for the option.
+         * Shorthand of {@link Binding#of(Object, Supplier, Consumer)}
+         *
+         * @param def default value of the option, used to reset
+         * @param getter should return the current value of the option
+         * @param setter should set the option to the supplied value
+         * @see Binding
+         */
         public Builder<T> binding(@NotNull T def, @NotNull Supplier<@NotNull T> getter, @NotNull Consumer<@NotNull T> setter) {
             Validate.notNull(def, "`def` must not be null");
             Validate.notNull(getter, "`getter` must not be null");