improving docs and javadocs