improved javadoc and refactored methods according to issue #6