completing api docs

adding the missing paragraphs and some formatting
Merge branch 'master' into complete-api-doc