How can you escape the @ character in javadoc?

Mastering the art of character escaping

Introducing the {@literal} tag

The {@literal} tag is the official way of escaping characters within Javadoc, thereby improving code readability and precision:

/**
 * Here's how you can include {@literal @} in your Javadoc comments.
 */


Instead of cramming character codes into your brain, this more explicit approach makes your intent clear - displaying literal text.

Handling code snippets and nested tags

The {@literal} tag can nest within {@code} tags (and vice versa), particularly inside <pre> blocks, when you're adding code snippets in your Javadoc:

/**
 * Have a look at this example:
 * <pre>
 * {@code
 * // Who said emails can't have {@literal @}?
 * String email = "admin{@literal @}domain.com";
 * }
 * </pre>
 */


Dealing with variable JDK versions

While Javadoc tool version 15.0.2 and later do not require @ to be escaped within {@code} blocks, this is not the case in versions prior to 15.0.2. Always stay updated on JDK bug JDK-8130754 for the latest patches.

Getting technical with character escaping

Trying out octal and hex representations

Besides {@literal}, the escapade continues with the possibility to use @'s octal (\100) or decimal (@) HTML entity representations:

/**
 * Check this out:
 * Decimal: admin@domain.com
 * Octal: admin\100domain.com (Is it 007's secret email ID?)
 */


Balancing readability and tool compatibility

Use {@literal} for clean, human-friendly documentation, but keep in mind that compatibility with Javadoc tools might vary based on version or settings. So, stay alert and do the necessary testing.

Consulting the official manuals

Always keep the official Javadoc documentation handy to stay updated with the best practices for escaping characters.