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

[Pavel Rappo]

On Thu, 31 Aug 2023 22:59:57 GMT, Jonathan Gibbons <jjg 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.
>
> 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