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

Pavel Rappo prappo at openjdk.org
Tue Sep 5 09:19:36 UTC 2023 

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.

Full disclosure. Below is the test output. Note that some tags are not recognized as similar enough, and that's fine. Catering for them would complicate the code. 


testSimilarTags/src/x/MyClass.java:4: error: unknown tag. Mistyped @code or an unregistered custom tag?
 * {@cod}
   ^
testSimilarTags/src/x/MyClass.java:5: error: unknown tag. Unregistered custom tag?
 * {@codejdk.net.hosts.file}
   ^
testSimilarTags/src/x/MyClass.java:6: error: unknown tag. Mistyped @code or an unregistered custom tag?
 * {@coe}
   ^
testSimilarTags/src/x/MyClass.java:7: error: unknown tag. Mistyped @code or an unregistered custom tag?
 * {@cpde}
   ^
testSimilarTags/src/x/MyClass.java:8: error: unknown tag. Mistyped @code or an unregistered custom tag?
 * {@ocde}
   ^
testSimilarTags/src/x/MyClass.java:9: error: unknown tag. Mistyped @code or an unregistered custom tag?
 * {@ode}
   ^
testSimilarTags/src/x/MyClass.java:11: error: unknown tag. Mistyped @author or an unregistered custom tag?
 * @auther
   ^
testSimilarTags/src/x/MyClass.java:13: error: unknown tag. Mistyped @deprecated or an unregistered custom tag?
 * @Depricated
   ^
testSimilarTags/src/x/MyClass.java:14: error: unknown tag. Mistyped @deprecated or an unregistered custom tag?
 * @deprecation
   ^
testSimilarTags/src/x/MyClass.java:16: error: unknown tag. Mistyped @docRoot or an unregistered custom tag?
 * @DocRoot
   ^
testSimilarTags/src/x/MyClass.java:17: error: unknown tag. Mistyped @docRoot or an unregistered custom tag?
 * @dccRoot
   ^
testSimilarTags/src/x/MyClass.java:18: error: unknown tag. Mistyped @docRoot or an unregistered custom tag?
 * @docroot
   ^
testSimilarTags/src/x/MyClass.java:20: error: unknown tag. Mistyped @exception or an unregistered custom tag?
 * @ecception
   ^
testSimilarTags/src/x/MyClass.java:21: error: unknown tag. Mistyped @exception or an unregistered custom tag?
 * @excception
   ^
testSimilarTags/src/x/MyClass.java:22: error: unknown tag. Mistyped @exception or an unregistered custom tag?
 * @exceptbion
   ^
testSimilarTags/src/x/MyClass.java:23: error: unknown tag. Mistyped @exception or an unregistered custom tag?
 * @exceptino
   ^
testSimilarTags/src/x/MyClass.java:24: error: unknown tag. Mistyped @exception or an unregistered custom tag?
 * @exceptions
   ^
testSimilarTags/src/x/MyClass.java:25: error: unknown tag. Mistyped @exception or an unregistered custom tag?
 * @exceptoin
   ^
testSimilarTags/src/x/MyClass.java:26: error: unknown tag. Mistyped @exception or an unregistered custom tag?
 * @execption
   ^
testSimilarTags/src/x/MyClass.java:28: error: unknown tag. Mistyped @implNote or an unregistered custom tag?
 * @implnote
   ^
testSimilarTags/src/x/MyClass.java:30: error: unknown tag. Mistyped @inheritDoc or an unregistered custom tag?
 * @inheritdoc
   ^
testSimilarTags/src/x/MyClass.java:31: error: unknown tag. Mistyped @inheritDoc or an unregistered custom tag?
 * @inherotDoc
   ^
testSimilarTags/src/x/MyClass.java:32: error: unknown tag. Mistyped @inheritDoc or an unregistered custom tag?
 * @inheretdoc
   ^
testSimilarTags/src/x/MyClass.java:33: error: unknown tag. Mistyped @inheritDoc or an unregistered custom tag?
 * @inhertitDoc
   ^
testSimilarTags/src/x/MyClass.java:35: error: unknown tag. Mistyped @jvms or an unregistered custom tag?
 * @jvm
   ^
testSimilarTags/src/x/MyClass.java:36: error: unknown tag. Mistyped @jvms or an unregistered custom tag?
 * @jmvs
   ^
testSimilarTags/src/x/MyClass.java:38: error: unknown tag. Mistyped @link or an unregistered custom tag?
 * @Link
   ^
testSimilarTags/src/x/MyClass.java:39: error: unknown tag. Mistyped @link or an unregistered custom tag?
 * @linK
   ^
testSimilarTags/src/x/MyClass.java:40: error: unknown tag. Mistyped @link or an unregistered custom tag?
 * @linbk
   ^
testSimilarTags/src/x/MyClass.java:41: error: unknown tag. Mistyped @link or an unregistered custom tag?
 * @lini
   ^
