add javadocs

Author: HSGamer

core/src/main/java/io/github/projectunified/craftitem/core/Item.java

@@ -2,10 +2,38 @@
 
 import java.util.UUID;
 
+/**
+ * Represents a generic item with name, amount, and ownership information.
+ *
+ * <p>This interface defines the core API for modifying item properties.
+ *
+ * <p><strong>Example Usage:</strong>
+ * <pre>{@code
+ * Item item = new SpigotItem(Material.DIAMOND_SWORD);
+ * item.setName("Legendary Sword");
+ * item.setAmount(1);
+ * UUID owner = item.getOwner();
+ * }</pre>
+ */
 public interface Item {
+    /**
+     * Sets the display name of the item.
+     *
+     * @param name the new display name for the item
+     */
     void setName(String name);
 
+    /**
+     * Sets the stack amount of the item.
+     *
+     * @param amount the stack size (typically 1-64)
+     */
     void setAmount(int amount);
 
+    /**
+     * Gets the UUID of the item's owner.
+     *
+     * @return the owner's UUID, or null if no owner is set
+     */
     UUID getOwner();
 }

core/src/main/java/io/github/projectunified/craftitem/core/ItemModifier.java

@@ -2,6 +2,29 @@
 
 import java.util.function.UnaryOperator;
 
+/**
+ * Interface for applying modifications to items.
+ *
+ * <p>Implementations modify item properties using a string translator for dynamic value substitution.
+ * The translator allows for variable interpolation and custom value transformations.
+ *
+ * <p><strong>Example Implementation:</strong>
+ * <pre>{@code
+ * public class CustomModifier implements ItemModifier {
+ *     @Override
+ *     public void modify(Item item, UnaryOperator<String> translator) {
+ *         String translatedValue = translator.apply("${player_name}");
+ *         item.setName(translatedValue);
+ *     }
+ * }
+ * }</pre>
+ */
 public interface ItemModifier {
+    /**
+     * Applies modifications to the given item.
+     *
+     * @param item       the item to modify
+     * @param translator a function to translate string values (e.g., for variable substitution)
+     */
     void modify(Item item, UnaryOperator<String> translator);
 }

modifier/src/main/java/io/github/projectunified/craftitem/modifier/AmountModifier.java

@@ -5,21 +5,61 @@
 
 import java.util.function.UnaryOperator;
 
