add javadoc as requested by @tombentley