Use the standard style for the Javadoc commentJavadoc only requires a '/**' at the start and a '*/' at the end. In addition to this, use a single star on each additional line: /** * Standard comment. */ public ... /** Compressed comment.
If you want to start a line with the @ character and not have it be interpreted, use the HTML entity @. This implies that you can use HTML entities for any character that you would need to escape, and indeed you can: The text must be written in HTML with HTML entities and HTML tags.
Javadoc provides the @link inline tag for referencing the members in the Java classes. We can think of the @link tag as similar to the anchor tag in HTML, which is used to link one page to another via hyperlinks. Similar to the anchor tag, the path_to_member is the destination, and the label is the display text.
You can use <
for < and >
for > .
Recent versions of JavaDoc support {@literal A<B>C}; this outputs the content correctly (escaping the '<' and '>' in the generated HTML).
See http://download.oracle.com/javase/1.5.0/docs/guide/javadoc/whatsnew-1.5.0.html
Considering XML is actual code, I believe XML snippets in Javadoc are better suited for the {@code A<B>C} tag rather than the {@literal A<B>C} tag.
The {@code } tag uses a fixed-width font which makes its content standout as actual code.
Escape them as HTML: <
and >
You only need to use the HTML equivalent for one of the angle brackets. The <
can be represented as either <
or <
. Here's a sample taken from real Javadoc:
<pre> <complexType> <complexContent> <restriction base="{http://www.w3.org/2001/XMLSchema}anyType"> <sequence> [...]
This displays as:
<complexType>
<complexContent>
<restriction base="{http://www.w3.org/2001/XMLSchema}anyType">
<sequence>
Interposition of <pre> and {@code} saves angle brackets and empty lines in javadocs and is widely used, see java.util.Stream for example.
<pre>{@code
A<B>C
D<E>F
}</pre>
Just surround it with {@code}
like this:
{@code <xmlElement>}
If you love us? You can donate to us via Paypal or buy me a coffee so we can maintain and grow! Thank you!
Donate Us With