expand comments section

I did some work on expanding the comments guidelines.

Any feedback is appreciated.
A couple of comments here:
* These code snippets are not primarily tests -- they are usually examples of API usages. The neat thing is that we can test the documentation!
* The Guidelines are not (primarily) meant to document Rust features, but instead to give guidance on when and in what way to use them. It'd be great to come up with some guidelines for when to add examples, and what they should show.