RFR: JDK-8264181: javadoc tool Incorrect error message about malformed link

[Hannes Wallnöfer]

On Mon, 17 May 2021 16:54:07 GMT, Hannes Wallnöfer <hannesw at openjdk.org> wrote:

> The primary problem was that key `compiler.err.dc.ref.bad.parens` had the wrong message "')' missing in reference". That error message is not used when the right parenthesis is missing, but when it occurs before the end of the signature. The missing parenthesis case is caught earlier by the parens balancing code in `DocCommentParser#reference` and uses message `compiler.err.dc.unterminated.signature` ("unterminated signature").
> 
> I changed the message for `compiler.err.dc.ref.bad.parens` to "unexpected parenthesis". 
> 
> A secondary problem was that `DocCommentParser#reference` also threw "unterminated signature" when there were too many closing angle brackets or parentheses. These cases are now passed through in`DocCommentParser#reference` so that `ReferenceParser#parse` can throw a more appropriate error ("unexpected parenthesis" or "unexpected input"). 
> 
> Here's a list of what references now cause what error messages:
> 
>  - `#foo(int`     `unterminated signature`
>  - `#foo((int))`   `unexpected parenthesis`
>  - `#foo(int))`   `unexpected parenthesis`
>  - `#foo(int)x`   `unexpected parenthesis`
>  - `F<T`        `unterminated signature`
>  - `F<T>>`    `unexpected input`
> 
> I added two new tests for the cases with too many closing brackets/parens that used to fail with "unterminated signature".

Thanks for reviewing, Pavel!

>     1. I think this error is a counterintuitive:
>        ```
>        #foo(int)x
>        error: unexpected parenthesis
>        ```
> 
> 
> It's `x` that is unexpected, not the parenthesis. It looks correct here, but only coincidentally:
> 
> ```
>    #foo(int))
>    error: unexpected parenthesis
> ```

Yes, you can look at it both ways, either there is a closing parenthesis where it shouldn't be, or there is text following a correctly placed closing parenthesis. We tend to see one or the other depending on whether the text up to the closing parenthesis looks like a proper signature, but it's not as clear to the parser. 

I still like the more specific message. We can use a more generic "unexpected text" message, but I think it is less useful.

>     1. The latter case in your list, `F<T>>`, yields "unexpected text", not "unexpected input".

That's my mistake, the resource key ends with `unexpected.input` but the English message is "unexpected text".

>     2. Why is there an asymmetry between wording for angle brackets and that of parenthesis?

See my answer to point 1, I like the message to be as specific as possible.

-------------

PR: https://git.openjdk.java.net/jdk/pull/4068