The doclet "comment inheritance algorithm" spec conformance

[Jonathan Gibbons]

javadoc has some changes/fixes/enhancements in this area in JDK 22, both 
in the code and the Doc Comment Specification.

The intent is to better align the lookup for inherited comments with the 
general lookup rules in JLS.

-- Jon

On 2/6/24 7:14 AM, I Al Istannen wrote:
> Hey,
>
> I hope this is the right place to ask :)
>
> I was recently implementing javadoc comment inheritance for spoon[0] 
> and verified it against IntelliJ IDEA and the standard html doclet. 
> While doing this I found out that IntelliJ and the standard doclet 
> disagree on comment inheritance in this example[1]. The doclet 
> algorithm documented in [2] specifies the following:
>
>  1. Look in each directly implemented (or extended) interface in the
>     order they appear following the word implements (or extends) in
>     the type declaration. /Use the first documentation comment found
>     for this method./
>  2. If Step 1 failed to find a documentation comment, then recursively
>     apply this entire algorithm to each directly implemented (or
>     extended) interface in the same order they were examined in Step 1.
>
> This seems to imply that resolution proceeds in two phases. First, you 
> look at the direct super interfaces and see if any doc comment there 
> contains what you need. If this does not result in a value /after/ 
> looking at /all/ super interfaces, you try finding it recursively in 
> each super interface, again in declaration order.
>
> If we now apply this to find the body in the example[1]:
>
>  1. Look at the javadoc in SuperInt2, find no body
>  2. Look at the javadoc in SuperInt3, find the body
>     "Neverused,shadowedbybodyinsuperint1."
>  3. Return this value. Body is now "Neverused,shadowedbybodyinsuperint1."
>
> This is the behaviour you can observe in IntelliJ IDEA, as they split 
> this logic into two distinct phases[3]. It is, however, not the 
> behaviour of the standard doclet. The standard doclet finds the body 
> "Atest." declared in SuperInt1, which SuperInt2 extends from. After 
> glancing at the doclet source code, the doclet seems to /directly/ 
> explore the full inheritance hierarchy for every superinterface by 
> doing a depth-first search[4], effectively interleaving step 1 and 2.
>
> I was whipping up a patch for IntelliJ, but I am actually not sure it 
> is wrong. My spoon resolver code mirrors the JDK code by pure 
> coincidence, but I think the spec agrees with IntelliJ here. Is this a 
> bug in the standard doclet, is the specification outdated/wrong or did 
> I miss something?
>
> Have a nice day!
> I Al Istannen
>
> [0] https://github.com/INRIA/spoon/, 
> https://github.com/INRIA/spoon/blob/master/spoon-javadoc/src/main/java/spoon/javadoc/api/parsing/InheritanceResolver.java
> [1] https://gist.github.com/I-Al-Istannen/a95125d20319a999d2255a7fe086e768
> [2] 
> https://docs.oracle.com/en/java/javase/21/docs/specs/javadoc/doc-comment-spec.html
> [3] 
> https://github.com/JetBrains/intellij-community/blob/4f20bcc65cd08c53e4734bbe302480eb9b31515d/java/java-impl/src/com/intellij/codeInsight/javadoc/JavaDocInfoGenerator.java#L3076
> [4] 
> https://github.com/openjdk/jdk/blob/e9d19d0fffc47119d0d4f756833ec87cd0a6331e/src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/toolkit/util/Utils.java#L2832
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <https://mail.openjdk.org/pipermail/javadoc-dev/attachments/20240206/0625ab64/attachment-0001.htm>