added docs, improve error reporting