redhat-developer / redhat-developer/vscode-java
Javadoc overriding methods not inheriting @param descriptions
Nobody has claimed this yet.
- Dominant language
- TypeScript
- Stars
- 2.3k
- Forks
- 546
- Avg merge
- 20h 1m
- Merged PRs (30d)
- 11
Description
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
- Open a new folder
- 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;
}
}
- Hover over the
foomethod name inBarto 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.
Contributor guide
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
Research direction
Start by reproducing the hover behavior with the Foo and Bar Java files from the issue, then compare the overridden method's Javadoc with the Javadoc tool's HTML output. The issue is done when the inherited @param description for i appears in the hover popup, matching the parent method and the documented Javadoc behavior.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- java, typescript
- Domain
- developer-experience, tooling
- Issue type
- Bug
- Difficulty
- 4/5
- Estimated time
- 3-5 days
- Activity status
- Stale
- Clarity
- Mostly clear
- Newbie friendliness
- 35/100