1.1-SNAPSHOT

Updated javadocs

Author: Jan Kluka

src/main/java/dev/drawethree/xprison/api/currency/CurrencyType.java

@@ -1,5 +1,23 @@
 package dev.drawethree.xprison.api.currency;
 
+/**
+ * Represents the different types of currencies supported by the XPrison plugin.
+ * These currencies can be used for various in-game transactions, upgrades, and features.
+ */
 public enum CurrencyType {
-    GEMS,TOKENS,VAULT
+
+    /**
+     * Gems currency, typically used for high-tier or cosmetic purchases.
+     */
+    GEMS,
+
+    /**
+     * Tokens currency, often used for enchanting, upgrades, or mid-tier trades.
+     */
+    TOKENS,
+
+    /**
+     * Vault currency, representing stored or secured in-game balance.
+     */
+    VAULT
 }

src/main/java/dev/drawethree/xprison/api/enchants/XPrisonEnchantsAPI.java

@@ -1,30 +1,37 @@
 package dev.drawethree.xprison.api.enchants;
 
 import dev.drawethree.xprison.api.enchants.model.XPrisonEnchantment;
+import org.bukkit.Location;
 import org.bukkit.entity.Player;
+import org.bukkit.event.block.BlockBreakEvent;
 import org.bukkit.inventory.ItemStack;
 
 import java.util.Map;
 
 /**
- * API interface for managing custom enchantments on items.
+ * The {@code XPrisonEnchantsAPI} interface defines methods for interacting with and managing
+ * custom enchantments in the XPrison plugin. It provides utilities to query, modify, register,
+ * and remove custom enchantments on {@link ItemStack} objects as well as control enchantment-related
+ * behavior during block-breaking events.
+ *
+ * <p>This API is intended for developers who wish to interact with the XPrison enchantment system.
  */
 public interface XPrisonEnchantsAPI {
 
 	/**
 	 * Retrieves all custom enchantments applied to a specific item.
 	 *
-	 * @param itemStack The item to check.
+	 * @param itemStack The item to check for enchantments.
 	 * @return A map of {@link XPrisonEnchantment} to their respective levels on the item.
 	 */
 	Map<XPrisonEnchantment, Integer> getEnchants(ItemStack itemStack);
 
 	/**
-	 * Checks if an item has a specific enchantment.
+	 * Checks if an item has a specific enchantment applied.
 	 *
 	 * @param item        The item to check.
 	 * @param enchantment The enchantment to look for.
-	 * @return True if the item has the specified enchantment, false otherwise.
+	 * @return {@code true} if the item has the specified enchantment, {@code false} otherwise.
 	 */
 	boolean hasEnchant(ItemStack item, XPrisonEnchantment enchantment);
 
@@ -33,71 +40,86 @@ public interface XPrisonEnchantsAPI {
 	 *
 	 * @param item        The item to check.
 	 * @param enchantment The enchantment to look for.
-	 * @param level       The specific enchantment level.
-	 * @return True if the item has the specified enchantment at the given level, false otherwise.
+	 * @param level       The required level of the enchantment.
+	 * @return {@code true} if the item has the specified enchantment at the given level, {@code false} otherwise.
 	 */
 	boolean hasEnchant(ItemStack item, XPrisonEnchantment enchantment, int level);
 
 	/**
 	 * Gets the level of a specific enchantment on an item.
 	 *
-	 * @param item        The item to check.
-	 * @param enchantment The enchantment to retrieve the level for.
-	 * @return The level of the enchantment, or 0 if the enchantment is not present.
+	 * @param item        The item to inspect.
+	 * @param enchantment The enchantment whose level is to be retrieved.
+	 * @return The level of the enchantment, or {@code 0} if not present.
 	 */
 	int getEnchantLevel(ItemStack item, XPrisonEnchantment enchantment);
 
 	/**
-	 * Sets an enchantment with a specific level on an item.
+	 * Sets or updates a specific enchantment with a defined level on an item.
 	 *
 	 * @param player      The player applying the enchantment.
-	 * @param item        The item to enchant.
+	 * @param item        The item to be enchanted.
 	 * @param enchantment The enchantment to apply.
-	 * @param level       The level of the enchantment.
-	 * @return The modified item with the enchantment applied.
+	 * @param level       The level to set.
+	 * @return The modified {@link ItemStack} with the enchantment applied.
 	 */
 	ItemStack setEnchantLevel(Player player, ItemStack item, XPrisonEnchantment enchantment, int level);
 
 	/**
 	 * Removes a specific enchantment from an item.
 	 *
-	 * @param player      The player removing the enchantment.
+	 * @param player      The player performing the removal.
 	 * @param item        The item to modify.
 	 * @param enchantment The enchantment to remove.
-	 * @return The modified item with the enchantment removed.
+	 * @return The modified {@link ItemStack} with the enchantment removed.
 	 */
 	ItemStack removeEnchant(Player player, ItemStack item, XPrisonEnchantment enchantment);
 
 	/**
-	 * Retrieves an enchantment by its ID.
+	 * Retrieves a custom enchantment by its internal ID.
 	 *
-	 * @param id The ID of the enchantment.
-	 * @return The {@link XPrisonEnchantment} corresponding to the ID, or null if not found.
+	 * @param id The unique ID of the enchantment.
+	 * @return The corresponding {@link XPrisonEnchantment}, or {@code null} if not found.
 	 */
 	XPrisonEnchantment getById(int id);
 
 	/**
-	 * Retrieves an enchantment by its raw name.
+	 * Retrieves a custom enchantment by its raw (unformatted) name.
 	 *
 	 * @param rawName The raw name of the enchantment.
-	 * @return The {@link XPrisonEnchantment} corresponding to the name, or null if not found.
+	 * @return The corresponding {@link XPrisonEnchantment}, or {@code null} if not found.
 	 */
 	XPrisonEnchantment getByName(String rawName);
 
 	/**
-	 * Registers a new custom enchantment.
+	 * Registers a new custom enchantment to the system.
 	 *
 	 * @param enchantment The enchantment to register.
-	 * @return True if the enchantment was registered successfully, false otherwise.
+	 * @return {@code true} if registration was successful, {@code false} otherwise.
 	 */
 	boolean registerEnchant(XPrisonEnchantment enchantment);
 
 	/**
 	 * Unregisters an existing custom enchantment.
 	 *
 	 * @param enchantment The enchantment to unregister.
-	 * @return True if the enchantment was unregistered successfully, false otherwise.
+	 * @return {@code true} if unregistration was successful, {@code false} otherwise.
 	 */
 	boolean unregisterEnchant(XPrisonEnchantment enchantment);
 
+	/**
+	 * Prevents the specified {@link BlockBreakEvent} from triggering any enchantment logic.
+	 * Useful for temporary suppression of enchantment effects.
+	 *
+	 * @param event The block break event to ignore.
+	 */
+	void ignoreBlockBreakEvent(BlockBreakEvent event);
+
+	/**
+	 * Checks whether enchantments are allowed at a given {@link Location}.
+	 *
+	 * @param location The location to check.
+	 * @return {@code true} if enchantments are allowed, {@code false} otherwise.
+	 */
+	boolean isEnchantAllowed(Location location);
 }