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.gibb...@oracle.com <mailto:jonathan.gibb...@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