+/**
+ * Item modifier that sets the item's stack amount.
+ *
+ * <p>The amount can be provided as an integer, string, or defaults to 1.
+ * The string value is translated before parsing to support dynamic amounts.
+ *
+ * <p><strong>Example Usage:</strong>
+ * <pre>{@code
+ * // Direct integer amount
+ * ItemModifier modifier1 = new AmountModifier(64);
+ *
+ * // String amount with variables
+ * ItemModifier modifier2 = new AmountModifier("${stack_size}");
+ * modifier2.modify(item, s -> s.replace("${stack_size}", "32"));
+ *
+ * // Default amount of 1
+ * ItemModifier modifier3 = new AmountModifier();
+ * }</pre>
+ */
 public class AmountModifier implements ItemModifier {
     private final String amount;
 
+    /**
+     * Creates a new AmountModifier with the specified integer amount.
+     *
+     * @param amount the stack size
+     */
     public AmountModifier(int amount) {
         this.amount = Integer.toString(amount);
     }
 
+    /**
+     * Creates a new AmountModifier with the specified string amount.
+     * The string can contain variables for translation.
+     *
+     * @param amount the stack size as a string
+     */
     public AmountModifier(String amount) {
         this.amount = amount;
     }
 
+    /**
+     * Creates a new AmountModifier with a default amount of 1.
+     */
     public AmountModifier() {
         this.amount = "1";
     }
 
+    /**
+     * Applies the translated amount to the item.
+     * Invalid amounts are silently ignored.
+     *
+     * @param item       the item to modify
+     * @param translator the string translator for variable substitution
+     */
     @Override
     public void modify(Item item, UnaryOperator<String> translator) {
         String amount = translator.apply(this.amount);

modifier/src/main/java/io/github/projectunified/craftitem/modifier/NameModifier.java

@@ -5,13 +5,37 @@
 
 import java.util.function.UnaryOperator;
 
+/**
+ * Item modifier that sets the item's display name.
+ *
+ * <p>The provided name is passed through the translator before being applied to the item,
+ * allowing for variable substitution and dynamic name generation.
+ *
+ * <p><strong>Example Usage:</strong>
+ * <pre>{@code
+ * ItemModifier modifier = new NameModifier("Sword of ${owner}");
+ * modifier.modify(item, s -> s.replace("${owner}", "Player123"));
+ * // Item name becomes: "Sword of Player123"
+ * }</pre>
+ */
 public class NameModifier implements ItemModifier {
     private final String name;
 
+    /**
+     * Creates a new NameModifier with the specified name.
+     *
+     * @param name the display name (can contain variables for translation)
+     */
     public NameModifier(String name) {
         this.name = name;
     }
 
+    /**
+     * Applies the translated name to the item.
+     *
+     * @param item       the item to modify
+     * @param translator the string translator for variable substitution
+     */
     @Override
     public void modify(Item item, UnaryOperator<String> translator) {
         String name = translator.apply(this.name);

spigot/core/src/main/java/io/github/projectunified/craftitem/spigot/core/SpigotItem.java

@@ -8,56 +8,129 @@
 import java.util.UUID;
 import java.util.function.Consumer;
 
+/**
+ * Spigot-specific implementation of the Item interface.
+ * Wraps Bukkit's ItemStack and provides convenient modification methods.
+ *
+ * <p>Provides multiple constructors for flexibility and specialized methods
+ * for editing item metadata and the underlying ItemStack.
+ *
+ * <p><strong>Example Usage:</strong>
+ * <pre>{@code
+ * SpigotItem item = new SpigotItem(Material.DIAMOND_SWORD, playerUUID);
+ * item.setName("Legendary Sword");
+ * item.setAmount(1);
+ * item.editMeta(meta -> meta.setCustomModelData(1));
+ * ItemStack resultStack = item.getItemStack();
+ * }</pre>
+ */
 public class SpigotItem implements Item {
     private final UUID owner;
     private ItemStack itemStack;
 
+    /**
+     * Creates a new SpigotItem with the specified ItemStack and owner.
+     *
+     * @param itemStack the ItemStack to wrap (will be cloned)
+     * @param owner     the UUID of the item's owner, or null
+     */
     public SpigotItem(ItemStack itemStack, UUID owner) {
         this.owner = owner;
         this.itemStack = itemStack.clone();
     }
 
+    /**
+     * Creates a new SpigotItem with the specified ItemStack and no owner.
+     *
+     * @param itemStack the ItemStack to wrap (will be cloned)
+     */
     public SpigotItem(ItemStack itemStack) {
         this(itemStack, null);
     }
 
+    /**
+     * Creates a new SpigotItem with the specified Material type and owner.
+     *
+     * @param material the Material type for the new ItemStack
+     * @param owner    the UUID of the item's owner, or null
+     */
     public SpigotItem(Material material, UUID owner) {
         this.owner = owner;
         this.itemStack = new ItemStack(material);
     }
 
+    /**
+     * Creates a new SpigotItem with the specified Material type and no owner.
+     *
+     * @param material the Material type for the new ItemStack
+     */
     public SpigotItem(Material material) {
         this(material, null);
     }
 
+    /**
+     * Creates a new SpigotItem of STONE material with the specified owner.
+     *
+     * @param owner the UUID of the item's owner, or null
+     */
     public SpigotItem(UUID owner) {
         this.owner = owner;
         this.itemStack = new ItemStack(Material.STONE);
     }
 
+    /**
+     * Creates a new SpigotItem of STONE material with no owner.
+     */
     public SpigotItem() {
         this((UUID) null);
     }
 
+    /**
+     * Gets the underlying ItemStack.
+     *
+     * @return the ItemStack
+     */
     public ItemStack getItemStack() {
         return itemStack;
     }
 
+    /**
+     * Sets the underlying ItemStack (cloned to prevent external modifications).
+     *
+     * @param itemStack the new ItemStack
+     */
     public void setItemStack(ItemStack itemStack) {
         this.itemStack = itemStack.clone();
     }
 
+    /**
+     * Allows direct modification of the ItemStack.
+     *
+     * @param consumer the consumer to modify the ItemStack
+     */
     public void edit(Consumer<ItemStack> consumer) {
         consumer.accept(this.itemStack);
     }
 
+    /**
+     * Allows modification of the item's metadata.
+     *
+     * @param consumer the consumer to modify the ItemMeta
+     */
     public void editMeta(Consumer<ItemMeta> consumer) {
         ItemMeta meta = this.itemStack.getItemMeta();
         if (meta == null) return;
         consumer.accept(meta);
         this.itemStack.setItemMeta(meta);
     }
 
+    /**
+     * Allows type-safe modification of specific ItemMeta subclasses.
+     *
+     * @param <T>       the ItemMeta subclass type
+     * @param metaClass the class of the ItemMeta to modify
+     * @param consumer  the consumer to modify the metadata
+     */
     public <T extends ItemMeta> void editMeta(Class<T> metaClass, Consumer<T> consumer) {
         ItemMeta meta = this.itemStack.getItemMeta();
         if (meta == null) return;
@@ -66,16 +139,31 @@ public <T extends ItemMeta> void editMeta(Class<T> metaClass, Consumer<T> consum
         this.itemStack.setItemMeta(meta);
     }
 
+    /**
+     * Sets the display name of the item.
+     *
+     * @param name the new display name
+     */
     @Override
     public void setName(String name) {
         editMeta(itemMeta -> itemMeta.setDisplayName(name));
     }
 
+    /**
+     * Sets the stack amount of the item.
+     *
+     * @param amount the stack size
+     */
     @Override
     public void setAmount(int amount) {
         this.itemStack.setAmount(amount);
     }
 
+    /**
+     * Gets the UUID of the item's owner.
+     *
+     * @return the owner's UUID, or null if no owner
+     */
     @Override
     public UUID getOwner() {
         return owner;

spigot/core/src/main/java/io/github/projectunified/craftitem/spigot/core/SpigotItemModifier.java

@@ -5,7 +5,31 @@
 
 import java.util.function.UnaryOperator;
 
+/**
+ * Interface for Spigot-specific item modifications.
+ *
+ * <p>Extends ItemModifier to work specifically with SpigotItem instances.
+ * Provides type-safe modification methods while maintaining compatibility with the generic ItemModifier interface.
+ *
+ * <p><strong>Example Implementation:</strong>
+ * <pre>{@code
+ * public class CustomSpigotModifier implements SpigotItemModifier {
+ *     @Override
+ *     public void modify(SpigotItem item, UnaryOperator<String> translator) {
+ *         item.editMeta(meta -> {
+ *             meta.setCustomModelData(42);
+ *         });
+ *     }
+ * }
+ * }</pre>
+ */
 public interface SpigotItemModifier extends ItemModifier {
+    /**
+     * Applies Spigot-specific modifications to a SpigotItem.
+     *
+     * @param item       the SpigotItem to modify
+     * @param translator the string translator for variable substitution
+     */
     void modify(SpigotItem item, UnaryOperator<String> translator);
 
     @Override