Logo Questions Linux Laravel Mysql Ubuntu Git Menu
 

How to format a heading in a javadoc comment?

Tags:

java

javadoc

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 heave 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; }

enter image description here

The screenshot is from taken from Eclipse.

Update

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

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

enter image description here

like image 408
Micha Wiedenmann Avatar asked Aug 05 '13 09:08

Micha Wiedenmann


2 Answers

Use:

/**
 * <strong>Heading</strong>There is no line break.
 * <br /> <strong>Heading</strong>There is no line break.
 *
 * @param x foo
 * @return foo
 * @throws foo
 */
public int foo(int x) { return x; }
like image 139
Ankur Lathi Avatar answered Sep 27 '22 20:09

Ankur Lathi


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:

JavaDoc screenshot

like image 20
FrVaBe Avatar answered Sep 27 '22 19:09

FrVaBe