update comments and javadoc