edit docs and add a couple tiny examples

[bcdarwin]

Test suite runs, but I didn't regenerate the docs so there may be syntax errors (in particular from citation URLs, etc.)

Suggestions appreciated.