Update documentation

- Rephrase bits of the API documentation for clarity
- Add "common issues" section to README
- Add more inline documentation to examples