When it takes more than a few words to explain what's happening, it's often an indication that code should be rewritten. Students are taught that it's important to comment everything. Professional programmers are often required to comment all their code. But the purpose of commenting can be lost in blindly following rules. Comments are meant to help a reader understand parts of the program that are not readily understood from the code itself.
Good code needs fewer comments than bad code.
If your comment blocks follow the above style, Javadoc will notice them and create the appropriate HTML for the Java code. See the java output. This is a result of Javadoc invoking part of javac . You can use most standard HTML tags within your Javadoc comment blocks. Javadoc can understand and include standard HTML, it generates Web pages after all.