improved comments and javadoc