improved docs and exception declarations