[jfx17] RFR: 8271485: Javadoc "Method Summary" table is misaligned if overridden JDK method has {@inheritDoc} tag

Kevin Rushforth kcr at openjdk.java.net
Thu Jul 29 16:22:44 UTC 2021


As noted in the JBS bug report, the javadoc-generated HTML table for a class is messed up if any method is overridden from a core JDK class and has the `{@inheritDoc}` tag. For example, the following taken from the [Background](https://github.com/openjdk/jfx/blob/jfx17/modules/javafx.graphics/src/main/java/javafx/scene/layout/Background.java#L622) class provokes this bug:


    /**
     * {@inheritDoc}
     */
    @Override public boolean equals(Object o) {


The proposed fix is to stop generating javadocs for overridden methods with no spec change. This matches how the JDK docs have been generated since JDK 10. See [JDK-8157000](https://bugs.openjdk.java.net/browse/JDK-8157000). This is done by running `javadoc` with the `--override-methods=summary` option.

There is no useful information generated for such overridden methods regardless of whether or not they use the `{@inheritDoc}` tag, so this fix also addresses the problem of having methods with no description.

See the attached "before" and "after" images.

Before:

![javadoc-before](https://user-images.githubusercontent.com/34689748/127527754-ae5c529a-8c49-47a2-b595-5e423f5c9c49.png)

After:

![javadoc-after](https://user-images.githubusercontent.com/34689748/127527789-c97c4689-154f-4ed0-a4a1-5dfdfde0d9d2.png)

-------------

Commit messages:
 - 8271485: Javadoc "Method Summary" table is misaligned if overriden JDK method has {@inheritDoc} tag

Changes: https://git.openjdk.java.net/jfx/pull/593/files
 Webrev: https://webrevs.openjdk.java.net/?repo=jfx&pr=593&range=00
  Issue: https://bugs.openjdk.java.net/browse/JDK-8271485
  Stats: 4 lines in 1 file changed: 4 ins; 0 del; 0 mod
  Patch: https://git.openjdk.java.net/jfx/pull/593.diff
  Fetch: git fetch https://git.openjdk.java.net/jfx pull/593/head:pull/593

PR: https://git.openjdk.java.net/jfx/pull/593


More information about the openjfx-dev mailing list