[REQS-689] Add javadoc, tidy up the code