update docs and correct comments in the java docs