CODEWITHSUNDEEP
javajavadoc
Micha Wiedenmann
Micha Wiedenmann

Reputation: 20823

How to format a heading in a javadoc comment?

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

enter image description here

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
 */

enter image description here

Upvotes: 13

Views: 26558

Answers (3)

Nolequen
Nolequen

Reputation: 4245

Since Java 23 (JEP 467) you may use /// for Markdown comments:

  /// Introduction
  ///
  /// # Heading 1
  /// There is a line break.
  /// # Heading 2
  /// There is a line break.
  ///
  /// @param x foo
  /// @return foo
  /// @throws foo

Upvotes: 1

FrVaBe
FrVaBe

Reputation: 49341

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

Upvotes: 11

Ankur Lathi
Ankur Lathi

Reputation: 7836

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

Upvotes: 11

Related Questions