updated javadoc comments to match method sigs