Docstring improvements, clearer and additional tests

The original claim that this fixes #1321 is incorrect. I have a
test for #1321, but it fails, so i've commented it for now.