On Wed, 30 Aug 2023 16:34:58 GMT, Pavel Rappo <[email protected]> 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
