redhat-developer / redhat-developer/vscode-java

Javadoc overriding methods not inheriting @param descriptions

未关闭
#962 6 条评论 1 个 reaction 已指派 0 人 在 GitHub 查看

还没有人认领这个 Issue。

bug hover javadoc
主要语言
TypeScript
星标
2.3k
派生
546
平均合并
20 小时 1 分钟
30 天内合并 PR
11

描述

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;
    }
}
  1. 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:

image

Expected Result

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

image

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.

贡献指南

打开贡献指南

从这里开始

  1. 先读完整个 Issue,再读项目的贡献指南。
  2. 在 Issue 下留言说明你要接手 —— 这能避免两个人做同样的事。
  3. Fork 仓库,在一个分支上完成修改。
  4. 提交 Pull Request,并在描述里引用这个 Issue 编号。

调研方向

首先,使用 issue 中的 Foo 和 Bar Java 文件重现 hover 行为,然后将被重写方法的 Javadoc 与 Javadoc 工具的 HTML 输出进行比较。当继承的 i 的 @param 描述出现在 hover 弹窗中,并且与父方法及文档记录的 Javadoc 行为一致时,该 issue 即完成。

由索引模型根据 Issue 内容生成。

评估

技术栈
java, typescript
领域
developer-experience, tooling
Issue 类型
缺陷
难度
4/5
预计耗时
3-5 天
活跃度
停滞
描述清晰度
基本清楚
新手友好度
35/100

把新 issue 发到你的邮箱

精选适合新手参与的 GitHub issue 摘要。