docs!  and update API to match the way I used it in the docs
minor test fix - tests pass