Updated documentation for transaction classes

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;

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;