documentation and exception improvements