update comments and javadocs