Javadoc: Difference between revisions

Revision as of 14:07, 6 January 2025

Revision as of 14:14, 6 January 2025

Line 23:

== Design ==

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. For a method, the first paragraph is a description of the method. Following that are optionally various fields such as:

* <code>@param</code> to describe a method parameter

* <code>@return</code> to describe the return value

* <code>@throws</code> to describe exceptions the method may throw

* <code>@see</code> and other less-common tags

An example of a class header block follows:

Line 42 ⟶ 37:

</syntaxhighlight>

For a method, the first paragraph is a 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 fields such as:

Documentation comments for methods usually contain a short, concise, one line description to

explain what the item does, followed by a longer description, and lastly a tag section that lists accepted input arguments and return values of the method. The

* <code>@param</code> to describe a method parameter

Javadoc is treated as HTML, so a "<code>&lt;p&gt;</code>" paragraph break tag can be used to denote multiple paragraphs.

* <code>@return</code> to describe the return value

* <code>@throws</code> to describe exceptions the method may throw

* <code>@see</code> and other less-common 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">

/**

* Short one One-line description. (1)

* <p>

* Longer description. If there were any, it would be (2)here.

* here.

* <p>

* And even more explanationsexplanation to follow in consecutive

* paragraphs separated by HTML paragraph breaksbreak.

*

* @param variablevariableName Description text text text. (3)..

* @return Description text text text...

*/

public int methodName (...) { ... }

// method body with a return statement

}

</syntaxhighlight>