How to format code snippet in Javadoc with @ and { symbols inside?

Question

This is what I'm trying to do:

/**
 * <pre>
 * {@code
 * &#64;XmlRootElement
 * public final class Page &#123;
 * &#125;
 * }
 * </pre>
 */

I'm expecting it to be formatted like:

@XmlRootElement
public final class Page {
}

But I'm getting:

&#64;XmlRootElement
public final class Page &#123;
&#125;

Replacing these HTML entities with real symbols (@, {, }) leads to javadoc warnings and absolutely incorrect formatting. What is a workaround?

score 40 · Accepted Answer · answered Nov 06 '11 at 14:07

40

This is how it finally works for me:

/**
 * <pre>
 * &#64;XmlRootElement
 * public final class Page {
 * }
 * </pre>
 */

answered Nov 06 '11 at 14:07

yegor256

Your answer works for me. THX. If use "{@literal @}Override", I have to remove one space before "{@literal @}Override" to line up. – Allen Kerr Jun 24 '20 at 10:02

score 31 · Answer 2 · answered Sep 26 '13 at 03:37

31

<pre>
<code>
{@literal@}Override
public String toString() {
    return "blah";
}
</code>
</pre>

This works for me.

answered Sep 26 '13 at 03:37

Patrick

I had to add a space between `@literal` and `@`, like so: `{@literal @}Override` – geld0r Jan 17 '18 at 14:38

score 7 · Answer 3 · answered Nov 06 '11 at 13:04

7

wrap your code snippet with <pre><code></code></pre>. These are special HTML tags that allow you to forget about escaping of special characters.

answered Nov 06 '11 at 13:04

AlexR

7

Huh. There is nothing in the definition of `pre` or `code` which escapes special characters. They only change the font and the whitespace interpretation. (Also, `@` and `{` might get interpreted by Javadoc before the HTML browser even gets them.) – Paŭlo Ebermann Nov 06 '11 at 15:45

score 3 · Answer 4 · answered Nov 04 '21 at 09:27

3

Since Java 18 (JEP 413) you may use @snippet tag:

/**
 * -- ex: looping through List of Map objects --
 * {@snippet :
 * @XmlRootElement
 * public final class Page {
 * }
 * }
 */

answered Nov 04 '21 at 09:27

Nolequen

You can also use the same syntax in Java 8+ with this maven doclet plugin https://github.com/jtulach/codesnippet4javadoc – Saljack Aug 29 '22 at 12:27

score 0 · Answer 5 · answered Nov 08 '17 at 22:43

0

It is old question but I figured out why it was not working for me.

This was not working:

<pre>{@code 
@Autowired

But when all written in one line it works.

<pre>
{@code @Autowired

answered Nov 08 '17 at 22:43

Chandresh Mishra

5 Answers5