added and improved javadoc