Added a few method docs, and updated the README

re-submitting to `dev` branch
``else`` is not required...