Enhance API documentation and annotations across transaction modules

- Added concise, structured documentation for `transaction`, `account`, `currency`, and related APIs for improved clarity and usability.
- Applied `@ApiStatus.NonExtendable` to several interfaces to clarify usage restrictions.
- Updated and standardized parameter descriptions in transactional operations to ensure consistency.
- Improved type annotations and metadata for interfaces and result objects.

Author: twisti-dev

surf-transaction-api/src/main/kotlin/dev/slne/surf/transaction/api/account/Account.kt

@@ -5,27 +5,91 @@ import dev.slne.surf.transaction.api.account.result.AccountCreationResult
 import dev.slne.surf.transaction.api.transactional.Transactional
 import dev.slne.surf.transaction.api.util.InternalTransactionApi
 import net.kyori.adventure.text.Component
+import org.jetbrains.annotations.ApiStatus
 import java.util.*
 
+/**
+ * Represents an account within the transaction system.
+ *
+ * An [Account] holds balances for one or more currencies and supports
+ * transactional operations such as deposits, withdrawals, and transfers.
+ * It also provides member management via [AccountMemberOperations].
+ *
+ * Accounts are managed by the [AccountService] and should be accessed
+ * through the provided lookup and creation methods.
+ */
 @OptIn(InternalTransactionApi::class)
