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