improve  javadoc and other minor tweaks