Tidy up

Break up walls of text into small sections. Bring old docs up to speed with newer ones.
Fix typo
Add comments_count to example json responses in calendar_events

calendar_events json response now returns the comment count. Updates
the example json responses accordingly.
Merge branch 'update-docs-with-comments_count-on-calendar_events'
Add `app_url` to json responses in documentation