+@ApiStatus.NonExtendable
 interface Account : Transactional, AccountMemberOperations {
 
+    /**
+     * The unique identifier of this account.
+     */
     val accountId: UUID
+
+    /**
+     * The human-readable name of this account.
+     *
+     * The name length must be within [MIN_NAME_LENGTH] and [MAX_NAME_LENGTH].
+     */
     val name: String
+
+    /**
+     * The UUID of the account owner.
+     *
+     * The owner typically has full permissions on the account.
+     */
     val ownerUuid: UUID
+
+    /**
+     * Whether this account is the default account of its owner.
+     */
     val defaultAccount: Boolean
 
+    /**
+     * Returns a component representation of this account.
+     *
+     * This component is typically used for user-facing displays and may
+     * include formatting or additional contextual information.
+     *
+     * @return a display component representing this account
+     */
     suspend fun asComponent(): Component
 
     companion object {
+        /**
+         * The minimum allowed length of an account name.
+         */
         const val MIN_NAME_LENGTH = 3
+        /**
+         * The maximum allowed length of an account name.
+         */
         const val MAX_NAME_LENGTH = 32
 
+
+        /**
+         * Returns an account by its unique [accountId], or `null` if none exists.
+         *
+         * @param accountId the account identifier
+         */
         suspend fun byId(accountId: UUID): Account? =
             AccountService.instance.getAccountByAccountId(accountId)
 
+        /**
+         * Returns an account by its [name], or `null` if none exists.
+         *
+         * @param name the name of the account
+         */
         suspend fun byName(name: String): Account? = AccountService.instance.getAccountByName(name)
 
+        /**
+         * Creates a new account for the given [owner] with the specified [name].
+         *
+         * @param owner the UUID of the account owner
+         * @param name the name of the new account
+         *
+         * @return the result of the account creation attempt
+         */
         suspend fun create(
             owner: UUID,
             name: String

surf-transaction-api/src/main/kotlin/dev/slne/surf/transaction/api/account/AccountAccess.kt

@@ -3,16 +3,61 @@ package dev.slne.surf.transaction.api.account
 import dev.slne.surf.transaction.api.account.result.AccountCreationResult
 import dev.slne.surf.transaction.api.account.result.AccountDeleteResult
 import dev.slne.surf.transaction.api.util.InternalTransactionApi
+import org.jetbrains.annotations.ApiStatus
 import java.util.*
 
+/**
+ * Provides user-scoped access to account management operations.
+ *
+ * An [AccountAccess] instance represents the view of accounts belonging to a
+ * specific user and allows creating, retrieving, and deleting accounts owned
+ * by that user.
+ */
 @OptIn(InternalTransactionApi::class)
+@ApiStatus.NonExtendable
 interface AccountAccess {
 
+    /**
+     * The UUID of the user this access instance belongs to.
+     */
     val userUuid: UUID
+
+    /**
+     * Returns the default account of the user.
+     *
+     * @return the user's default account
+     */
     suspend fun getDefaultAccount(): Account
+
+    /**
+     * Returns all accounts owned by the user.
+     *
+     * @return a set of all user accounts
+     */
     suspend fun getAllAccounts(): Set<Account>
+
+    /**
+     * Creates a new account with the given [name] for the user.
+     *
+     * @param name the name of the account to create
+     * @return the result of the account creation attempt
+     */
     suspend fun createAccount(name: String): AccountCreationResult
+
+    /**
+     * Returns an account owned by the user with the given [accountName],
+     * or `null` if no such account exists.
+     *
+     * @param accountName the name of the account
+     */
     suspend fun getAccountByName(accountName: String): Account?
+
+    /**
+     * Deletes the given [account].
+     *
+     * @param account the account to delete
+     * @return the result of the account deletion attempt
+     */
     suspend fun deleteAccount(account: Account): AccountDeleteResult
 
 }

surf-transaction-api/src/main/kotlin/dev/slne/surf/transaction/api/account/AccountService.kt

@@ -5,10 +5,43 @@ import dev.slne.surf.transaction.api.account.result.AccountCreationResult
 import dev.slne.surf.transaction.api.util.InternalTransactionApi
 import java.util.*
 
+/**
+ * Internal service for managing accounts.
+ *
+ * [AccountService] is responsible for resolving, creating, and managing
+ * accounts within the transaction system. It is used internally by the
+ * account and transaction APIs.
+ *
+ * This API is strictly internal to the Surf Transaction module and must not
+ * be used by external consumers.
+ */
 @InternalTransactionApi
 interface AccountService {
+
+    /**
+     * Returns an account by its unique [accountId], or `null` if none exists.
+     *
+     * @param accountId the account identifier
+     * @return the resolved account or `null`
+     */
     suspend fun getAccountByAccountId(accountId: UUID): Account?
+
+    /**
+     * Returns an account by its [accountName], or `null` if none exists.
+     *
+     * @param accountName the name of the account
+     * @return the resolved account or `null`
+     */
     suspend fun getAccountByName(accountName: String): Account?
+
+    /**
+     * Creates a new account for the given owner.
+     *
+     * @param ownerUuid the UUID of the account owner
+     * @param name the name of the new account
+     *
+     * @return the result of the account creation attempt
+     */
     suspend fun createAccount(ownerUuid: UUID, name: String): AccountCreationResult
 
     companion object {

surf-transaction-api/src/main/kotlin/dev/slne/surf/transaction/api/account/member/AccountMemberOperations.kt

@@ -1,20 +1,55 @@
 package dev.slne.surf.transaction.api.account.member
 
 import dev.slne.surf.transaction.api.account.member.results.AccountMemberResult
+import org.jetbrains.annotations.ApiStatus
 import java.util.*
-
+/**
+ * Defines member management operations for an account.
+ *
+ * Implementations of this interface allow accounts to manage additional members
+ * who may have access to the account, depending on permission rules enforced
+ * by the implementation.
+ */
+@ApiStatus.NonExtendable
 interface AccountMemberOperations {
+    /**
+     * The set of UUIDs representing all members of the account.
+     *
+     * This does not necessarily include the account owner.
+     */
     val members: Set<UUID>
 
+    /**
+     * Adds a new member to the account.
+     *
+     * @param executor the UUID of the entity performing the operation
+     * @param target the UUID of the player to be added as a member
+     *
+     * @return the result of the member addition attempt
+     */
     suspend fun addMember(
         executor: UUID,
         target: UUID
     ): AccountMemberResult
 
+    /**
+     * Removes a member from the account.
+     *
+     * @param executor the UUID of the entity performing the operation
+     * @param target the UUID of the player to be removed from the account
+     *
+     * @return the result of the member removal attempt
+     */
     suspend fun removeMember(
         executor: UUID,
         target: UUID
     ): AccountMemberResult
 
+    /**
+     * Checks whether the given player is a member of the account.
+     *
+     * @param player the UUID of the player to check
+     * @return `true` if the player is a member, otherwise `false`
+     */
     fun isMember(player: UUID): Boolean
 }

surf-transaction-api/src/main/kotlin/dev/slne/surf/transaction/api/account/member/results/AccountMemberResult.kt

@@ -1,7 +1,27 @@
 package dev.slne.surf.transaction.api.account.member.results
 
+/**
+ * Represents the result of an account member modification operation.
+ *
+ * This result is returned when adding or removing members from an account.
+ */
 enum class AccountMemberResult {
+
+    /**
+     * The operation completed successfully.
+     */
     SUCCESS,
+
+    /**
+     * The operation did not change anything.
+     *
+     * This typically means the target was already in the desired state
+     * (e.g. adding an existing member or removing a non-member).
+     */
     NOTHING_CHANGED,
+
+    /**
+     * The account on which the operation was attempted could not be found.
+     */
     ACCOUNT_NOT_FOUND;
-}
+}

surf-transaction-api/src/main/kotlin/dev/slne/surf/transaction/api/account/result/AccountCreationResult.kt

@@ -2,15 +2,50 @@ package dev.slne.surf.transaction.api.account.result
 
 import dev.slne.surf.transaction.api.account.Account
 
+/**
+ * Represents the result of an account creation attempt.
+ *
+ * Account creation can either succeed with a newly created [Account]
+ * or fail with a specific [FailureReason].
+ */
 sealed interface AccountCreationResult {
 
+    /**
+     * Indicates that the account was created successfully.
+     *
+     * @param account the newly created account
+     */
     data class Success(val account: Account) : AccountCreationResult
+
+    /**
+     * Indicates that the account creation failed.
+     *
+     * @param reason the reason why account creation failed
+     */
     data class Failed(val reason: FailureReason) : AccountCreationResult
 
+    /**
+     * Describes possible reasons why account creation may fail.
+     */
     enum class FailureReason {
+        /**
+         * An account with the given name already exists.
+         */
         NAME_ALREADY_EXISTS,
+
+        /**
+         * The provided account name exceeds the maximum allowed length.
+         */
         NAME_TOO_LONG,
+
+        /**
+         * The provided account name is shorter than the minimum required length.
+         */
         NAME_TOO_SHORT,
+
+        /**
+         * The provided account name is a valid UUID and therefore not allowed.
+         */
         NAME_IS_UUID;
     }
 }

surf-transaction-api/src/main/kotlin/dev/slne/surf/transaction/api/account/result/AccountDeleteResult.kt

@@ -1,7 +1,22 @@
 package dev.slne.surf.transaction.api.account.result
 
+/**
+ * Represents the result of an account deletion attempt.
+ */
 enum class AccountDeleteResult {
+
+    /**
+     * The account was deleted successfully.
+     */
     SUCCESS,
+
+    /**
+     * The account could not be deleted because it is marked as the default account.
+     */
     DEFAULT_ACCOUNT_CANNOT_BE_DELETED,
+
+    /**
+     * The account to be deleted could not be found.
+     */
     ACCOUNT_NOT_FOUND;
-}
+}