improve api doc rendering and formating

(@rjackson / @stefanpenner)