Merge pull request #8 from AtlasMediaGroup/feat/doc-economy

Add documentation to economy-related interfaces

Patchwork/src/main/java/me/totalfreedom/economy/CompletedTransaction.java

@@ -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();
 }

Patchwork/src/main/java/me/totalfreedom/economy/EconomicEntity.java

@@ -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();
 }

Patchwork/src/main/java/me/totalfreedom/economy/EconomicEntityData.java

@@ -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);
 }

Patchwork/src/main/java/me/totalfreedom/economy/MutableTransaction.java

@@ -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);
 }

Patchwork/src/main/java/me/totalfreedom/economy/Transaction.java

@@ -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();
 
 }

Patchwork/src/main/java/me/totalfreedom/economy/TransactionLogger.java

@@ -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);
 }

Patchwork/src/main/java/me/totalfreedom/economy/TransactionResult.java

@@ -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();

Patchwork/src/main/java/me/totalfreedom/economy/Transactor.java

@@ -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);
 }