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;
/**
* Represents an immutable transaction that has been fully handled by a {@link Transactor} instance
*/
public interface CompletedTransaction extends Transaction
{
/**
* Gets the final result of the {@link Transaction}
*
* @return the result
*/
TransactionResult getResult();
}

View File

@ -1,8 +1,21 @@
package me.totalfreedom.economy;
/**
* An entity that is able to transfer sums of currency between other {@link 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();
/**
* The name of the economic entity
*
* @return the economic entity's name
*/
String getName();
}

View File

@ -1,14 +1,40 @@
package me.totalfreedom.economy;
/**
* Metadata associated with a {@link EconomicEntity}
*/
public interface EconomicEntityData
{
/***
* @return the transaction freeze state
*/
boolean areTransactionsFrozen();
/***
* @return the balance
*/
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);
/**
* 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);
/**
* Sets the balance of the associated instance
*
* @param newBalance the new balance
*/
void setBalance(final long newBalance);
}

View File

@ -1,13 +1,32 @@
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
{
/**
* 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);
/**
* 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);
/**
* Sets the balance transferred in this transaction
*
* @param newBalance the new balance of the transaction
*/
void setBalance(final long newBalance);
}

View File

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

View File

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

View File

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

View File

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