Add some javadoc

Author: NichtStudioCode

invui/src/main/java/xyz/xenondevs/invui/gui/ScrollGui.java

@@ -9,6 +9,10 @@
 import java.util.function.Consumer;
 import java.util.function.Supplier;
 
+/**
+ * A {@link Gui} that displays content in lines that can be scrolled through.
+ * @param <C> The content type.
+ */
 public sealed interface ScrollGui<C> extends Gui permits AbstractScrollGui {
 
     /**

invui/src/main/java/xyz/xenondevs/invui/gui/SlotElement.java

@@ -7,6 +7,10 @@
 import xyz.xenondevs.invui.inventory.Inventory;
 import xyz.xenondevs.invui.item.ItemProvider;
 
+/**
+ * Represents an element in a slot in a {@link Gui}.
+ * You will rarely need to use this interface directly.
+ */
 public sealed interface SlotElement {
 
     @Nullable

invui/src/main/java/xyz/xenondevs/invui/gui/TabGui.java

@@ -7,6 +7,9 @@
 import java.util.function.Consumer;
 import java.util.function.Supplier;
 
+/**
+ * A {@link Gui} that displays multiple tabs, which themselves are {@link Gui Guis} as well.
+ */
 public sealed interface TabGui extends Gui permits TabGuiImpl {
 
     /**

invui/src/main/java/xyz/xenondevs/invui/i18n/Languages.java

@@ -16,6 +16,9 @@
 import java.util.Map;
 import java.util.function.Function;
 
+/**
+ * Handles localization of items and window titles.
+ */
 public class Languages {
 
     private static final Languages INSTANCE = new Languages();

invui/src/main/java/xyz/xenondevs/invui/inventory/event/UpdateReason.java

@@ -1,5 +1,10 @@
 package xyz.xenondevs.invui.inventory.event;
 
+import xyz.xenondevs.invui.inventory.Inventory;
+
+/**
+ * A reason for an {@link Inventory} update.
+ */
 public interface UpdateReason {
 
     /**

invui/src/main/java/xyz/xenondevs/invui/item/BoundItem.java

@@ -39,28 +39,74 @@ public sealed interface BoundItem extends Item permits AbstractBoundItem {
      */
     boolean isBound();
 
+    /**
+     * Creates a new {@link Builder} for a {@link BoundItem} that can be bound to any {@link Gui}.
+     *
+     * @return A new {@link Builder} for a {@link BoundItem}.
+     */
     static Builder<Gui> gui() {
         return new CustomBoundItem.Builder<>();
     }
 
+    /**
+     * Creates a new {@link Builder} for a {@link BoundItem} that can be bound to a {@link PagedGui}.
+     * The item will be automatically updated when the bound {@link PagedGui PagedGui's} page or content changes.
+     *
+     * @return A new {@link Builder} for a {@link BoundItem}.
+     */
     static Builder<PagedGui<?>> pagedGui() {
         return new CustomBoundItem.Builder.Paged();
     }
 
+    /**
+     * Creates a new {@link Builder} for a {@link BoundItem} that can be bound to a {@link ScrollGui}.
+     * The item will be automatically updated when the bound {@link ScrollGui ScrollGui's} line or content changes.
+     *
+     * @return A new {@link Builder} for a {@link BoundItem}.
+     */
     static Builder<ScrollGui<?>> scrollGui() {
         return new CustomBoundItem.Builder.Scroll();
     }
 
+    /**
+     * Creates a new {@link Builder} for a {@link BoundItem} that can be bound to a {@link TabGui}.
+     * The item will be automatically updated when the bound {@link TabGui TabGui's} tab changes.
+     *
+     * @return A new {@link Builder} for a {@link BoundItem}.
+     */
     static Builder<TabGui> tabGui() {
         return new CustomBoundItem.Builder.Tab();
     }
 
+    /**
+     * A builder for a {@link BoundItem}.
+     *
+     * @param <G> The type of {@link Gui} this item can be bound to.
+     */
     sealed interface Builder<G extends Gui> extends Item.Builder<Builder<G>> permits CustomBoundItem.Builder {
 
+        /**
+         * Adds a bind handler that is called when the item is bound to a {@link Gui}.
+         *
+         * @param handler The bind handler.
+         * @return This builder.
+         */
         Builder<G> addBindHandler(BiConsumer<Item, G> handler);
 
+        /**
+         * Adds a click handler that is called when the item is clicked.
+         *
+         * @param handler The click handler, receiving the {@link Item} itself, the bound {@link Gui} and the {@link Click}.
+         * @return This builder.
+         */
         Builder<G> addClickHandler(TriConsumer<Item, G, Click> handler);
 
+        /**
+         * Sets the item provider that provides the item for a specific player and {@link Gui}.
+         *
+         * @param itemProvider The item provider.
+         * @return This builder.
+         */
         Builder<G> setItemProvider(BiFunction<Player, G, ItemProvider> itemProvider);
 
     }

invui/src/main/java/xyz/xenondevs/invui/item/Item.java

@@ -19,10 +19,9 @@ public sealed interface Item permits AbstractItem, BoundItem {
 
     /**
      * Gets the {@link ItemProvider}.
-     * This method gets called every time a {@link Window} is notified ({@link #notifyWindows()}).
+     * This method gets called every time a {@link Window} is updated, triggered by ({@link #notifyWindows()}).
      *
      * @param viewer The {@link Player} that sees the {@link Item}.
-     * 
      * @return The {@link ItemProvider}
      */
     ItemProvider getItemProvider(Player viewer);
@@ -45,44 +44,138 @@ public sealed interface Item permits AbstractItem, BoundItem {
      */
     void handleClick(ClickType clickType, Player player, Click click);
 
+    /**
+     * Creates a new {@link Builder} for an {@link Item}.
+     *
+     * @return A new {@link Builder} for an {@link Item}.
+     */
     static Builder<?> builder() {
         return new CustomItem.Builder();
     }
 
+    /**
+     * Creates a simple {@link Item} with a static {@link ItemStack}.
+     *
+     * @param itemStack The {@link ItemStack} to display.
+     * @return A simple {@link Item}.
+     */
     static Item simple(ItemStack itemStack) {
         return builder().setItemProvider(new ItemWrapper(itemStack)).build();
     }
 
+    /**
+     * Creates a simple {@link Item} with a static {@link ItemProvider}.
+     *
+     * @param itemProvider The {@link ItemProvider} to display.
+     * @return A simple {@link Item}.
+     */
     static Item simple(ItemProvider itemProvider) {
         return builder().setItemProvider(itemProvider).build();
     }
 
+    /**
+     * Creates a simple {@link Item} that resolves its {@link ItemProvider} using the provided function.
+     * The function is called every time it is updated, triggered by {@link #notifyWindows()}.
+     *
+     * @param itemProvider The function that resolves the {@link ItemProvider}, receiving the viewing {@link Player}.
+     * @return A simple {@link Item}.
+     */
     static Item simple(Function<Player, ItemProvider> itemProvider) {
         return builder().setItemProvider(itemProvider).build();
     }
 
+    /**
+     * A builder for an {@link Item}.
+     *
+     * @param <S> The type of the builder itself.
+     */
     interface Builder<S extends Builder<S>> {
 
+        /**
+         * Sets the {@link ItemProvider} of the {@link Item}.
+         *
+         * @param itemProvider The {@link ItemProvider}.
+         * @return This builder.
+         */
         S setItemProvider(ItemProvider itemProvider);
 
+        /**
+         * Sets the function that resolves the {@link ItemProvider}, receiving the viewing {@link Player}.
+         * The function is called every time it is updated, triggered by {@link Item#notifyWindows()}.
+         *
+         * @param itemProvider The function that resolves the {@link ItemProvider}.
+         * @return This builder.
+         */
         S setItemProvider(Function<Player, ItemProvider> itemProvider);
 
+        /**
+         * Configures the {@link Item} to automatically cycle through a given array of {@link ItemProvider ItemProviders}.
+         *
+         * @param period        The period in ticks between each cycle.
+         * @param itemProvider  The first {@link ItemProvider}.
+         * @param itemProviders The rest of the {@link ItemProvider ItemProviders}.
+         * @return This builder.
+         */
         default S setCyclingItemProvider(int period, ItemProvider itemProvider, ItemProvider... itemProviders) {
             return setCyclingItemProvider(period, List.of(ArrayUtils.concat(ItemProvider[]::new, itemProvider, itemProviders)));
         }
 
+        /**
+         * Configures the {@link Item} to automatically cycle through a given list of {@link ItemProvider ItemProviders}.
+         *
+         * @param period        The period in ticks between each cycle.
+         * @param itemProviders The {@link ItemProvider ItemProviders}.
+         * @return This builder.
+         */
         S setCyclingItemProvider(int period, List<? extends ItemProvider> itemProviders);
 
+        /**
+         * Configures the resulting {@link Item} to resolve the {@link ItemProvider} set via {@link #setItemProvider(Function)}
+         * asynchronously. Once resolved, the {@link ItemProvider} will stay like this and the function will never be called again.
+         * (Not even when calling {@link Item#notifyWindows()})
+         *
+         * @param placeholder The {@link ItemProvider} to display while the actual {@link ItemProvider} is being resolved.
+         * @return This builder.
+         */
         S async(ItemProvider placeholder);
 
+        /**
+         * Configures the resulting to automatically call {@link #notifyWindows()} every period ticks, while it is
+         * being displayed in a {@link Window}.
+         *
+         * @param period The period in ticks between each update.
+         * @return This builder.
+         */
         S updatePeriodically(long period);
 
+        /**
+         * Configures the resulting {@link Item} to automatically call {@link #notifyWindows()} when it is clicked.
+         *
+         * @return This builder.
+         */
         S updateOnClick();
 
+        /**
+         * Adds a click handler that is called when the {@link Item} is clicked.
+         *
+         * @param clickHandler The click handler, receiving the {@link Item} itself and the {@link Click}.
+         * @return This builder.
+         */
         S addClickHandler(BiConsumer<Item, Click> clickHandler);
 
+        /**
+         * Adds a modifier that is run on the {@link Item} when it is being built.
+         *
+         * @param modifier The modifier.
+         * @return This builder.
+         */
         S addModifier(Consumer<Item> modifier);
 
+        /**
+         * Builds the {@link Item}.
+         *
+         * @return The {@link Item}.
+         */
         Item build();
 
     }

invui/src/main/java/xyz/xenondevs/invui/util/ColorPalette.java

@@ -6,6 +6,9 @@
 import java.io.IOException;
 import java.io.InputStream;
 
+/**
+ * Utility for converting images into the color space used by maps in Minecraft.
+ */
 public class ColorPalette {
 
     private static final byte[] colorCache;

invui/src/main/java/xyz/xenondevs/invui/util/ItemUtils.java

@@ -4,6 +4,9 @@
 import org.bukkit.inventory.ItemStack;
 import org.jspecify.annotations.Nullable;
 
+/**
+ * Generic item-related utilities.
+ */
 public class ItemUtils {
 
     /**

invui/src/main/java/xyz/xenondevs/invui/util/TriConsumer.java

@@ -1,10 +1,30 @@
 package xyz.xenondevs.invui.util;
 
+/**
+ * A functional interface that takes three arguments and returns no result.
+ *
+ * @param <A> The first argument type
+ * @param <B> The second argument type
+ * @param <C> The third argument type
+ */
 @FunctionalInterface
 public interface TriConsumer<A, B, C> {
 
+    /**
+     * Performs this operation on the given arguments.
+     *
+     * @param a The first operand
+     * @param b The second operand
+     * @param c The third operand
+     */
     void accept(A a, B b, C c);
 
+    /**
+     * Returns a composed {@code TriConsumer} that performs, in sequence, this operation followed by the {@code after} operation.
+     *
+     * @param after The operation to perform after this operation
+     * @return A composed {@code TriConsumer} that performs in sequence this operation followed by the {@code after} operation
+     */
     default TriConsumer<A, B, C> andThen(TriConsumer<? super A, ? super B, ? super C> after) {
         return (a, b, c) -> {
             accept(a, b, c);