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

[Kevin Rushforth]

On Thu, 29 Jul 2021 16:18:24 GMT, Kevin Rushforth <k...@openjdk.org> wrote:

> 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)

As a follow-on cleanup bug (for JavaFX 18), we might still want to remove the 
`{@inheritDoc}` from methods where that is the only javadoc tag present.

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

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