Javadoc overriding methods not inheriting @param descriptions

[tylertian123]

EDIT: This issue was originally about the {@inheritDoc} tag, but I realized it's actually caused by something else after some more experimentation.

When method Javadocs are inherited through {@inheritDoc}, the parameter descriptions are not shown in the hover popups.

When hovering over methods that override a parent method, the descriptions for @param tags in the parent's Javadoc are not inherited, which does not match the Javadoc tool's HTML output.

Environment

• Operating System: Ubuntu 18.04/20.04
• JDK version: 11.0.3
• Visual Studio Code version: 1.36.0-insider/1.56.0-insider
• Java extension version: 0.46.0/0.77.0

Steps To Reproduce

1. Open a new folder
2. Create two Java files:

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;
    }
}

3. Hover over the foo method name in Bar to see the Javadoc.

Current Result

When hovering above Bar.foo(int), in the Javadoc popup, the description for the parameter i is empty:

Expected Result

The description for i should be the same as in Foo.foo(int), which is what the Javadoc tool does:

According to the documentation of the Javadoc tool, the missing @param tags should have been inherited from the overridden method. This does work for @return and @throws tags, but not for @param tags.

[Th3OnlyN00b]

I can reproduce this issue. I can attach code if desired.

[BSoDium]

Same issue here, this is very annoying when implementing many interface-specific inherited methods.

[tylertian123]

Upon some more experimentation and a closer look at the Javadoc tool's documentation, I noticed that this actually isn't an issue with the {@inheritDoc} tag. According to the docs, an {@inheritDoc} in the main description should only copy over the main description itself. Putting more {@inheritDoc} tags in @params does work as expected:

public class Bar extends Foo {
    /**
     * {@inheritDoc}
     * 
     * @param i {@inheritDoc}
     */
    @Override
    public void foo(int i) {
        throw new UnsupportedOperationException();
    }
}

With this, the description for i shows up correctly:

However, the main issue is in the way parameter descriptions are inherited in general. According to the docs:

When a main description, or @return, @param or @throws tag is missing from a method comment, the Javadoc tool copies the corresponding main description or tag comment from the method it overrides or implements (if any), according to the algorithm below.
This behavior contrasts with version 1.3 and earlier, where the presence of any main description or tag would prevent all comments from being inherited.

So even if there is text in the main description of the overriding method, as long as there are @param tags missing, their descriptions should be copied over automatically — which the plugin currently does not do. The current behaviour matches "1.3 and earlier" Javadoc versions, which is inconsistent with current versions of the Javadoc tool. I will edit the issue to reflect this.

[BSoDium]

Thank you ! It does indeed work, I just tested it 😄

[tylertian123]

This seems to be an issue in the Eclipse JDT language server instead, since that's what provides the hovers.

[anttijuu]

So the case is still that I should report a similar issue to Eclipse JDT language server project? I am using VS Code with Red Hat Java extensions (macOS).

I have a case where a Java interface class has JavaDocs, one method having a parameter and a @throws. But in the implementation class of that interface, the @throws is not shown when hovering the mouse over the implementation class method.