minor tweaks; update docs to explain error handling