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

[Jonathan Gibbons]

On 4/22/20 3:23 PM, John Rose wrote:
> Really nice!  Does this change the specification, or is this a
> change that aligns the implementation with the specification?
> (You know I’ve pestered in the past about “where’s the specification”
> but I forget where that conversation ended.)

Technically, it's a change to an unwritten part of the spec, which has not
previously correlated block tags and inline tags.  I intend to update the
spec, which can be found in the JDK docs/specs directory, or linked to
from the jdk.javadoc module page.


>
> On Apr 22, 2020, at 10:27 AM, Jonathan Gibbons 
> <jonathan.gibbons at oracle.com <mailto:jonathan.gibbons at oracle.com>> wrote:
>>
>> 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.
>
> Suggestion:  *If* there’s an error due to missing “}”, then it might
> be friendly to report the error up to the end of the line of the last
> open inline tag, rather than the end of the whole javadoc.  Basically,
> gobble until the end of the javadoc, in hopes of finding the errant
> “}” braces, but if they are missing, just report context up to the
> end of the line.  This is just a nit, and maybe the error messages
> won’t be burdened with the failed gobble-to-eof for some other
> reason.  I suppose there’s already a solution in place, to make the
> failure message clear enough, since this error can happen even
> without the new change.

I was speaking loosely when talking about error messages, and did
not mean to imply that a longer message may be generated.  For
both javac and javadoc, error messages are of the form of a line
of source with a caret somewhere underneath.

What I was more trying to convey is that the amount consumed
might vary in the case of unmatched '{' characters.  Consider this:

     /**
      * This is a method.
      * @param p1 this is {@code p1
      * @param p2 this is {@code p2
      */

Previously, you would get two messages, for the bad {@code
in each @param.
Now, the first {@code will consume the rest of the comment
and so you will not get a syntax error for the second @param.

I only list this case for completeness; I am not worried about
error message consistency in these two cases.  In both cases,
there's an error that will be reported, and the error recovery
differs.

OK, for perversity, I note the following used to fail, and
will now be accepted.

     /**
      * This is a method.
      * @param p1 this is {@code p1
      * @param p2 here is a brace: }
      */


>
> — John
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <https://mail.openjdk.java.net/pipermail/javadoc-dev/attachments/20200422/fd2c8549/attachment-0001.htm>