added javadoc comments and notes