improve docs & error checking