Documentation updates

 - Be more explicit about telling users to check the tests for more examples
 - Use headings for examples to allow people to scan the page
 - Add some additional examples
 - Grammar fixes