Summary

Allow @ as an escape character in documentation comments.

Problem

Some characters or character sequences are difficult or inconvenient to represent in documentation comments. These include the following:

• inhibiting the interpretation of @ as part of the introduction of a block or inline tag,
• providing an asterisk that should not be discarded after whitespace at the beginning of a line, and
• using the character sequence */ in a block comment without terminating that comment.

The first can currently be avoided by using the {@literal} tag or the @ entity; the second can be avoided by using an additional asterisk and whitespace, which may be against the author's coding style; the last can only be avoided by using entities in some way, such as */ or by separating the characters, such as with a zero-width space or by enclosing one of the characters inside an inline tag.

Solution

Allow the use of @ to introduce an escape sequence to simplify these use cases.

Specification

The following text is added to the Document Comment Specification:

@@ -129,6 +129,28 @@ indentation preserved.
 Spaces are interpreted by browsers more uniformly than tabs. Indentation is
 relative to the left margin (rather than the separator `/**` or `<pre>` tag).

+### Escape Sequences
+
+The following escape sequences are supported wherever text, entities and HTML 
+may appear, to represent characters that would otherwise be inconvenient or 
+difficult to represent:
+
+* `@@`, to represent `@`, to prevent it from being interpreted as part of the
+  introduction of a [block](#block-tags) or [inline](#inline-tags) tag,
+* `@/`, to represent `/`, as part of `*@/` to represent `*/`, to avoid
+  prematurely terminating the enclosing comment,
+* `@*`, to represent `*`, where it would otherwise be [discarded](#leading-asterisks)
+  at the beginning of a line.
+
+Escape sequences are context-sensitive, and can only be used where the
+use of the escaped character by itself would have a different syntactic 
+interpretation. In other situations, these charac ter sequences are taken 
+literally, without additional interpretation.
+
+Escape sequences cannot be used in inline tags that contain literal text; 
+this includes [`
{@code}
`](#code), [`
{@literal}
`](#literal), [`
{@snippet}
`](#snippet),
+and user-defined tags.
+
 ## References

 References are the constructs in a documentation comment that refer to

In addition, a new subtype of DocTree is added, to represent the use of an escape sequence. Corresponding new methods are added to the visitor and scanner classes. These are described in the attached spec diff, also available at http://cr.openjdk.java.net/~jjg/8300914/