clarify and fix doctests