Add documentation to economy-related interfaces

This commit is contained in:
Allink 2023-06-09 17:22:54 +01:00
parent cccf76d077
commit 6ccaf5eb25
No known key found for this signature in database
8 changed files with 99 additions and 2 deletions

View File

@ -1,7 +1,14 @@
package me.totalfreedom.economy; package me.totalfreedom.economy;
/**
* Represents an immutable transaction that has been fully handled by a {@link Transactor} instance
*/
public interface CompletedTransaction extends Transaction public interface CompletedTransaction extends Transaction
{ {
/**
* Gets the final result of the {@link Transaction}
*
* @return the result
*/
TransactionResult getResult(); TransactionResult getResult();
} }

View File

@ -1,8 +1,21 @@
package me.totalfreedom.economy; package me.totalfreedom.economy;
/**
* An entity that is able to transfer sums of currency between other {@link EconomicEntity}
*/
public interface EconomicEntity public interface EconomicEntity
{ {
/**
* Gets the {@link EconomicEntityData} (which contains various common metadata about this {@link EconomicEntity}) associated with this class
*
* @return the {@link EconomicEntityData}
*/
EconomicEntityData getEconomicData(); EconomicEntityData getEconomicData();
/**
* The name of the economic entity
*
* @return the economic entity's name
*/
String getName(); String getName();
} }

View File

@ -1,14 +1,40 @@
package me.totalfreedom.economy; package me.totalfreedom.economy;
/**
* Metadata associated with a {@link EconomicEntity}
*/
public interface EconomicEntityData public interface EconomicEntityData
{ {
/***
* @return the transaction freeze state
*/
boolean areTransactionsFrozen(); boolean areTransactionsFrozen();
/***
* @return the balance
*/
long getBalance(); long getBalance();
/**
* Adds the provided amount to the associated instance's balance
*
* @param amount the amount to add
* @return the new balance
*/
long addToBalance(final long amount); long addToBalance(final long amount);
/**
* Subtracts the provided amount from the associated instance's balance
*
* @param amount the amount to subtract
* @return the new balance
*/
long removeFromBalance(final long amount); long removeFromBalance(final long amount);
/**
* Sets the balance of the associated instance
*
* @param newBalance the new balance
*/
void setBalance(final long newBalance); void setBalance(final long newBalance);
} }

View File

@ -1,13 +1,32 @@
package me.totalfreedom.economy; package me.totalfreedom.economy;
/** /**
* Please ensure that all modifications of {@link MutableTransaction} happen BEFORE it is passed to a {@link Transactor} implementation * A transaction that can be changed.
* <p>
* IMPORTANT NOTE: Please ensure that all modifications of {@link MutableTransaction} happen BEFORE it is passed to a {@link Transactor} implementation
*/ */
public interface MutableTransaction extends Transaction public interface MutableTransaction extends Transaction
{ {
/**
* Adds a number to the balance transferred in this transaction
*
* @param amount the amount to add
* @return the new amount
*/
long addToBalance(final long amount); long addToBalance(final long amount);
/**
* Subtracts a number from the balance transferred in this transaction
*
* @param amount the amount to remove
* @return the new amount
*/
long removeFromBalance(final long amount); long removeFromBalance(final long amount);
/**
* Sets the balance transferred in this transaction
*
* @param newBalance the new balance of the transaction
*/
void setBalance(final long newBalance); void setBalance(final long newBalance);
} }

View File

@ -1,11 +1,23 @@
package me.totalfreedom.economy; package me.totalfreedom.economy;
/**
* A class that denotes the transfer of currency between two EconomicEntity instances.
*/
public interface Transaction public interface Transaction
{ {
/**
* @return the initiating entity
*/
EconomicEntity getSource(); EconomicEntity getSource();
/**
* @return the destination entity
*/
EconomicEntity getDestination(); EconomicEntity getDestination();
/**
* @return the balance transferred in this Transaction
*/
long getBalance(); long getBalance();
} }

View File

@ -1,6 +1,14 @@
package me.totalfreedom.economy; package me.totalfreedom.economy;
/**
* A class that intercepts transactions after they are completed and logs them to a data point
*/
public interface TransactionLogger public interface TransactionLogger
{ {
/**
* Logs a completed transaction
*
* @param completedTransaction the completed transaction to log
*/
void logTransaction(CompletedTransaction completedTransaction); void logTransaction(CompletedTransaction completedTransaction);
} }

View File

@ -2,6 +2,9 @@ package me.totalfreedom.economy;
import net.kyori.adventure.text.Component; import net.kyori.adventure.text.Component;
/**
* A class that represents the result of a transaction
*/
public interface TransactionResult public interface TransactionResult
{ {
String getMessage(); String getMessage();

View File

@ -1,6 +1,15 @@
package me.totalfreedom.economy; package me.totalfreedom.economy;
/**
* A class that implements the completion of transactions.
*/
public interface Transactor public interface Transactor
{ {
/**
* Processes a transaction
*
* @param transaction the transaction to process
* @return the completed transaction
*/
CompletedTransaction handleTransaction(MutableTransaction transaction); CompletedTransaction handleTransaction(MutableTransaction transaction);
} }