Clean up craft replacements docs

p-ouellette · sfan5 · commit 27ce6d0ecc55 · 2019-12-07T23:46:24.000+01:00
diff --git a/doc/lua_api.txt b/doc/lua_api.txt
@@ -4782,8 +4782,9 @@ Item handling
       `{stack1, stack2, stack3, stack4, stack 5, stack 6, stack 7, stack 8, stack 9}`
     * `output.item` = `ItemStack`, if unsuccessful: empty `ItemStack`
     * `output.time` = a number, if unsuccessful: `0`
-    * `output.replacements` = list of `ItemStack`s that couldn't be placed in
-      `decremented_input.items`
+    * `output.replacements` = List of replacement `ItemStack`s that couldn't be
+      placed in `decremented_input.items`. Replacements can be placed in
+      `decremented_input` if the stack of the replaced item has a count of 1.
     * `decremented_input` = like `input`
 * `minetest.get_craft_recipe(output)`: returns input
     * returns last registered recipe for output item (node)
diff --git a/src/craftdef.h b/src/craftdef.h
@@ -113,9 +113,6 @@ struct CraftOutput
 	Example: If ("bucket:bucket_water", "bucket:bucket_empty") is a
 	replacement pair, the crafting input slot that contained a water
 	bucket will contain an empty bucket after crafting.
-
-	Note: replacements only work correctly when stack_max of the item
-	to be replaced is 1. It is up to the mod writer to ensure this.
 */
 struct CraftReplacements
 {
@@ -410,10 +407,22 @@ class ICraftDefManager
 	ICraftDefManager() = default;
 	virtual ~ICraftDefManager() = default;
 
-	// The main crafting function
+	/**
+	 * The main crafting function.
+	 *
+	 * @param input The input grid.
+	 * @param output CraftOutput where the result is placed.
+	 * @param output_replacements A vector of ItemStacks where replacements are
+	 * placed if they cannot be placed in the input. Replacements can be placed
+	 * in the input if the stack of the replaced item has a count of 1.
+	 * @param decrementInput If true, consume or replace input items.
+	 * @param gamedef
+	 * @return true if a result was found, otherwise false.
+	 */
 	virtual bool getCraftResult(CraftInput &input, CraftOutput &output,
 			std::vector<ItemStack> &output_replacements,
 			bool decrementInput, IGameDef *gamedef) const=0;
+
 	virtual std::vector<CraftDefinition*> getCraftRecipes(CraftOutput &output,
 			IGameDef *gamedef, unsigned limit=0) const=0;
 
diff --git a/src/inventorymanager.cpp b/src/inventorymanager.cpp
@@ -861,7 +861,7 @@ void ICraftAction::apply(InventoryManager *mgr,
 	}
 
 	// Put the replacements in the inventory or drop them on the floor, if
-	// the invenotry is full
+	// the inventory is full
 	for (auto &output_replacement : output_replacements) {
 		if (list_main)
 			output_replacement = list_main->addItem(output_replacement);

Original file line number	Diff line number	Diff line change
`@@ -861,7 +861,7 @@ void ICraftAction::apply(InventoryManager *mgr,`
`861`	`861`	`}`
`862`	`862`
`863`	`863`	`// Put the replacements in the inventory or drop them on the floor, if`
`864`		`- // the invenotry is full`
	`864`	`+ // the inventory is full`
`865`	`865`	`for (auto &output_replacement : output_replacements) {`
`866`	`866`	`if (list_main)`
`867`	`867`	`output_replacement = list_main->addItem(output_replacement);`