Overhaul documentation and add javaDoc task (#26)

* Add java doc tasks

* Add or improve documentation

* Overhaul phase documentation

* Small documentation adjustments

* Add constructor documentation

Add constructor documentation

* Remove generic comment

* Add missing documentation

* Documentation changes

* Improve parameter documentation

* Improve constructor documentation

* Fix typo in documentation

---------

Co-authored-by: theEvilReaper <[email protected]>

Author: theEvilReaper

build.gradle.kts

@@ -13,6 +13,8 @@ java {
     toolchain {
         languageVersion.set(JavaLanguageVersion.of(21))
     }
+    withJavadocJar()
+    withSourcesJar()
 }
 
 dependencies {

src/main/java/net/theevilreaper/xerus/api/ColorData.java

@@ -7,8 +7,8 @@
 import org.jetbrains.annotations.NotNull;
 
 /**
- * The class combines all colors of DyeColor, ChatColor and the wool blocks into enum values.
- * So for each color you have all the matching values.
+ * Represents a mapping of visual color variants using text color, dye color, block material, and a string identifier.
+ * Each constant aligns with a specific base color and can be used to harmonize visual elements across different systems.
  *
  * @author theEvilReaper
  * @version 1.5.0
@@ -17,24 +17,53 @@
 @SuppressWarnings("java:S3252")
 public enum ColorData {
 
+    /** Aligns with the aqua color. */
     AQUA(NamedTextColor.AQUA, DyeColor.LIGHT_BLUE, Material.LIGHT_BLUE_WOOL, "colorAqua"),
+
+    /** Aligns with the dark aqua color. */
     DARK_AQUA(NamedTextColor.DARK_AQUA, DyeColor.CYAN, Material.CYAN_WOOL, "colorCyan"),
+
+    /** Aligns with the black color. */
     BLACK(NamedTextColor.BLACK, DyeColor.BLACK, Material.BLACK_WOOL, "colorBlack"),
+
+    /** Aligns with the blue color. */
     BLUE(NamedTextColor.BLUE, DyeColor.LIGHT_BLUE, Material.BLUE_WOOL, "colorBlue"),
+
+    /** Aligns with the dark blue color. */
     DARK_BLUE(NamedTextColor.DARK_BLUE, DyeColor.BLUE, Material.BLUE_WOOL, "colorDarkBlue"),
+
+    /** Aligns with the brown/gold color. */
     GOLD(NamedTextColor.GOLD, DyeColor.ORANGE, Material.ORANGE_WOOL, "colorOrange"),
+
+    /** Aligns with the gray color. */
     GRAY(NamedTextColor.GRAY, DyeColor.GRAY, Material.LIGHT_GRAY_WOOL, "colorLightGray"),
+
+    /** Aligns with the dark gray color. */
     DARK_GREY(NamedTextColor.DARK_GRAY, DyeColor.GRAY, Material.GRAY_WOOL, "colorDarkGray"),
+
+    /** Aligns with the green color. */
     GREEN(NamedTextColor.DARK_GREEN, DyeColor.GREEN, Material.GREEN_WOOL, "colorGreen"),
+
+    /** Aligns with the light green color. */
     LIGHT_GREEN(NamedTextColor.GREEN, DyeColor.LIME, Material.LIME_WOOL, "colorLime"),
+
+    /** Aligns with the purple color. */
     PURPLE(NamedTextColor.DARK_PURPLE, DyeColor.PURPLE, Material.PURPLE_WOOL, "colorPurple"),
+
+    /** Aligns with the light purple color. */
     LIGHT_PURPLE(NamedTextColor.LIGHT_PURPLE, DyeColor.MAGENTA, Material.MAGENTA_WOOL, "colorMagenta"),
+
+    /** Aligns with the red color. */
     RED(NamedTextColor.RED, DyeColor.RED, Material.RED_WOOL, "colorRed"),
+
+    /** Aligns with the dark red color. */
     DARK_RED(NamedTextColor.DARK_RED, DyeColor.RED, Material.RED_WOOL, "colorDarkRed"),
+
+    /** Aligns with the yellow color. */
     YELLOW(NamedTextColor.YELLOW, DyeColor.YELLOW, Material.YELLOW_WOOL, "colorYellow"),
-    WHITE(NamedTextColor.WHITE, DyeColor.WHITE, Material.WHITE_WOOL, "colorWhite")
 
-    ;
+    /** Aligns with the white color. */
+    WHITE(NamedTextColor.WHITE, DyeColor.WHITE, Material.WHITE_WOOL, "colorWhite");
 
     //Reduce defensive copies from the array, because values() returns each call a new array!
     private static final ColorData[] VALUES = values();
@@ -111,7 +140,7 @@ public enum ColorData {
 
     /**
      * Returns an array which contains all given color data values.
-     * Please use this method because its reduce defensive copies from the array,
+     * Please use this method because it reduces defensive copies from the array,
      * because values() returns each call a new array!
      *
      * @return an array with the color data values

src/main/java/net/theevilreaper/xerus/api/event/GameFinishEvent.java

@@ -5,17 +5,10 @@
 
 /**
  * This event signals the end of a game when a specific defined condition is met.
- * The event supports various end-game conditions through a generic structure (<T>).
+ * The event supports various end-game conditions through a generic structure.
  * If the game has a more advanced use case, this event can be extended by other classes.
- * Example usage:
- * Suppose you have a game with a custom end-game condition involving player scores.
- * You can create a subclass of this event as follows:
- * {@code
- * public class CustomGameEndEvent extends GameEndEvent<CustomGameData> {
- * // Additional customizations for your game's end event
- * }
- * <p>
- * @param <T> The generic structure representing the end-game condition data
+ *
+ * @param <T> the type of the end-game condition
  * @author theEvilReaper
  * @version 1.0.0
  * @since 1.2.0

src/main/java/net/theevilreaper/xerus/api/kit/ArmorSlot.java

@@ -4,24 +4,47 @@
 import org.jetbrains.annotations.NotNull;
 
 /**
+ * The {@link ArmorSlot} enum contains all available armor slots.
+ *
  * @author theEvilReaper
  * @version 1.0.0
  * @since 1.2.0
  **/
 public enum ArmorSlot {
 
-    BOOTS(EquipmentSlot.BOOTS),
-    LEGGINGS(EquipmentSlot.LEGGINGS),
+    /**
+     * Represents the helmet slot.
+     */
+    HELMET(EquipmentSlot.HELMET),
+    /**
+     * Represents the chestplate slot.
+     */
     CHESTPLATE(EquipmentSlot.CHESTPLATE),
-    HELMET(EquipmentSlot.HELMET);
+    /**
+     * Represents the legging's slot.
+     */
+    LEGGINGS(EquipmentSlot.LEGGINGS),
+    /**
+     * Represents the boots slot.
+     */
+    BOOTS(EquipmentSlot.BOOTS);
 
     final EquipmentSlot slot;
 
+    /**
+     * Creates a new {@link ArmorSlot} with the given equipment slot.
+     * @param slot the equipment slot to use.
+     */
     ArmorSlot(@NotNull EquipmentSlot slot) {
         this.slot = slot;
     }
 
-    public EquipmentSlot getSlot() {
+    /**
+     * Returns the underlying equipment slot.
+     *
+     * @return the slot
+     */
+    public @NotNull EquipmentSlot getSlot() {
         return slot;
     }
 }

src/main/java/net/theevilreaper/xerus/api/kit/BaseKit.java

@@ -10,6 +10,9 @@
 import static net.minestom.server.inventory.PlayerInventory.INVENTORY_SIZE;
 
 /**
+ * The {@link BaseKit} is an abstract layer implementation of the {@link Kit} interface.
+ * It contains the general structure of a kit and can be used to define custom implementations.
+ *
  * @author theEvilReaper
  * @version 1.0.0
  * @since 1.2.0
@@ -20,42 +23,63 @@ public abstract class BaseKit implements Kit {
     protected EnumMap<ArmorSlot, IItem> armorItems;
     protected IItem[] items;
 
+    /**
+     * Creates a new instance of the {@link BaseKit}.
+     *
+     * @param armorItems whether the kit should contain armor items
+     */
     protected BaseKit(boolean armorItems) {
         this.items = new IItem[INVENTORY_SIZE];
         if (armorItems) {
             this.armorItems = new EnumMap<>(ArmorSlot.class);
         }
     }
 
+    /**
+     * {@inheritDoc}}
+     */
     @Override
     public void setArmorItem(@NotNull ArmorSlot slot, @NotNull IItem item) {
         this.armorItems.put(slot, item);
     }
 
+    /**
+     * {@inheritDoc}}
+     */
     @Override
     public void setArmorItems(@NotNull EnumMap<ArmorSlot, IItem> armorItems) {
         this.armorItems = armorItems;
     }
 
+    /**
+     * {@inheritDoc}}
+     */
     @Override
     public void setItem(int index, @NotNull IItem item) {
-        Check.argCondition(index > items.length,  "The index is to high");
+        Check.argCondition(index > items.length, "The index is to high");
         items[index] = item;
     }
 
+    /**
+     * {@inheritDoc}}
+     */
     @Override
     public void setItems(IItem[] items) {
         Check.argCondition(items.length != this.items.length, "The given array has not the same index (" + INVENTORY_SIZE + ")");
         this.items = items;
     }
 
+    /**
+     * {@inheritDoc}}
+     */
     @Override
     public void setIcon(@NotNull IItem icon) {
         this.icon = icon;
     }
 
     /**
      * Returns the underlying icon from the kit.
+     *
      * @return The underlying icon which is an object from {@link IItem}
      */
     @Override

src/main/java/net/theevilreaper/xerus/api/kit/Kit.java

@@ -12,19 +12,25 @@
 import java.util.Locale;
 
 /**
+ * The {@link Kit} interface provides all basic methods that a kit should have.
+ *
  * @author theEvilReaper
  * @version 1.0.0
  * @since 1.2.0
  **/
 public interface Kit extends ItemShiftOption {
 
+    /**
+     * The maximum number of armor items that can be set.
+     */
     int MAX_ARMOR_ITEMS = 4;
 
     /**
      * Creates a new instance of the kit.
-     * @param name The name of the kit
+     *
+     * @param name       The name of the kit
      * @param armorItems Whether the kit should contain armor items
-     * @return The created instance
+     * @return the created instance
      */
     @Contract(value = "_, _ -> new", pure = true)
     static @NotNull KitImpl of(@NotNull Component name, boolean armorItems) {
@@ -33,69 +39,85 @@ public interface Kit extends ItemShiftOption {
 
     /**
      * Set the icon for the kit.
+     *
      * @param item the item to set
      */
     void setIcon(@NotNull IItem item);
 
     /**
      * Add an item to a specific position in the array for the armor items.
+     *
      * @param slot The index where the item should be set
      * @param item The item to set
      */
     void setArmorItem(@NotNull ArmorSlot slot, @NotNull IItem item);
 
     /**
      * Set the armor items directly per array.
+     *
      * @param items The items to set
      */
     void setArmorItems(@NotNull EnumMap<ArmorSlot, IItem> items);
 
     /**
      * Add an item to a specific position in the array for the hotBar items.
+     *
      * @param index The index where the item should be set
-     * @param item The item to set
+     * @param item  The item to set
      */
     void setItem(int index, @NotNull IItem item);
 
     /**
      * Set all hotbar items directly per array.
+     *
      * @param items The items to set
      */
     void setItems(@NotNull IItem... items);
 
     /**
      * Returns the identifier of the kit.
+     *
      * @return the underlying value
      */
     String getIdentifier();
 
     /**
      * Gets the name of the kit.
+     *
      * @return the underlying value
      */
-    default Component getName() { return getName(null); }
+    default Component getName() {
+        return getName(null);
+    }
 
     /**
-     * Returns the name of the kit.
+     * Returns the name of the kit depending on the given locale as a {@link Component}.
+     *
+     * @param locale The locale to determine the right name
      * @return the underlying value
      */
     Component getName(@UnknownNullability Locale locale);
 
     /**
      * Returns the description from the kit.
+     *
      * @return the underlying value
      */
-    default Component getDescription() { return getDescription(null); }
+    default Component getDescription() {
+        return getDescription(null);
+    }
 
     /**
      * Returns the description from the kit.
+     *
      * @param locale The locale to determine the right description
      * @return The underlying value
      */
     Component getDescription(@UnknownNullability Locale locale);
 
     /**
      * Returns the icon from the kit.
+     *
      * @return the underlying value
      */
     @Nullable