Polish the rustdoc

[germangb]

The documentation page is in need of a lot of polish. I'm trying to improve it incrementally with every new commit, but the constant context switching between writing features/refactoring and writing docs leaves a lot to desire...

On top of that, I'm not a native speaker (english) which I think it shows in the sometimes poor use of grammar and lack of lexicon.

Some of the things I think need to be done:

• Fix the rushed-looking parts.
• Some of the examples are marked as no_run or ignore (lacking set up code).
• Some of the pages have too much information, instead of simple, concise example...