Improve documentation of tools

[Wuzzy2]

This PR changes and adds to the lua_api.txt documentation of tools.

Currently, the documentation of tools is a bit lacking and the actual features are somewhat misrepresented.

It adds a more detailed description of item types to make clear that the term “tool” is really just a technical category and NOT limited to tools in a literal gameplay sense.
The documentation made the false assumption that only tools can do certain things like dig or punch while in reality all items can do that. So, I replaced the word “tool” with “item” where needed.

I also added a description of the toolrepair recipe with the wear formula.

A short explainer of punch attack uses was added.

And a couple of other things (see commit).

To do

This PR is ready to review.

How to test

Read the commit text. ;-)

[Df458]

Overall this seems like a big improvement to the existing text, I like how it clarifies what actually does/doesn't apply to non-tools. I haven't tested to confirm that this information is accurate, but I assume you've done so on your end.

Besides that, I have a bunch of random nitpicks with the text. Mostly small tweaks, the broad strokes are good imo but a minor editing pass could improve it.

[Wuzzy2]

OK, done.

“fulfil” is British English (I don't know which spelling is preferred tho, I don't care).
“identical items” sounds like I'm talking of the same instance of the item, which is not what is meant. Not sure about that.

[Df458]

Bump

This seems like a pretty trivial PR to review/merge, would be nice if a core dev could give it a quick look.

[sfan5]

Looks good otherwise.

[Wuzzy2]

I did what sfan5 requested. I rebased the single commit. There was no other change.

[SmallJoker]

Few ideas on how to keep the documentation short but precise.

---

Why are the toolcaps allowed on items? That was IMO a mistake. Only tools should have tool capabilities.

[Wuzzy2]

Two tools of the same type without the disable_repair=1 group can be combined to a single tool in a shapeless recipe.

This is wrong because it assumes that games always register the toolrepair recipe.

Why are the toolcaps allowed on items? That was IMO a mistake. Only tools should have tool capabilities.

What's wrong with that? I think this is incredibly useful. It makes the engine more flexible. There is only to gain from allowing tool capabilities on all items instead of only tools, and nothing to lose. Also, you will probably break things anyway if you remove this.

The other comments are OK, will work on them soon(TM).

[Wuzzy2]

Oh, I just saw the toolrepair thing referred to the definition of toolrepair ... I thought this was a different section, lol. My bad. I still like to reword that tho.

[Wuzzy2]

OK, hopefully it's better now.

[SmallJoker]

Thanks. LGTM