added javadoc comments and improved readability even further