clean up Javadocs to make Java 8 happy

Oracle introduced an unannounced breaking change to the Javadoc tool in JDK 8 that enforces strict HTML4.01 for Javadoc comments and throws hard errors if it doesn't like anything. It also emits *lots* of warnings. This patch cleans up the Javadoc comments (particularly adding some `@param`s and escaping inline XML) to make JDK 8 settle down. It does not modify any running code.