Improve documentation formatting

[alamb]

While reviewing #1059 I noticed the documentation comments leave a lot to be desired in this crate.

While I was waiting for CI to pass, I spent some time making some improvements.

There are plenty more to make, but I think this is a step in the right direction

[coveralls]

Pull Request Test Coverage Report for Build 7267352347

Warning: This coverage report may be inaccurate.

We've detected an issue with your CI configuration that might affect the accuracy of this pull request's coverage report.
To ensure accuracy in future PRs, please see these guidelines.
A quick fix for this PR: rebase it; your next report should be accurate.

• 0 of 0 changed or added relevant lines in 0 files are covered.
• No unchanged relevant lines lost coverage.
• Overall coverage remained the same at 87.733%

---

Totals
Change from base Build 7267336660:	0.0%
Covered Lines:	18187
Relevant Lines:	20730

---

💛 - Coveralls