update javadoc with examples

Author: HSGamer

animation/src/main/java/io/github/projectunified/craftux/animation/Animation.java

@@ -5,7 +5,15 @@
 import java.util.concurrent.atomic.AtomicLong;
 
 /**
- * The animation that gets the frame based on the period
+ * Manages a sequence of frames that cycle over time with a specified period.
+ * Provides methods to get the current frame based on elapsed time and reset the animation.
+ *
+ * <p>Example usage:</p>
+ * <pre>{@code
+ * List<String> frames = Arrays.asList("Frame1", "Frame2", "Frame3");
+ * Animation<String> animation = new Animation<>(frames, 1000); // 1 second per frame
+ * String current = animation.getCurrentFrame(); // Gets current frame based on time
+ * }</pre>
  *
  * @param <T> the frame type
  */
@@ -15,10 +23,11 @@ public class Animation<T> {
     private final AtomicLong startMillis = new AtomicLong(-1);
 
     /**
-     * Create a new animation
+     * Creates a new Animation with the specified frames and period.
      *
-     * @param frames       the frames
-     * @param periodMillis the period in milliseconds
+     * @param frames       the list of frames to cycle through
+     * @param periodMillis the period in milliseconds between frame changes
+     * @throws IllegalArgumentException if frames is empty or periodMillis is not positive
      */
     public Animation(List<T> frames, long periodMillis) {
         if (frames.isEmpty()) {

button/src/main/java/io/github/projectunified/craftux/button/AnimatedButton.java

@@ -10,16 +10,28 @@
 import java.util.concurrent.ConcurrentHashMap;
 
 /**
- * The animated button with child buttons as frames
+ * A button that cycles through a list of buttons as animation frames over time.
+ * Each frame is displayed for a configurable period, creating an animated effect.
+ *
+ * <p>Example usage:</p>
+ * <pre>{@code
+ * AnimatedButton animatedButton = new AnimatedButton();
+ * animatedButton.addButton(
+ *     new SimpleButton(new ItemStack(Material.DIAMOND)),
+ *     new SimpleButton(new ItemStack(Material.EMERALD))
+ * );
+ * animatedButton.setPeriodMillis(100); // 100ms per frame
+ * }</pre>
  */
 public class AnimatedButton extends MultiButton {
     private final Map<UUID, Animation<Button>> animationMap = new ConcurrentHashMap<>();
     private long periodMillis = 50L;
 
     /**
-     * Set the period of the animation
+     * Sets the period of the animation between frame changes.
      *
      * @param periodMillis the period in milliseconds
+     * @throws IllegalArgumentException if periodMillis is not positive
      */
     public void setPeriodMillis(long periodMillis) {
         if (periodMillis <= 0) {

button/src/main/java/io/github/projectunified/craftux/button/ListButton.java

@@ -9,7 +9,18 @@
 import java.util.concurrent.ConcurrentHashMap;
 
 /**
- * The button that loops through the list of child buttons
+ * A button that applies actions from a list of child buttons, cycling through them.
+ * It can optionally remember the current button index per player UUID.
+ *
+ * <p>Example usage:</p>
+ * <pre>{@code
+ * ListButton listButton = new ListButton();
+ * listButton.addButton(
+ *     new SimpleButton(new ItemStack(Material.STONE)),
+ *     new SimpleButton(new ItemStack(Material.COBBLESTONE))
+ * );
+ * listButton.setKeepCurrentIndex(true); // Remember choice per player
+ * }</pre>
  */
 public class ListButton extends MultiButton {
     private final Map<UUID, Integer> currentIndexMap = new ConcurrentHashMap<>();

button/src/main/java/io/github/projectunified/craftux/button/MultiButton.java

@@ -7,7 +7,18 @@
 import java.util.*;
 
 /**
- * A base button that handles multiple child buttons
+ * A base class for buttons that manage multiple child buttons.
+ * Provides functionality to add, retrieve, and manage lifecycle of child buttons.
+ *
+ * <p>Example usage:</p>
+ * <pre>{@code
+ * MultiButton multiButton = new MyMultiButton();
+ * multiButton.addButton(
+ *     new SimpleButton(new ItemStack(Material.RED_WOOL)),
+ *     new SimpleButton(new ItemStack(Material.BLUE_WOOL))
+ * );
+ * List<Button> buttons = multiButton.getButtons();
+ * }</pre>
  */
 public abstract class MultiButton implements Element, Button {
     protected final List<Button> buttons = new ArrayList<>();

button/src/main/java/io/github/projectunified/craftux/button/PredicateButton.java

@@ -10,7 +10,16 @@
 import java.util.function.Predicate;
 
 /**
- * The conditional button that chooses a button based on a specific predicate
+ * A button that conditionally applies actions from one of two buttons based on a predicate
+ * evaluated against the player's UUID. Uses a fallback button if the predicate fails.
+ *
+ * <p>Example usage:</p>
+ * <pre>{@code
+ * PredicateButton predicateButton = new PredicateButton();
+ * predicateButton.setButton(new SimpleButton(new ItemStack(Material.COMMAND_BLOCK)));
+ * predicateButton.setFallbackButton(new SimpleButton(new ItemStack(Material.CHEST)));
+ * predicateButton.setViewPredicate(uuid -> isAdmin(uuid)); // Check if player is admin
+ * }</pre>
  */
 public class PredicateButton implements Element, Button {
     private @Nullable Button button = null;

common/src/main/java/io/github/projectunified/craftux/common/ActionItem.java

@@ -8,7 +8,17 @@
 import java.util.function.UnaryOperator;
 
 /**
- * The action item
+ * Represents an item with an associated action that can be triggered.
+ * The item can be of any type, and the action is a Consumer that accepts an event object.
+ * This class provides methods to set, get, and extend both the item and the action.
+ *
+ * <p>Example usage:</p>
+ * <pre>{@code
+ * ActionItem actionItem = new ActionItem();
+ * actionItem.setItem("My Item");
+ * actionItem.setAction(event -> System.out.println("Clicked: " + event));
+ * actionItem.callAction("click");
+ * }</pre>
  */
 public final class ActionItem {
     private @Nullable Object item;

common/src/main/java/io/github/projectunified/craftux/common/Button.java

@@ -6,7 +6,20 @@
 import java.util.function.Consumer;
 
 /**
- * The button
+ * Represents a button that can apply actions to an ActionItem based on a player's UUID.
+ * Buttons are used in GUI systems to define interactive elements that respond to player actions.
+ *
+ * <p>Example implementation:</p>
+ * <pre>{@code
+ * public class MyButton implements Button {
+ *     @Override
+ *     public boolean apply(UUID uuid, ActionItem actionItem) {
+ *         actionItem.setItem("My Button");
+ *         actionItem.setAction(event -> System.out.println("Button clicked by " + uuid));
+ *         return true;
+ *     }
+ * }
+ * }</pre>
  */
 public interface Button {
     /**

common/src/main/java/io/github/projectunified/craftux/common/Element.java

@@ -4,7 +4,23 @@
 import java.util.function.Consumer;
 
 /**
- * An element of the GUI
+ * Represents an element in the GUI that can be initialized and stopped.
+ * Elements are components that make up the user interface and may require lifecycle management.
+ *
+ * <p>Example usage:</p>
+ * <pre>{@code
+ * public class MyElement implements Element {
+ *     @Override
+ *     public void init() {
+ *         // Initialize resources
+ *     }
+ *
+ *     @Override
+ *     public void stop() {
+ *         // Clean up resources
+ *     }
+ * }
+ * }</pre>
  */
 public interface Element {
     /**

common/src/main/java/io/github/projectunified/craftux/common/Mask.java

@@ -9,7 +9,23 @@
 import java.util.stream.Collectors;
 
 /**
- * The mask that maps positions to action item consumers
+ * Represents a mask that maps positions to action item consumers for a given player UUID.
+ * Masks define the layout and behavior of GUI elements in a grid-based interface.
+ *
+ * <p>Example implementation:</p>
+ * <pre>{@code
+ * public class MyMask implements Mask {
+ *     @Override
+ *     public Map<Position, Consumer<ActionItem>> apply(UUID uuid) {
+ *         Map<Position, Consumer<ActionItem>> map = new HashMap<>();
+ *         map.put(Position.of(0, 0), actionItem -> {
+ *             actionItem.setItem("Button at 0,0");
+ *             actionItem.setAction(event -> System.out.println("Clicked at 0,0"));
+ *         });
+ *         return map;
+ *     }
+ * }
+ * }</pre>
  */
 public interface Mask {
     /**

common/src/main/java/io/github/projectunified/craftux/common/Position.java

@@ -3,7 +3,15 @@
 import java.util.Objects;
 
 /**
- * The position
+ * Represents a 2D position with x and y coordinates in the GUI grid.
+ * Positions are used to locate elements in the interface.
+ *
+ * <p>Example usage:</p>
+ * <pre>{@code
+ * Position pos = Position.of(1, 2);
+ * int x = pos.getX(); // 1
+ * int y = pos.getY(); // 2
+ * }</pre>
  */
 public class Position {
     private final int x;