Improve the documentation of the readme

obvious.

Documentation improvements within the code can now be used to generate a API doc like javadoc.
Maybe consider to integrate this generated API to the repo  (generate with yuidoc or jsdoc).

Check my fork to see how the readme.md does look like.