On Thu, 31 Aug 2023 22:55:08 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.
>
> 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
No. I can change it if you want me to.
-------------
PR Review Comment: https://git.openjdk.org/jdk/pull/15494#discussion_r1312795253
