More work on the javadocs to clearify usage