From 1b40278b7b1d930d918c558a946d46fbaeee50a2 Mon Sep 17 00:00:00 2001
From: isXander <isxander@users.noreply.github.com>
Date: Thu, 6 Oct 2022 22:11:40 +0100
Subject: javadoc & changelog for cycling package

---
 .../java/dev/isxander/yacl/api/NameableEnum.java   |  2 +-
 .../controllers/cycling/CyclingListController.java | 31 ++++++++++++++++++++++
 .../controllers/cycling/ICyclingController.java    | 19 +++++++++++++
 .../yacl/gui/controllers/package-info.java         |  2 +-
 4 files changed, 52 insertions(+), 2 deletions(-)

(limited to 'src/main/java/dev')

diff --git a/src/main/java/dev/isxander/yacl/api/NameableEnum.java b/src/main/java/dev/isxander/yacl/api/NameableEnum.java
index 9744ce9..793b230 100644
--- a/src/main/java/dev/isxander/yacl/api/NameableEnum.java
+++ b/src/main/java/dev/isxander/yacl/api/NameableEnum.java
@@ -3,7 +3,7 @@ package dev.isxander.yacl.api;
 import net.minecraft.text.Text;
 
 /**
- * Used for the default value formatter of {@link dev.isxander.yacl.gui.controllers.EnumController}
+ * Used for the default value formatter of {@link dev.isxander.yacl.gui.controllers.cycling.EnumController}
  */
 public interface NameableEnum {
     Text getDisplayName();
diff --git a/src/main/java/dev/isxander/yacl/gui/controllers/cycling/CyclingListController.java b/src/main/java/dev/isxander/yacl/gui/controllers/cycling/CyclingListController.java
index a894eff..3b14066 100644
--- a/src/main/java/dev/isxander/yacl/gui/controllers/cycling/CyclingListController.java
+++ b/src/main/java/dev/isxander/yacl/gui/controllers/cycling/CyclingListController.java
@@ -6,41 +6,72 @@ import net.minecraft.text.Text;
 
 import java.util.function.Function;
 
+/**
+ * A controller where once clicked, cycles through elements
+ * in the provided list.
+ */
 public class CyclingListController<T> implements ICyclingController<T> {
     private final Option<T> option;
     private final Function<T, Text> valueFormatter;
     private final ImmutableList<T> values;
 
+    /**
+     * Constructs a {@link CyclingListController}, with a default
+     * value formatter of {@link Object#toString()}.
+     * @param option option of which to bind the controller to
+     * @param values the values to cycle through
+     */
     public CyclingListController(Option<T> option, Iterable<T> values) {
         this(option, values, value -> Text.of(value.toString()));
     }
 
+    /**
+     * Constructs a {@link CyclingListController}
+     * @param option option of which to bind the controller to
+     * @param values the values to cycle through
+     * @param valueFormatter function of how to convert each value to a string to display
+     */
     public CyclingListController(Option<T> option, Iterable<T> values, Function<T, Text> valueFormatter) {
         this.option = option;
         this.valueFormatter = valueFormatter;
         this.values = ImmutableList.copyOf(values);
     }
 
+    /**
+     * {@inheritDoc}
+     */
     @Override
     public Option<T> option() {
         return option;
     }
 
+    /**
+     * {@inheritDoc}
+     */
     @Override
     public Text formatValue() {
         return valueFormatter.apply(option().pendingValue());
     }
 
+    /**
+     * {@inheritDoc}
+     */
     @Override
     public void setPendingValue(int ordinal) {
         option().requestSet(values.get(ordinal));
     }
 
+    /**
+     * {@inheritDoc}
+     */
     @Override
     public int getPendingValue() {
         return values.indexOf(option().pendingValue());
     }
 
+    /**
+     * {@inheritDoc}
+     */
     @Override
     public int getCycleLength() {
         return values.size();
diff --git a/src/main/java/dev/isxander/yacl/gui/controllers/cycling/ICyclingController.java b/src/main/java/dev/isxander/yacl/gui/controllers/cycling/ICyclingController.java
index 39f0b35..081b572 100644
--- a/src/main/java/dev/isxander/yacl/gui/controllers/cycling/ICyclingController.java
+++ b/src/main/java/dev/isxander/yacl/gui/controllers/cycling/ICyclingController.java
@@ -5,13 +5,32 @@ import dev.isxander.yacl.api.utils.Dimension;
 import dev.isxander.yacl.gui.AbstractWidget;
 import dev.isxander.yacl.gui.YACLScreen;
 
+/**
+ * This interface simply generifies setting and getting of
+ * the pending value, using an ordinal so elements can cycle through
+ * without knowing the content.
+ */
 public interface ICyclingController<T> extends Controller<T> {
+    /**
+     * Sets the pending value to whatever corresponds to the ordinal
+     * @param ordinal index of element to set
+     */
     void setPendingValue(int ordinal);
 
+    /**
+     * Gets the pending ordinal that corresponds to the actual value
+     * @return ordinal
+     */
     int getPendingValue();
 
+    /**
+     * Allows the element when it should wrap-around back to zeroth ordinal
+     */
     int getCycleLength();
 
+    /**
+     * {@inheritDoc}
+     */
     @Override
     default AbstractWidget provideWidget(YACLScreen screen, Dimension<Integer> widgetDimension) {
         return new CyclingControllerElement(this, screen, widgetDimension);
diff --git a/src/main/java/dev/isxander/yacl/gui/controllers/package-info.java b/src/main/java/dev/isxander/yacl/gui/controllers/package-info.java
index 88c74c9..12ce86b 100644
--- a/src/main/java/dev/isxander/yacl/gui/controllers/package-info.java
+++ b/src/main/java/dev/isxander/yacl/gui/controllers/package-info.java
@@ -4,7 +4,7 @@
  * <ul>
  *     <li>For numbers: {@link dev.isxander.yacl.gui.controllers.slider}</li>
  *     <li>For booleans: {@link dev.isxander.yacl.gui.controllers.TickBoxController}</li>
- *     <li>For enums: {@link dev.isxander.yacl.gui.controllers.EnumController}</li>
+ *     <li>For lists/enums: {@link dev.isxander.yacl.gui.controllers.cycling}</li>
  *     <li>For strings: {@link dev.isxander.yacl.gui.controllers.string.StringController}</li>
  *     <li>For {@link dev.isxander.yacl.api.ButtonOption}: {@link dev.isxander.yacl.gui.controllers.ActionController}</li>
  * </ul>
-- 
cgit