RFR: JDK-8241780 Allow \n@ inside inline tags.

Jonathan Gibbons jonathan.gibbons at oracle.com
Wed Apr 22 17:27:21 UTC 2020

Please review a change that will permit the use of a previously illegal 
construction, to allow <newline> <spaces> `@` inside inline tags. This 
will allow "<pre>{@code..." constructions that contain annotations, such 
as the following:

     * This is a method.
     * <pre>{@code
     *    @Override
     *    void m() { }
     * }</pre>

Previously, the text was first parsed into the main body and subsequent 
block tags, and only then were those analyzed for inline tags. That 
meant that the example just given was invalid, for having an incomplete 
inline tag between `<pre>` and an apparent block tag named `@Override`. 
With the change, `@` at the beginning of a line inside an inline tag 
will not be treated as the beginning of a block tag, and so the comment 
will parse as might be expected.

The change to the code is as simple as deleting the code that detected 
block tags inside inline tags.

There are some minor compatibility effects.

1. Some comments that were previously invalid may become valid. This is 
the desired effect.

2. Some comments that previously invalid may now be parsed differently. 
In particular, in the case of a genuinely missing '}', the parse will 
now swallow up any block tags that might follow.  For example, consider 
the following:

      * This is a method.
      * @param p1 this has an unbalanced {@code description
      * @param p2 this is the second parameter
     void m(int p1, int p2) { }

As a result of the change, the description for parameter p2 will be 
swallowed up as part of the invalid description for p1. This will only 
be visible in error messages and clients of the API that analyze 
erroneous comments.

The tests are updated to accommodate the change. A specific test for the 
`<pre>{@code...}</pre>` construction is added.  The biggest change is to 
the test code that "predicts" the output of the AST pretty printer, 
which is now updated to better handle the new behavior of `{@code}` and 
`{@literal}` tags.

-- Jon

JBS: https://bugs.openjdk.java.net/browse/JDK-8241780
Webrev: http://cr.openjdk.java.net/~jjg/8241780/webrev.00/index.html

More information about the compiler-dev mailing list