Added a few method docs, and updated the README

re-submitting to `dev` branch