Docblock cleanup

(mostly style, some typo fixes and return type additions)