#JC-1185 - small refactoring and javadocs