Reputation: 28345

How can I use "<" and ">" in javadoc without formatting?

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?

Upvotes: 153

Answers (10)

plswork04

Reputation: 659

A full example showing off uses of {@code }, {@literal }, and escapes to preserve < and >.

package example;

public class Example {

    /**
     * Prints the perfect XML.
     * 
     * The following XML will be printed:
     * 
     *
     * <pre>{@code
<hello>
    <world>
        <value>42</value>
        <value>
           * oops?
        </value>
    </world>
</hello>
     * }</pre>
     * 
     * 
     * Keep leading stars if you want. Will still be ignored.
     * 
     * <pre>{@code
     * <hello>
     *     <world>
     *         <value>42</value>
     *         <value>
     *            * oops?
     *         </value>
     *     </world>
     * </hello>
     * }</pre>
     * 
     * Look at stdout.
     */
    public void printXML() {
    }

    /**
     * Prints meanings of {@code Map<String, Integer>}.
     * 
     * {@code Map<String, Integer>} can represent:
     * <ul>
     * <li>{@literal Map<Input, Hash>}</li>
     * <li>{@literal Map<Team, Score>}</li>
     * <li>{@literal Map<Country, GDP>}</li>
     * </ul>
     * 
     * Look at stdout.
     */
    public void printMapRelations() {
    }

    /**
     * {@literal 
     * Proves 4 < 2 + 3 is the same as 2 + 3 > 4
     * 
     * No markup is required to show that flipping the left and right sides 
     * of an < expression causes < to become >.
     * 
     * Don't use <and> carelessly.
     * }
     */
    public void printProof() {
    }

    /**
     * Javadoc is HTML so encoded <strong>&lt;</strong> and <em>&gt;</em> work but
     * not super
     * legible in source.
     */
    public void printOther() {
    }
}

Note: The IDE preview and the actual output can sometiems look slightly different.

Reminder: ./gradlew javadoc will by default build to build/docs/javadoc/.

See also:

https://docs.oracle.com/javase/7/docs/technotes/tools/windows/javadoc.html#javadoctags (What is the current version of this page?)

Upvotes: 0

Daric

Reputation: 93

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)

Upvotes: 0

ivanjermakov

Reputation: 1284

Just surround it with {@code} like this:

{@code <xmlElement>}

Upvotes: 6

Serg

Reputation: 487

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>

Upvotes: 16

Etienne Delavennat

Reputation: 1083

Considering XML is actual code, I believe XML snippets in Javadoc are better suited for the {@code AC} tag rather than the {@literal AC} tag.

The {@code } tag uses a fixed-width font which makes its content standout as actual code.

Upvotes: 62

Owen

Reputation: 3193

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

`AC` reads a bit nicer than {@code AC}

Upvotes: 4

Pavitar Singh

Reputation: 2373

You can use < for < and > for > .

Upvotes: 205

Howard M. Lewis Ship

Reputation: 2337

Recent versions of JavaDoc support {@literal AC}; 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

Upvotes: 83

Pops

Reputation: 30828

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>
&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>

Upvotes: 10

duffymo

Reputation: 308753

Escape them as HTML: < and >

Upvotes: 19

How can I use &quot;&lt;&quot; and &quot;&gt;&quot; in javadoc without formatting?

Answers (10)

Related Questions

How can I use "<" and ">" in javadoc without formatting?