redhat-developer / redhat-developer/vscode-java

Javadoc overriding methods not inheriting @param descriptions

Offen
#962 6 Kommentare 1 Reaktion 0 zugewiesene Personen Auf GitHub ansehen

Dieses Issue hat noch niemand übernommen.

bug hover javadoc
Vorherrschende Sprache
TypeScript
Sterne
2.3k
Forks
546
Ø Merge
20 Std. 1 Min.
Gemergte PRs (30 T.)
11

Beschreibung

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.

Beitragsleitfaden

Beitragsleitfaden öffnen

Erste Schritte

  1. Lies das ganze Issue und danach den Beitragsleitfaden des Projekts.
  2. Schreib ins Issue, dass du es übernimmst — das erspart doppelte Arbeit.
  3. Forke das Repository und arbeite in einem Branch.
  4. Öffne einen Pull Request, der die Issue-Nummer nennt.

Rechercherichtung

Beginne damit, das Hover-Verhalten mit den Java-Dateien Foo und Bar aus dem Issue zu reproduzieren, und vergleiche dann den Javadoc-Text der überschriebenen Methode mit der HTML-Ausgabe des Javadoc-Tools. Das Issue ist abgeschlossen, wenn die geerbte @param-Beschreibung für i im Hover-Popup erscheint und mit der übergeordneten Methode sowie dem dokumentierten Javadoc-Verhalten übereinstimmt.

Vom Indexierungsmodell aus dem Issue-Text verfasst.

Bewertung

Tech-Stack
java, typescript
Bereich
developer-experience, tooling
Issue-Typ
Bug
Schwierigkeit
4/5
Geschätzter Aufwand
3-5 Tage
Aktivitätsstatus
Veraltet
Klarheit
Größtenteils klar
Anfängerfreundlichkeit
35/100

Neue Issues direkt in Ihr Postfach

Eine kurze Übersicht über anfängerfreundliche GitHub-Issues.