Tidied documentation

- Normalized leading whitespace in function documentation
- README.md examples reflect that the password is no longer echoed to
  the terminal when entered interactively.
- Reworded some of the documentation and a couple of code comments.