Editing Javadoc (section)

== Markup ==

Javadoc ignores comments unless they are specially marked. A Javadoc comment is marked with an extra asterisk after the start of a multi-line comment: <code>/**</code>. A comment block pertains to the symbol that follows the block. 

An example of a class header block follows:

<syntaxhighlight lang="java">
/**
 * Provides some service
 * @author Jill Smith <address@example.com>
 * @version 1.6
 * @since 1.2
 */
public class Test {}
</syntaxhighlight>

For a method, the first line is a short description of the method. If more detail is warranted, then it may be followed by a longer description in additional paragraphs. Following that are optionally various tags.

Various aspects of HTML as supported via Javadoc. For example <code>&lt;p&gt;</code> denotes a paragraph break.

An example of a method header block follows:

<syntaxhighlight lang="java">
/**
 * One-line description
 * <p>
 * Longer description. If there were any, it would be here.
 * <p>
 * And even more explanation to follow in consecutive
 * paragraphs separated by paragraph break.
 *
 * @param variableName Description...
 * @return Description...
 */
public int methodName(...) { ... }
</syntaxhighlight>

Variables can also be documented. For example:

<syntaxhighlight lang="java">
/**
 * Description of the variable here
 */
private int debug = 0;
</syntaxhighlight>

A more complete example follows:

<syntaxhighlight lang="java">
/**
 * Validates a chess move
 *
 * <p>Use {@link #doMove(int fromFile, int fromRank, int toFile, int toRank)} to move a piece.
 *
 * @param fromFile file from which a piece is being moved
 * @param fromRank rank from which a piece is being moved
 * @param toFile file to which a piece is being moved
 * @param toRank rank to which a piece is being moved
 * @return true if the move is valid, otherwise false
 * @since 1.0
 */
boolean isValidMove(int fromFile, int fromRank, int toFile, int toRank) { ... }

/**
 * Moves a chess piece
 *
 * @see java.math.RoundingMode
 */
void doMove(int fromFile, int fromRank, int toFile, int toRank) { ... }
</syntaxhighlight>