Update javadocs to document behavior