Improve the documentation of the project.

Go over the README file, and improve its contents. Add a Usage/hints section
with some helpful hints on how to use the library in turn. Also while here, make
sure that `rebar doc` works as expected and fix every documentation bug in
the EDoc sections, so it compiles and works. Verify the documentation output
is nice-looking while at it.