issue-#4-improve-javadoc

- formatting
- added feature examples to javadoc (from javadoc)
- minor fixes in README.md