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.