added docs and better exceptions