Update

If you found this question chances are that you should follow the advice of nolequen and their answer to use markdown documentation comments.

Original Question

How can I format headings in a Javadoc comment such that they match the format of @param, @return, or @throws. I am not asking how to define my own keywords, rather how to have a bold face heading similar to them.

I have tried <h1></h1> but it looks terrible in the Javadoc-view of Eclipse, in particular the size is much larger. Is there an alternative, or is <h1></h1> the way to go?

/**
 * foo
 *
 * @param x foo
 * @return foo
 * @throws foo
 */
public int foo(int x) { return x; }

The screenshot is taken from Eclipse.

Update

I do not think that <strong> is sufficient, since it does not add line breaks:

/**
 * Introduction
 * 
 * <strong>Heading</strong>There is no line break.
 * <strong>Heading</strong>There is no line break.
 *
 * @param x foo
 * @return foo
 * @throws foo
 */

Just have a look at the generated Java Doc of the JAVA API, e.g. SimpleDateFormat.parse (have a look at the HTML source code).

They use a html description list for formatting and a strong CSS class to format the term. So do it the same:

/**
 * Introdcution
 * 
 * <dl>
 * <dt><span class="strong">Heading 1</span></dt><dd>There is a line break.</dd>
 * <dt><span class="strong">Heading 2</span></dt><dd>There is a line break.</dd>
 * </dl>
 *
 * @param x foo
 * @return foo
 * @throws foo
 */

Looks like this: