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

[Jonathan Gibbons]

On Tue, 5 Sep 2023 09:19:34 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.
>
> Pavel Rappo has updated the pull request with a new target base due to a merge or a rebase. The incremental webrev excludes the unrelated changes brought in by the merge/rebase. The pull request contains three additional commits since the last revision:
> 
>  - Shorten messages and simplify diagnostics
>  - Merge branch 'master' into 8288660
>  - Initial commit

Marked as reviewed by jjg (Reviewer).

src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclint/resources/doclint.properties line 88:

> 86: dc.tag.start.unmatched = end tag missing: </{0}>
> 87: dc.tag.unknown = unknown tag. Unregistered custom tag?
> 88: dc.tag.unknown.with.hint = unknown tag. Mistyped @{0} or an unregistered custom tag?

"one of these days", we will come up with a general style guide for diagnostic messages, and the (mixed) use of phrases and sentences!

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

PR Review: https://git.openjdk.org/jdk/pull/15494#pullrequestreview-1611662596
PR Review Comment: https://git.openjdk.org/jdk/pull/15494#discussion_r1316235262