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

[Jonathan Gibbons]

On Wed, 30 Aug 2023 16:34:58 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.

I like the detection for misspellings.
I'm less convinced (at this time) by the helpful suggestion, but maybe it would eventually be OK when viewed in the context of a broader effort to give help hints, with some stylistic consistency as to their format.

I wonder if it would be interesting to treat helpful hints as a subcategory of notes so that all hints can be enabled or disabled with a single option. (i.e. we shouldn't change the distinction of `error`/`warning`/`note` but we might want to be able to identify "all hints", perhaps by a convention in the key name, etc.

src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/toolkit/resources/doclets.properties line 122:

> 120: doclet.UnknownTagWithHint={0} is an unknown tag; the most similar tags are: {1}
> 121: doclet.UnknownTagHelp=An unknown tag has been reported. Mistyped? \
> 122:   Forgot to add a custom tag or register a taglet?

This is a bit terse. I'd suggest to split it in two lines, the first containing a statement of fact. (`An unknown tag has been reported.`), and the second containing a more complete helpful sentence, such as "Did you mistype it, or forget to add a custom tag, or register a taglet?"

I know I suggested posting the message early, but if you post it at the end, it could be more of a summary, such as "5 different tags were reported 105 times; did you ..."

src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclint/DocLint.java line 380:

> 378: 
> 379:     public static List<String> suggestSimilar(Collection<String> knownTags, String unknownTag) {
> 380:         final double MIN_SIMILARITY = 2.0 / 3;

Is there significance in `2.0 / 3` as compared to `0.667` etc

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

> 88: dc.tag.unknown.with.hint = unknown tag: {0}; the most similar tags are: {1}
> 89: dc.tag.unknown.help = An unknown tag has been reported. Mistyped? \
> 90:   Forgot to add a custom tag or register a taglet?

Mild uugh at duplicate strings; maybe it's OK for now but is another reason to consolidate docent/javadoc behavior.

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 :-)

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

PR Review: https://git.openjdk.org/jdk/pull/15494#pullrequestreview-1605878689
PR Review Comment: https://git.openjdk.org/jdk/pull/15494#discussion_r1312362450
PR Review Comment: https://git.openjdk.org/jdk/pull/15494#discussion_r1312363282
PR Review Comment: https://git.openjdk.org/jdk/pull/15494#discussion_r1312365309
PR Review Comment: https://git.openjdk.org/jdk/pull/15494#discussion_r1312365775