Improve crafting recipe documentation

[Wuzzy2]

Fixes #12796.

This adds missing documentation for the crafting recipe definition in lua_api.txt. Currently, the "documentation" was mostly just examples, not a proper definition. So I have written the missing definition, and parameter specification, and stuff.

Just read the diff for details. :P

[Wuzzy2]

Update! I have clarified some stuff about the crafting replacements and went into great detail, because those are pretty tricky.

[TurkeyMcMac]

LGTM

[SmallJoker]

Some suggestions to shorten the text while keeping the important information.

[Wuzzy2]

I have accepted and applied most of these changes (new commit), except:

Crafting converts one or more inputs to one output ItemStack of arbitrary count
(including empty). The conversion reduces each input ItemStack by one (1).

This is wrong or misleading, the output can NOT be specified as an ItemStack because ItemStack is an object. I changed it to "item stack" that term doesn't imply an object.
The output is only empty for fuel recipes. Otherwise, output is required and Minetest even refuses to start if you have a non-fuel
recipe with empty output. I didn't explain that correctly tho.

Craft recipes are registered by minetest.register_craft. The accepted
formats are listed below..

The fact that it's a table still should be mentioned explicitly.

optional output

Is that actually possible? I haven't seen this being used anywhere.

Fuel recipes never have an output. I changed the text anyway because this was confusing.

What if the input stack has a count larger than 1? What's replaced?

I now explained this is more detail in a new bullet point.

[the first example]

I intentionally want to keep a long explanation for the first example. That's the point of having examples.

[Wuzzy2]

More reactions because I overlooked these:

• output: Itemstring of the output ItemStack

Crafting behaviour (count >= 1) is already documented above.

Since this is the parameter list, I think it is OK to repeat it once. Also, ItemStack is misleading as it must not be an actual ItemStack object.

I suppose a commented code example would be more helpful than this text.

Replacing documentation by examples is exactly what documentation should NOT be doing. This was a direct reaction from a complaint in the issue this PR is reacting to. Also, examples are already provided. I consider this to be irreducible complexity.

[SmallJoker]

This is wrong or misleading, the output can NOT be specified as an ItemStack because ItemStack is an object.

Interesting. ItemStacks are not accepted but any item string works, including tool wear - likely even with metadata. Weird but not related to PR :)

Replacing documentation by examples

I did not mean to replace the documentation, but to integrate it into a generic example to comprehend what's going on while seeing the table format. I wouldn't read the text and head on to the examples, but other people might act different. Fair enough.

[SmallJoker]

Looks about right.

[ghost]

Unfortunately 2x2 recipes are broken

[TurkeyMcMac]

Could you open an issue?

[ghost]

Could you open an issue?

Yep