Clean up the HTTP client module

[marcelstoer]

See #887 (comment):

• write documentation
• move examples from README to examples dir

[jmattsson]

Somewhere/somewhen I volunteered to write the API docs for it. I've got it on my todo list, either this weekend or early next.

[jmattsson]

I've added module docs to newdocs

[jmattsson]

Considering the module docs include examples, should they perhaps just be removed from the readme? (as opposed to moved elsewhere)

[devsaurus]

Guess so, #771 also proposes to remove examples from the README.
My approach is to have code snippets in the module docs, but to store full-fledged scripts that can actually be executed in lua/examples.

[TerryE]

I think that the current code snippets can be very misleading. I would prefer every module to have at least one full-fledged script which demonstrates best practice in using the module, and that this is in lua_examples not lua/examples.

[marcelstoer]

Indeed, as per #771 and #772 full-fledged examples, not to be mixed up with the snippets in the docs, should be removed from README.