docs and more detailed type annotations