212

How can I escape the @ symbol in javadoc? I am trying to use it inside a {@code} tag, which is inside <pre> tags.

I already tried the html escape &#64; sequence, but that didn't work.

Bohemian
  • 412,405
  • 93
  • 575
  • 722
JayL
  • 2,819
  • 4
  • 22
  • 15

5 Answers5

306

Use the {@literal} javadoc tag:

/**
 * This is an "at" symbol: {@literal @}
 */

The javadoc for this will read:

This is an "at" symbol: @

Of course, this will work for any characters, and is the "officially supported" way of displaying any "special" characters.

It is also the most straighforward - you don't need to know the hex code of the character, and you can read what you've typed!

Bohemian
  • 412,405
  • 93
  • 575
  • 722
  • 2
    How do you escape the `}` symbol? – ADTC Sep 06 '13 at 09:01
  • 1
    @ADTC You can't. Why would you want to? `}` has no special meaning in html. – Bohemian Sep 07 '13 at 04:06
  • So I guess you can only split it into two `literal` tags. – ADTC Sep 07 '13 at 09:19
  • @adtc I thought of splitting it too, but you really only need literal with the HTML-like chars, eg when javadocing `Foo` etc, so if you put @literal just around the bits you need to, rather than entire snippets, it should be not a problem. – Bohemian Sep 07 '13 at 13:24
  • 33
    I'm surprised this is accepted and so up-voted. Premise of the question: _inside {@code} tag_. {@literal} just doesn't work inside a {@code} tag. – Daniel C. Sobral Mar 28 '16 at 19:12
  • 3
    What? The 11th of the month, '11 at 11:11? You should have posted this exactly a month earlier. ;-) – MC Emperor Sep 14 '17 at 10:42
  • 1
    @MCEmperor the java Calendar uses 0-based months, so this would be month #11 there - close enough? – Bohemian Sep 14 '17 at 17:55
  • @Bohemian You [convinced](https://docs.oracle.com/javase/7/docs/api/constant-values.html#java.util.Calendar.DECEMBER) me! ;-) – MC Emperor Sep 14 '17 at 18:02
  • 7
    Omitting the `{` and just using `@literal @` works inside of a `{@code}` tag. – Brad Turek Feb 10 '18 at 22:35
  • How can you go about escaping whole _tags_? I want to do something like `{@literal {@code ...}}` (basically show the text "{@code ...}") which Eclipse (falsely??) interprets as `{@code ...}}`. – Alex Mandelias Mar 05 '21 at 15:26
67

Just write it as an HTML entity:

&#064;

From the document "javadoc - The Java API Documentation Generator"

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. You can use whichever version of HTML your browser supports. The standard doclet generates HTML 3.2-compliant code elsewhere (outside of the documentation comments) with the inclusion of cascading style sheets and frames. HTML 4.0 is preferred for generated files because of the frame sets.

For example, entities for the less than symbol (<) and the greater than symbol (>) should be written as &lt; and &gt;. Similarly, the ampersand (&) should be written as &amp;.

Community
  • 1
  • 1
Frank V
  • 25,141
  • 34
  • 106
  • 144
  • 1
    It works better than the literal expression when not followed by a space (when writting annotation for example) – Bludwarf May 25 '16 at 14:56
11

my solution is 

/**
 * Mapper Test Helper.
 *
 * add the following annotations above the class
 * <pre>{@code
 * // junit5
 * @literal @ExtendWith(SpringExtension.class)
 * // junit4
 * @literal @RunWith(SpringRunner.class)
 * }</pre>
 */
Yeongjun Kim
  • 739
  • 7
  • 19
4

Fixed in javadoc tool from 15.0.2

This issue now appears to be fixed when using javadoc tool from 15.0.2.

That is, we no longer need to escape the @ character when using javadoc multiline {@code ... } block.

There is a JDK bug logged https://bugs.openjdk.java.net/browse/JDK-8130754 ... which is currently not marked as fixed but it no longer reproduces with javadoc 15.0.2.

Rob Bygrave
  • 3,861
  • 28
  • 28
2

You got the general idea, try using the octal representation: &#064;

Yuval Adam
  • 161,610
  • 92
  • 305
  • 395