revised the javadocs of the package API