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).