fix docstrings to use `@raise` and fix exception names

Suggested by @dbuenzli