testSimilarTags/src/x/MyClass.java:42: error: unknown tag. Mistyped @link or an unregistered custom tag?
 * @linke
   ^
testSimilarTags/src/x/MyClass.java:43: error: unknown tag. Mistyped @link or an unregistered custom tag?
 * @linked
   ^
testSimilarTags/src/x/MyClass.java:45: error: unknown tag. Mistyped @linkplain or an unregistered custom tag?
 * @linkplan
   ^
testSimilarTags/src/x/MyClass.java:47: error: unknown tag. Mistyped @param or an unregistered custom tag?
 * @params
   ^
testSimilarTags/src/x/MyClass.java:48: error: unknown tag. Mistyped @param or an unregistered custom tag?
 * @pararm
   ^
testSimilarTags/src/x/MyClass.java:49: error: unknown tag. Mistyped @param or an unregistered custom tag?
 * @parasm
   ^
testSimilarTags/src/x/MyClass.java:50: error: unknown tag. Mistyped @param or an unregistered custom tag?
 * @parem
   ^
testSimilarTags/src/x/MyClass.java:51: error: unknown tag. Mistyped @param or an unregistered custom tag?
 * @parm
   ^
testSimilarTags/src/x/MyClass.java:52: error: unknown tag. Mistyped @param or an unregistered custom tag?
 * @parma
   ^
testSimilarTags/src/x/MyClass.java:53: error: unknown tag. Mistyped @param or an unregistered custom tag?
 * @praam
   ^
testSimilarTags/src/x/MyClass.java:54: error: unknown tag. Unregistered custom tag?
 * @prarm
   ^
testSimilarTags/src/x/MyClass.java:56: error: unknown tag. Mistyped @return or an unregistered custom tag?
 * @Return
   ^
testSimilarTags/src/x/MyClass.java:57: error: unknown tag. Mistyped @return or an unregistered custom tag?
 * @eturn
   ^
testSimilarTags/src/x/MyClass.java:58: error: unknown tag. Unregistered custom tag?
 * @result
   ^
testSimilarTags/src/x/MyClass.java:59: error: unknown tag. Mistyped @return or an unregistered custom tag?
 * @retrun
   ^
testSimilarTags/src/x/MyClass.java:60: error: unknown tag. Mistyped @return or an unregistered custom tag?
 * @retuen
   ^
testSimilarTags/src/x/MyClass.java:61: error: unknown tag. Mistyped @return or an unregistered custom tag?
 * @retun
   ^
testSimilarTags/src/x/MyClass.java:62: error: unknown tag. Mistyped @return or an unregistered custom tag?
 * @retunr
   ^
testSimilarTags/src/x/MyClass.java:63: error: unknown tag. Mistyped @return or an unregistered custom tag?
 * @retur
   ^
testSimilarTags/src/x/MyClass.java:64: error: unknown tag. Mistyped @return or an unregistered custom tag?
 * @returns
   ^
testSimilarTags/src/x/MyClass.java:65: error: unknown tag. Mistyped @return or an unregistered custom tag?
 * @returnss
   ^
testSimilarTags/src/x/MyClass.java:66: error: unknown tag. Mistyped @return or an unregistered custom tag?
 * @retursn
   ^
testSimilarTags/src/x/MyClass.java:67: error: unknown tag. Mistyped @return or an unregistered custom tag?
 * @rturn
   ^
testSimilarTags/src/x/MyClass.java:69: error: unknown tag. Mistyped @see or an unregistered custom tag?
 * @See
   ^
testSimilarTags/src/x/MyClass.java:70: error: unknown tag. Mistyped @see or an unregistered custom tag?
 * @gsee
   ^
testSimilarTags/src/x/MyClass.java:72: error: unknown tag. Mistyped @serialData or an unregistered custom tag?
 * @serialdata
   ^
testSimilarTags/src/x/MyClass.java:74: error: unknown tag. Mistyped @since or an unregistered custom tag?
 * @sinc
   ^
testSimilarTags/src/x/MyClass.java:75: error: unknown tag. Mistyped @since or an unregistered custom tag?
 * @sine
   ^
testSimilarTags/src/x/MyClass.java:77: error: unknown tag. Mistyped @systemProperty or an unregistered custom tag?
 * @systemproperty
   ^
testSimilarTags/src/x/MyClass.java:79: error: unknown tag. Mistyped @throws or an unregistered custom tag?
 * @thows
   ^
testSimilarTags/src/x/MyClass.java:80: error: unknown tag. Mistyped @throws or an unregistered custom tag?
 * @thrown
   ^
testSimilarTags/src/x/MyClass.java:81: error: unknown tag. Mistyped @throws or an unregistered custom tag?
 * @throwss
   ^

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

PR Comment: https://git.openjdk.org/jdk/pull/15494#issuecomment-1706242946

More information about the compiler-dev mailing list