more doc-comments (and refactor)