improve api doc rendering and formating
(@rjackson / @stefanpenner)
Merge pull request #742 from stefanpenner/improve_docs

improve api doc rendering and formating