Pay a part of the debt - some small refactoring and javadoc.

Signed-off-by: Clement Escoffier <clement.escoffier@gmail.com>