update javadoc and test method to reflect current implementation