In Java, Javadoc is an essential tool for generating API documentation directly from Java source code. However, when documenting your code, you might encounter situations where you need to include the @ character in your comments. The @ character is significant in Javadoc as it denotes tags like @param, @return, etc. To include @ as part of your descriptive text without Javadoc interpreting it as a tag, you need to escape it correctly.

Escaping the @ Character in Javadoc

Understanding the Need for Escaping

In Javadoc comments, the @ character indicates the beginning of a tag. Tags define specific properties or metadata about methods or classes. For instance:

• @param specifies information about method parameters.
• @return provides details about what a method returns.

If you want to use the @ character itself as part of your documentation (for example, mentioning an email address like [email protected]), you must ensure Javadoc interprets it as a plain character rather than a special tag.

How to Escape @

You can escape the @ character by using the @ HTML entity. This entity represents the @ character in HTML and Javadoc will render it correctly as @.

Example Usage

1/**
2 * This is a sample method demonstrating how to escape the @ character.
3 * 
4 * `@sampleTag` is a custom Javadoc tag.
5 * 
6 * `Example usage of the escape sequence:`
7 * - Email: user@example.com
8 * - Twitter: @javadev
9 *
10 * @param  input  This is a parameter to demonstrate Javadoc tags.
11 * @return        Returns a string containing escaped @ symbol.
12 */
13public String sampleMethod(String input) {
14    return "Escaping demonstration";
15}

In the example above:

• The email user@example.com will be rendered as [email protected].
• The Twitter handle @javadev will display as @javadev.

Best Practices and Considerations

1. Readability: Ensure that the use of escaped characters does not hamper the readability of the code. Commenting should remain as clear and comprehensible to human readers as possible.
2. Documentation Tools: When using various documentation generation tools, verify how they handle HTML or Javadoc entities to ensure that the output is as expected.
3. Custom Javadoc Tags: If working with custom Javadoc tags, make sure to validate that there are no conflicts with similar notations within the document.

Using Inline HTML in Javadoc

Apart from escaping specific characters, Javadoc supports a subset of HTML, which can be used to format text effectively or include additional HTML entities as needed.

Example Usage of HTML Tags

1/**
2 * Demonstrates the use of inline HTML in Javadoc.
3 * 
4 * <p>This is a paragraph describing the method `with` HTML support.</p>
5 * 
6 * <ul>
7 *   <li>Use `&#64;` for escaping the at symbol.</li>
8 *   <li>Italics can be applied with `<em>tags</em>`.</li>
9 *   <li>Bold text can be used in `<strong>tags</strong>`.</li>
10 * </ul>
11 *
12 * @return A string which includes inline HTML.
13 */
14public String htmlUsageMethod() {
15    return "Javadoc inline HTML example";
16}

Summary Table

In summary, escaping the @ character in Javadoc enables developers to provide clear and precise documentation without misinterpretation due to reserved tags. By using @ and leveraging HTML formatting, you can ensure your documents are both functional and easy to understand.