From 96d3f4f78bf770992160b1a58f4076bd72fadcd6 Mon Sep 17 00:00:00 2001
From: "Dylan K. Taylor" <odigiman@gmail.com>
Date: Mon, 10 Jun 2019 17:19:03 +0100
Subject: [PATCH] Updated documentation for transaction classes

---
 .../inventory/transaction/CraftingTransaction.php | 15 +++++++++++++++
 .../transaction/InventoryTransaction.php          | 14 +++++++++++++-
 2 files changed, 28 insertions(+), 1 deletion(-)

diff --git a/src/pocketmine/inventory/transaction/CraftingTransaction.php b/src/pocketmine/inventory/transaction/CraftingTransaction.php
index e5f98c4f4..e91085812 100644
--- a/src/pocketmine/inventory/transaction/CraftingTransaction.php
+++ b/src/pocketmine/inventory/transaction/CraftingTransaction.php
@@ -32,6 +32,21 @@ use function array_pop;
 use function count;
 use function intdiv;
 
+/**
+ * This transaction type is specialized for crafting validation. It shares most of the same semantics of the base
+ * inventory transaction type, but the requirement for validity is slightly different.
+ *
+ * It is expected that the actions in this transaction type will produce an **unbalanced result**, i.e. some inputs won't
+ * have corresponding outputs, and vice versa. The reason why is because the unmatched inputs are recipe inputs, and
+ * the unmatched outputs are recipe results.
+ *
+ * Therefore, the validity requirement is that the imbalance of the transaction should match the expected inputs and
+ * outputs of a registered crafting recipe.
+ *
+ * This transaction allows multiple repetitions of the same recipe to be crafted in a single batch. In the case of batch
+ * crafting, the number of unmatched inputs and outputs must be exactly divisible by the expected recipe ingredients and
+ * results, with no remainder. Any leftovers are expected to be emitted back to the crafting grid.
+ */
 class CraftingTransaction extends InventoryTransaction{
 	/** @var CraftingRecipe|null */
 	protected $recipe;
diff --git a/src/pocketmine/inventory/transaction/InventoryTransaction.php b/src/pocketmine/inventory/transaction/InventoryTransaction.php
index f5d67be74..f1e98c10e 100644
--- a/src/pocketmine/inventory/transaction/InventoryTransaction.php
+++ b/src/pocketmine/inventory/transaction/InventoryTransaction.php
@@ -36,7 +36,19 @@ use function min;
 use function spl_object_hash;
 
 /**
- * This InventoryTransaction only allows doing Transaction between one / two inventories
+ * This is the basic type for an inventory transaction. This is used for moving items between inventories, dropping
+ * items and more. It allows transactions with multiple inputs and outputs.
+ *
+ * Validation **does not** depend on ordering. This means that the actions can appear in any order and still be valid.
+ * The only validity requirement for this transaction type is that the balance of items must add up to zero. This means:
+ * - No new outputs without matching input amounts
+ * - No inputs without matching output amounts
+ * - No userdata changes (item state, NBT, etc)
+ *
+ * A transaction is composed of "actions", which are pairs of inputs and outputs which target a specific itemstack in
+ * a specific location. There are multiple types of inventory actions which might be involved in a transaction.
+ *
+ * @see InventoryAction
  */
 class InventoryTransaction{
 	protected $hasExecuted = false;