Javadoc overriding methods not inheriting @param descriptions

[tylertian123]

When a method overrides/implements a method from the parent class, the parameter descriptions from @param tags in the parent class are not inherited.

For example, with the following code:

public class Foo {
    /**
     * Foo.foo
     * 
     * @param i an int
     */
    public int foo(int i) {
        return i;
    }
}

public class Bar extends Foo {
    @Override
    public int foo(int i) {
        return i;
    }
}

In the Javadoc hover for Bar.foo(int), the description for the parameter i is empty (screenshot taken from VS Code with the Language Support for Java plugin, which uses the Eclipse JDT Language Server):

For reference, this is what the Javadoc tool outputs:

Which matches the Javadoc tool's documentation, which says that missing @param tags should be inherited.

Originally I opened an issue in the VS Code plugin's repository: redhat-developer/vscode-java#962, but it seems like this is an issue with the language server/JDT instead. I had a friend who uses coc-java in Neovim, which also uses the JDT Language Server, and he also has the same issue:

[fbricon]

@rgrunber this works in Eclipse, so this is a problem specific to jdt.ls

[rgrunber]

I'll try to have look, that is quite odd.

[rgrunber]

This seems to have worked correctly in 0.15.0, after which JavadocContentAccess2 was introduced, so it has been an issue since. I think to really undestand why it's going wrong, it'd be best to compare with Eclipse's approach, which probably does things correctly. I think the code before 0.15.0 just looked up the method being overriden in the hierarchy and directly used that javadoc. The current implementation attempts to rebuild a lot of the javadoc from the various components of the method, and I'm not entirely sure why.

With that said, we could also just fix the existing code for now.. The problem happens at https://github.com/eclipse/eclipse.jdt.ls/blob/master/org.eclipse.jdt.ls.core/src/org/eclipse/jdt/ls/core/internal/javadoc/JavadocContentAccess2.java#L1936 where we need to surround the entire parameter name and description with BLOCK_TAG_ENTRY_START/BLOCK_TAG_ENTRY_END, as it happens in the for-loop directly above.

Here's what the javadoc to be render looks like in both cases :

param description is displayed

This is the foo method.
<ul>
  <li><b>Parameters:</b>
  <ul>
    <li><b>input</b>  the input parameter</li>
  </ul>
</ul>

param description is not displayed

This is the foo method.
<ul>
  <li><b>Parameters:</b>
  <ul>
    <b>input</b>  the input parameter
  </ul>
</ul>

[fbricon]

wow you really went all the way back to 0.15.0??

[rgrunber]

wow you really went all the way back to 0.15.0??

Well, I jumped back based on modifications to JavadocContentAccess2, so there were only about 4 versions to check. I was surprised they all more or less still ran without issue :P