Unit tests + cleanups for #1994

This pull requests pulls in the changes I originally put in #1994.

This includes:
* cherry-picked @jumping 's commits onto develop rather than master
* Fixed up some code and docs to match for those changes
* Added a unit test