144

If I write <xmlElement> in a javadoc, it does not appear, because tags have special functions on formatting texts.

How can I show this chars in a javadoc?

Cœur
  • 37,241
  • 25
  • 195
  • 267
The Student
  • 27,520
  • 68
  • 161
  • 264
  • 5
    Related but not quite a dupe: http://stackoverflow.com/questions/1782040/does-javadoc-have-an-equivalent-to-cdata – Pops May 24 '10 at 17:34
  • Another dup: https://stackoverflow.com/questions/26588234/putting-sample-xml-code-in-javadoc – gavenkoa Aug 01 '23 at 10:39

9 Answers9

195

You can use &lt; for < and &gt; for > .

Hernán Eche
  • 6,529
  • 12
  • 51
  • 76
Pavitar Singh
  • 2,273
  • 1
  • 13
  • 5
  • or you could use & to to escape the & – ILMTitan May 24 '10 at 21:26
  • 25
    @TomBrito Although this answers the actual question, I believe the necessity to escape the signs appears only when they are used as angle brackets (i.e. in pairs), which in turn implies that they are part of some code (such as an XML tag, as in OP's case). In this situation, I believe a better solution is to wrap the entire XML snippet in `{@code ...}` tags, as Etienne Delavennat suggested in his answer. – Zoltán Jan 22 '15 at 09:14
  • 2
    `&gt` or `&lt` is not exactly the same meaning with the angle brackets in XML format. But `{@code <>}` is a right choice. – cinqS Sep 06 '17 at 02:08
77

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

Howard M. Lewis Ship
  • 2,247
  • 15
  • 23
58

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.

stkent
  • 19,772
  • 14
  • 85
  • 111
Etienne Delavennat
  • 1,012
  • 9
  • 10
  • 2
    I agree. XML should be wrapped in `{@code }` tags. It will be displayed more naturally (with a fixed-width font), and it will not look weird in the source javadoc, because you don't have to escape the angle brackets separately. – Zoltán Jan 22 '15 at 09:11
18

Escape them as HTML: &lt; and &gt;

duffymo
  • 305,152
  • 44
  • 369
  • 561
13

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>
Serg
  • 357
  • 4
  • 10
9

You only need to use the HTML equivalent for one of the angle brackets. The < can be represented as either &lt; or &#60;. Here's a sample taken from real Javadoc:

<pre>
&lt;complexType>
  &lt;complexContent>
    &lt;restriction base="{http://www.w3.org/2001/XMLSchema}anyType">
      &lt;sequence>
      [...]

This displays as:

<complexType>
   <complexContent>
     <restriction base="{http://www.w3.org/2001/XMLSchema}anyType">
       <sequence>
Pops
  • 30,199
  • 37
  • 136
  • 151
6

Just surround it with {@code} like this:

{@code <xmlElement>}
ivanjermakov
  • 1,131
  • 13
  • 24
4

If you set maven up to use markdown, you can just surround it with backticks.

`A<B>C` reads a bit nicer than {@code A<B>C}

Owen
  • 3,063
  • 5
  • 30
  • 26
0

In my case where I wanted to put in my javadocs List<SomeClass>...

I added an even more specific information by giving the link to my SomeClass, so here is my solution :

List<{@link SomeClass}>

Which resulted to a clean :

List<SomeClass>

With underlined 'SomeClass' directing to the specified class.

(of course if the SomeClass is not in same package, the complete path should be referenced)

Daric
  • 83
  • 9