Improved Javadoc and parameter handling in banking APIs

Enhanced descriptions for method parameters, added `@apiNote` annotations for clarity, and standardized return value formatting with `{@code}`. Updated references to `uuid` instead of `UUID`. Improved consistency in `Account` API behavior with `BigDecimal.ZERO` returns for unsupported operations.

Author: NonSwag

src/main/java/net/thenextlvl/service/api/economy/Account.java

@@ -17,6 +17,8 @@
 public interface Account {
     /**
      * Deposits the specified amount of the given currency into the account balance.
+     * <p>
+     * Returns {@link BigDecimal#ZERO} if {@link #canHold(Currency)} returns {@code false}
      *
      * @param amount   the amount to be deposited
      * @param currency the currency that is being deposited
@@ -38,6 +40,8 @@ default BigDecimal deposit(Number amount, Currency currency) {
 
     /**
      * Withdraws the specified amount of the given currency from the account balance.
+     * <p>
+     * Returns {@link BigDecimal#ZERO} if {@link #canHold(Currency)} returns {@code false}
      *
      * @param amount   the amount to be withdrawn
      * @param currency the currency in which the withdrawal is to be made
@@ -49,16 +53,16 @@ default BigDecimal withdraw(Number amount, Currency currency) {
     }
 
     /**
-     * Returns an optional containing the world associated with this account.
+     * Returns the world associated with this account.
      *
-     * @return an {@code Optional<World>} containing the world associated with this account, or empty
+     * @return an optional containing the world associated with this account, or empty
      */
     Optional<World> getWorld();
 
     /**
-     * Returns the UUID of the owner of this account.
+     * Returns the account owner's uuid.
      *
-     * @return the UUID of the owner
+     * @return the account owner's uuid
      */
     UUID getOwner();
 
@@ -77,10 +81,13 @@ default int compareTo(Account account, Currency currency) {
 
     /**
      * Sets the balance of the account to the specified value in the given currency.
+     * <p>
+     * Returns {@link BigDecimal#ZERO} if {@link #canHold(Currency)} returns {@code false}
      *
      * @param balance  the new balance to be set
      * @param currency the currency of the balance
      * @return the new balance after the operation
+     * @see #canHold(Currency)
      * @since 3.0.0
      */
     BigDecimal setBalance(Number balance, Currency currency);

src/main/java/net/thenextlvl/service/api/economy/bank/Bank.java

@@ -1,6 +1,7 @@
 package net.thenextlvl.service.api.economy.bank;
 
 import net.thenextlvl.service.api.economy.Account;
+import net.thenextlvl.service.api.economy.currency.Currency;
 import org.bukkit.OfflinePlayer;
 import org.jetbrains.annotations.Contract;
 import org.jetbrains.annotations.Unmodifiable;
@@ -13,7 +14,7 @@
  * The Bank interface represents a financial entity that can be owned and hold members.
  * It extends the Account interface, providing additional functionality specific
  * to banking, such as depositing or withdrawing money.
- * 
+ *
  * @since 1.0.0
  */
 @NullMarked
@@ -22,6 +23,7 @@ public interface Bank extends Account {
      * Retrieves a set of UUIDs representing the members of the bank.
      *
      * @return an unmodifiable set containing the UUIDs of the members.
+     * @apiNote does not contain the uuid of the owner
      */
     @Unmodifiable
     Set<UUID> getMembers();
@@ -37,8 +39,8 @@ public interface Bank extends Account {
     /**
      * Adds a member to the bank.
      *
-     * @param player the OfflinePlayer object representing the player to be added as a member
-     * @return true if the player was successfully added as a member, false otherwise
+     * @param player the player to be added as a member
+     * @return {@code true} if the player was successfully added as a member, otherwise {@code false}
      */
     default boolean addMember(OfflinePlayer player) {
         return addMember(player.getUniqueId());
@@ -47,62 +49,64 @@ default boolean addMember(OfflinePlayer player) {
     /**
      * Adds a member to the bank.
      *
-     * @param uuid the UUID of the member to be added
-     * @return true if the member was successfully added, false otherwise
+     * @param uuid the uuid of the member to be added
+     * @return {@code true} if the member was successfully added, otherwise {@code false}
      */
     boolean addMember(UUID uuid);
 
     /**
      * Checks if the specified player is a member of the bank.
      *
-     * @param player the OfflinePlayer object representing the player to check for membership
-     * @return true if the player is a member of the bank, false otherwise
+     * @param player the player to check for membership
+     * @return {@code true} if the player is a member of the bank, otherwise {@code false}
+     * @apiNote returns {@code false} on the owner
      */
     default boolean isMember(OfflinePlayer player) {
         return isMember(player.getUniqueId());
     }
 
     /**
-     * Checks if the specified UUID is associated with a member of the bank.
+     * Checks if the specified uuid is associated with a member of the bank.
      *
-     * @param uuid the UUID of the member to check for membership
-     * @return true if the UUID corresponds to a member of the bank, false otherwise
+     * @param uuid the uuid of the member to check for membership
+     * @return {@code true} if the uuid corresponds to a member of the bank, otherwise {@code false}
+     * @apiNote returns {@code false} on the owner
      */
     boolean isMember(UUID uuid);
 
     /**
      * Removes a member from the bank.
      *
-     * @param player the OfflinePlayer object representing the player to be removed as a member
-     * @return true if the member was successfully removed, false otherwise
+     * @param player the player to be removed as a member
+     * @return {@code true} if the member was successfully removed, otherwise {@code false}
      */
     default boolean removeMember(OfflinePlayer player) {
         return removeMember(player.getUniqueId());
     }
 
     /**
-     * Removes a member from the bank using the specified UUID.
+     * Removes a member from the bank using the specified uuid.
      *
-     * @param uuid the UUID of the member to be removed
-     * @return true if the member was successfully removed, false otherwise
+     * @param uuid the uuid of the member to be removed
+     * @return {@code true} if the member was successfully removed, otherwise {@code false}
      */
     boolean removeMember(UUID uuid);
 
     /**
-     * Sets the specified OfflinePlayer as the owner of the bank.
+     * Sets the specified player as the owner of the bank.
      *
-     * @param player the OfflinePlayer object representing the player to be set as the owner
-     * @return true if the player was successfully set as the owner, false otherwise
+     * @param player the player to be set as the owner
+     * @return {@code true} if the player was successfully set as the owner, otherwise {@code false}
      */
     default boolean setOwner(OfflinePlayer player) {
         return setOwner(player.getUniqueId());
     }
 
     /**
-     * Sets the owner of the bank to the specified UUID.
+     * Sets the owner of the bank to the specified uuid.
      *
-     * @param uuid the UUID of the new owner
-     * @return true if the owner was successfully set, false otherwise
+     * @param uuid the uuid of the new owner
+     * @return {@code true} if the owner was successfully set, otherwise {@code false}
      */
     boolean setOwner(UUID uuid);
 }