new docs
Add a bunch of tests to make sure I got the behavior right in the docs.