On Thu, 31 Aug 2023 22:59:57 GMT, Jonathan Gibbons <[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.
>
> test/langtools/jdk/javadoc/doclet/testUknownTags/TestUnknownTags.java line
> 125:
>
>> 123: package x;
>> 124:
>> 125: /**
>
> :-) I bet the spelling checker in the IDE loves this :-)
Initially, I added a snarky code comment, but then removed it before publishing
the PR. Something along the lines: pinch your nose and calm down your IDE.
FWIW, I note two things. Firstly, those tags in test come from these three
sources:
- actual typos in OpenJDK mainline
- actual typos in codebase before it was open-sourced
- made-up typos
Secondly, the significant portion of those tags are actual typos.
-------------
PR Review Comment: https://git.openjdk.org/jdk/pull/15494#discussion_r1312803934
