add some javadoc to explain new methods
typos :p