RFR: 8288660: JavaDoc should be more helpful if it doesn't recognize a tag

[Hannes Wallnöfer]

On Wed, 30 Aug 2023 16:34:58 GMT, Pavel Rappo <prappo at openjdk.org> wrote:

> This PR makes JavaDoc and DocLint produce more helpful diagnostic output when encounter an unknown tag.
> 
> Before:
> 
> 
> MyClass.java:4: warning: no main description
>  * @implSpite {@linkpain Object#hashCode}}
>    ^
> MyClass.java:4: error: unknown tag: implSpite
>  * @implSpite {@linkpain Object#hashCode}}
>    ^
> MyClass.java:4: error: unknown tag: linkpain
>  * @implSpite {@linkpain Object#hashCode}}
>               ^
> MyClass.java:5: error: unknown tag: danger
>  * @danger
>    ^
> 
> 
> After:
> 
> 
>  * @implSpite {@linkpain Object#hashCode}}
>    ^
> MyClass.java:4: error: unknown tag: implSpite; the most similar tags are: implSpec, implNote
>  * @implSpite {@linkpain Object#hashCode}}
>    ^
> Note: An unknown tag has been reported. Mistyped? Forgot to add a custom tag or register a taglet?
> MyClass.java:4: error: unknown tag: linkpain; the most similar tags are: linkplain
>  * @implSpite {@linkpain Object#hashCode}}
>               ^
> MyClass.java:5: error: unknown tag: danger
>  * @danger
>    ^
> 
> 
> As you can see, the output has changed in two ways. Firstly, the tags that are similar to the unknown tag might be suggested. Secondly, an auxiliary note to help troubleshoot the unknown tag is provided. That note is provided once, close to the first reported unknown tag. This is done to not clutter the output in case multiple tags are reported.
> 
> For details, see the actual change.

I really like this feature, but my immediate reaction is to also worry about decreased readability caused by increased verbosity. Some ideas:

 - `the most similar tags are: ...` is quite long, and there are now 4 colon characters in that message line. Maybe the message could be something like `unknown tag implSpite, did you mean implSpec, implNote`?
 - The `Note: An unknown tag has been reported...` message after the first unrecognized tag is a bit disruptive. I'm not sure it is needed, and if we want it maybe it should be at the end of the output? I have an open JBS issue to [generate a final message if any invalid input was encountered](https://bugs.openjdk.org/browse/JDK-8296175), maybe this would also benefit from such handling?

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

PR Comment: https://git.openjdk.org/jdk/pull/15494#issuecomment-1700648869