update docs and slightly clean code

[Ironholds]

This clarifies some of the documentation and a bit of the code - for example, making explicit in the (prose) documentation what the defaults are, using x = NULL when x not being set is still acceptable and will perform an operation (which seems to be the convention) and adding an explicit returm.

[renkun-ken]

Thanks a lot for your corrections and clarifications!

[renkun-ken]

Thanks!