#121 javadocs updated per discussion with Sebastien