[wip] more doc-comments (and refactor)