On Tue, 5 Sep 2023 09:19:34 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.
>
> 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
