Add api version to javadocs and fix minor formating

Author: benwoo1110

src/main/java/org/mvplugins/multiverse/inventories/profile/InventoryDataProvider.java

@@ -4,6 +4,7 @@
 import org.bukkit.OfflinePlayer;
 import org.bukkit.entity.Player;
 import org.bukkit.inventory.ItemStack;
+import org.jetbrains.annotations.ApiStatus;
 import org.jvnet.hk2.annotations.Service;
 import org.mvplugins.multiverse.external.jakarta.inject.Inject;
 import org.mvplugins.multiverse.external.jetbrains.annotations.NotNull;
@@ -25,7 +26,10 @@
 /**
  * Provides methods for asynchronously loading player inventory data.
  * This class encapsulates the business logic for fetching inventory, armor, and off-hand contents.
+ *
+ * @since 5.2
  */
+@ApiStatus.AvailableSince("5.2")
 @Service
 public final class InventoryDataProvider {
 
@@ -43,14 +47,28 @@ public InventoryDataProvider(
 
     /**
      * Represents the loaded inventory data.
+     *
+     * @since 5.2
      */
+    @ApiStatus.AvailableSince("5.2")
     public static class PlayerInventoryData {
         public final ItemStack[] contents;
         public final ItemStack[] armor;
         public final ItemStack offHand;
         public final String statusMessage; // To indicate if it's live or stored data
         public final ProfileType profileTypeUsed; // To pass back which profile type was used for stored data
 
+        /**
+         *
+         * @param contents
+         * @param armor
+         * @param offHand
+         * @param statusMessage
+         * @param profileTypeUsed
+         *
+         * @since 5.2
+         */
+        @ApiStatus.AvailableSince("5.2")
         public PlayerInventoryData(ItemStack[] contents, ItemStack[] armor, ItemStack offHand, String statusMessage, ProfileType profileTypeUsed) {
             this.contents = contents;
             this.armor = armor;
@@ -68,7 +86,10 @@ public PlayerInventoryData(ItemStack[] contents, ItemStack[] armor, ItemStack of
      * @param targetPlayer The OfflinePlayer whose inventory data to load.
      * @param worldName The name of the world to load the inventory from (either live or stored).
      * @return A CompletableFuture that will complete with PlayerInventoryData or an exception.
+     *
+     * @since 5.2
      */
+    @ApiStatus.AvailableSince("5.2")
     public CompletableFuture<PlayerInventoryData> loadPlayerInventoryData(
             @NotNull OfflinePlayer targetPlayer,
             @NotNull String worldName
@@ -135,7 +156,6 @@ public CompletableFuture<PlayerInventoryData> loadPlayerInventoryData(
             });
         }
 
-
     /**
      * Asynchronously saves a player's inventory data to their Multiverse-Inventories profile.
      * If the player is online and in the target world, their live inventory is also updated.
@@ -147,7 +167,10 @@ public CompletableFuture<PlayerInventoryData> loadPlayerInventoryData(
      * @param newArmor The new armor contents (helmet, chestplate, leggings, boots).
      * @param newOffHand The new off-hand item.
      * @return A CompletableFuture that completes when saving is done, or an exception occurs.
+     *
+     * @since 5.2
      */
+    @ApiStatus.AvailableSince("5.2")
     public CompletableFuture<Void> savePlayerInventoryData(
             @NotNull OfflinePlayer targetPlayer,
             @NotNull String worldName,
@@ -198,4 +221,4 @@ public CompletableFuture<Void> savePlayerInventoryData(
             return null;
         });
     }
-}
+}

src/main/java/org/mvplugins/multiverse/inventories/view/InventoryGUIHelper.java

@@ -7,6 +7,7 @@
 import org.bukkit.inventory.ItemStack;
 import org.bukkit.inventory.meta.ItemMeta;
 import org.bukkit.persistence.PersistentDataType;
+import org.jetbrains.annotations.ApiStatus;
 import org.jetbrains.annotations.NotNull;
 import org.jvnet.hk2.annotations.Service;
 import org.mvplugins.multiverse.external.jakarta.inject.Inject;
@@ -17,7 +18,10 @@
 /**
  * A helper class for creating and validating items within the custom inventory GUIs.
  * This centralizes logic for filler items and slot-specific item validation.
+ *
+ * @since 5.2
  */
+@ApiStatus.AvailableSince("5.2")
 @Service
 public final class InventoryGUIHelper {
 
@@ -27,13 +31,18 @@ public final class InventoryGUIHelper {
     public InventoryGUIHelper(@NotNull MultiverseInventories inventories) {
         this.IS_FILLER_KEY = new NamespacedKey(inventories, "is_mvinv_filler");
     }
+
     /**
      * Creates a generic filler item for GUI slots.
+     *
      * @param material The material of the filler item.
      * @param name The display name of the item.
      * @param lore The lore text for the item.
      * @return The created ItemStack.
+     *
+     * @since 5.2
      */
+    @ApiStatus.AvailableSince("5.2")
     public ItemStack createFillerItem(Material material, String name, String lore) {
         ItemStack item = new ItemStack(material);
         ItemMeta meta = item.getItemMeta();
@@ -48,9 +57,13 @@ public ItemStack createFillerItem(Material material, String name, String lore) {
 
     /**
      * Checks if a given ItemStack is a filler item created by this helper.
+     *
      * @param item The ItemStack to check.
      * @return True if the item is a filler, false otherwise.
+     *
+     * @since 5.2
      */
+    @ApiStatus.AvailableSince("5.2")
     public boolean isFillerItem(@NotNull ItemStack item) {
         if (!item.hasItemMeta()) {
             return false;
@@ -62,10 +75,14 @@ public boolean isFillerItem(@NotNull ItemStack item) {
     /**
      * Determines if an ItemStack is valid for a given special inventory slot in the custom GUI.
      * This method is used for both armor and off-hand slot validation.
+     *
      * @param item The ItemStack to check.
      * @param slot The raw slot number (36-40 for armor/off-hand).
      * @return True if the item is valid for the slot, false otherwise.
+     *
+     * @since 5.2
      */
+    @ApiStatus.AvailableSince("5.2")
     public boolean isValidItemForSlot(@NotNull ItemStack item, int slot) {
         if (item.getType() == Material.AIR) {
             return true; // Air is always valid (it means the slot is empty)
@@ -101,9 +118,13 @@ public boolean isValidItemForSlot(@NotNull ItemStack item, int slot) {
 
     /**
      * Creates the appropriate filler item for a given special slot in the custom GUI.
+     *
      * @param slot The raw slot number (36-40).
      * @return The specific filler ItemStack for that slot.
+     *
+     * @since 5.2
      */
+    @ApiStatus.AvailableSince("5.2")
     public ItemStack createFillerItemForSlot(int slot) {
         switch (slot) {
             case 36: return createFillerItem(Material.GRAY_STAINED_GLASS_PANE, "Helmet Slot", "Place Helmet Here");

src/main/java/org/mvplugins/multiverse/inventories/view/ModifiableInventoryHolder.java

@@ -3,6 +3,7 @@
 import org.bukkit.OfflinePlayer;
 import org.bukkit.inventory.Inventory;
 import org.bukkit.inventory.InventoryHolder;
+import org.jetbrains.annotations.ApiStatus;
 import org.jetbrains.annotations.NotNull;
 import org.mvplugins.multiverse.inventories.MultiverseInventories;
 import org.mvplugins.multiverse.inventories.profile.key.ProfileType;
@@ -11,13 +12,26 @@
  * A custom InventoryHolder that serves as a marker for modifiable inventories.
  * It stores the necessary context (player, world, profile type, plugin instance)
  * to save changes back to the player's profile when the inventory is closed.
+ *
+ * @since 5.2
  */
+@ApiStatus.AvailableSince("5.2")
 public final class ModifiableInventoryHolder implements InventoryHolder {
     private final OfflinePlayer targetPlayer;
     private final String worldName;
     private final ProfileType profileType;
     private final MultiverseInventories inventories;
 
+    /**
+     *
+     * @param targetPlayer
+     * @param worldName
+     * @param profileType
+     * @param inventories
+     *
+     * @since 5.2
+     */
+    @ApiStatus.AvailableSince("5.2")
     public ModifiableInventoryHolder(@NotNull OfflinePlayer targetPlayer,
                                      @NotNull String worldName,
                                      @NotNull ProfileType profileType,
@@ -28,26 +42,57 @@ public ModifiableInventoryHolder(@NotNull OfflinePlayer targetPlayer,
         this.inventories = inventories;
     }
 
+    /**
+     *
+     * @return
+     *
+     * @since 5.2
+     */
+    @ApiStatus.AvailableSince("5.2")
     public @NotNull OfflinePlayer getTargetPlayer() {
         return targetPlayer;
     }
 
+    /**
+     *
+     * @return
+     *
+     * @since 5.2
+     */
+    @ApiStatus.AvailableSince("5.2")
     public @NotNull String getWorldName() {
         return worldName;
     }
 
+    /**
+     *
+     * @return
+     *
+     * @since 5.2
+     */
+    @ApiStatus.AvailableSince("5.2")
     public @NotNull ProfileType getProfileType() {
         return profileType;
     }
 
+    /**
+     *
+     * @return
+     *
+     * @since 5.2
+     */
+    @ApiStatus.AvailableSince("5.2")
     public @NotNull MultiverseInventories getInventories() {
         return inventories;
     }
 
+    /**
+     * {@inheritDoc}
+     */
     @Override
     public @NotNull Inventory getInventory() {
         // This method is required by the interface but is not directly used for the marker purpose.
         // Throwing UnsupportedOperationException clearly indicates it's not meant to be called.
         throw new UnsupportedOperationException("ModifiableInventoryHolder does not provide an Inventory directly.");
     }
-}
+}

src/main/java/org/mvplugins/multiverse/inventories/view/ReadOnlyInventoryHolder.java

@@ -2,18 +2,24 @@
 
 import org.bukkit.inventory.Inventory;
 import org.bukkit.inventory.InventoryHolder;
+import org.jetbrains.annotations.ApiStatus;
 import org.jetbrains.annotations.NotNull;
 
 /**
  * A custom InventoryHolder that serves as a marker for read-only inventories.
  * Inventories created with this holder will have their interactions cancelled by the InventoryViewListener.
+ *
+ * @since 5.2
  */
+@ApiStatus.AvailableSince("5.2")
 public final class ReadOnlyInventoryHolder implements InventoryHolder {
-
+    /**
+     * {@inheritDoc}
+     */
     @Override
     public @NotNull Inventory getInventory() {
         // This method is required by the interface but is not directly used for the marker purpose.
         // Throwing UnsupportedOperationException clearly indicates it's not meant to be called.
         throw new UnsupportedOperationException("ReadOnlyInventoryHolder does not provide an Inventory directly.");
     }
-}
+}