CIT 594 HTML for Javadoc
Spring 2015, David Matuszek

Javadoc comments in Java are not just plain text; they use a subset of HTML markup to provide more control of appearance. This clutters up the plain text and makes it harder to read, but greatly improves the generated Javadoc files. To read the Javadoc comments more clearly in Eclipse, hover (don't click) the mouse over the method, field, or class name to which the comments apply.

Ordinary, non-Javadoc comments do not use HTML markup.

Tags and entities

Most tags are containers, that is, they enclose text. The syntax is <tagname>enclosed text</tagname>. Tags may be nested within other tags.

Some tags are standalone, that is, they do not enclose text. The usual syntax is <tagname> but they are sometimes written with a trailing slash: <tagname/>.

The characters "<", ">", and "&" have special meaning in HTML. To display these characters as themselves in HTML, they must be replaced by the entities &lt;, &gt;, and &amp;, respectively. Unicode characters such as → and ∑can also be represented by entities, in this case, &rarr; and ∑.

Here is a small selection of the most useful tags:

Tag How to write it How it looks
<b> for boldface, <i> for italics This is <b>bold</b> and this is <i>italic</i>. This is bold and this is italic.
<br> or <br/> for a line break. this is <br>the way the world ends<br>not with a bang<br>but a whimper this is
the way the world ends
not with a bang
but a whimper
<pre> puts its text in a monospace font, and preserves all newlines and spacing, so it is good for code blocks. <pre>while (i &lt; 100) {
    i = doSomething(i);
}</pre>		 
while (i < 100) {
    i = doSomething(i);
}
<code> puts its text in a monospace font, but doesn't preserve newlines or spacing. <pre>while (i &lt; 100) {
    i = doSomething(i);
}</pre>		 while (i < 100) { i = doSomething(i); }
<ul> is for bulleted (unordered) lists. <li> contains each list element. 
<ul>
 <li>ice cream</li>
 <li>popcorn</li>
</ul>
 I like:
  • ice cream
  • popcorn
<ol> is for ordered lists. <li> contains each list element. 
<ol>
  <li><code>boil water</code></li>
  <li><code>pour in pasta</code></li>
  <li><code>wait 10 minutes</code></li>
</ol>
  1. boil water
  2. pour in pasta
  3. wait 10 minutes
<dl> is for definition lists. <dt> contains each term, and <dd> contains its definition. 
<dl>
  <dt>Tag</dt>
  <dd>A container for text</dd>
  <dt>Entity</dt>
  <dd>A representation of a character</dd>
</dl>
Tag
A container for text
Entity
A representation of a character