Improve docstrings and doctests in Utils.states

The only noteworthy thing here is that what is left
uncovered by the doctests all seems to be buggy code.