document the exceptions raised by the main API methods
Merge pull request #44 from esc/document_exceptions

Fixes: #40 document exceptions raised from toplevel.py