Adding Documentation to README.md

Adds documentations for most important behaviour and API idiosyncrasies to the `README.md`.