JDK-8271485 : Javadoc "Method Summary" table is misaligned if overridden JDK method has {@inheritDoc} tag
  • Type: Bug
  • Component: javafx
  • Sub-Component: build
  • Affected Version: openjfx17
  • Priority: P3
  • Status: Resolved
  • Resolution: Fixed
  • OS: generic
  • CPU: generic
  • Submitted: 2021-07-29
  • Updated: 2021-10-26
  • Resolved: 2021-08-10
The Version table provides details related to the release that this issue/RFE will be addressed.

Unresolved : Release in which this issue/RFE will be addressed.
Resolved: Release in which this issue/RFE has been resolved.
Fixed : Release in which this issue/RFE has been fixed. The release containing this fix may be available for download as an Early Access Release or a General Availability Release.

To download the current JDK release, click here.
Other
openjfx17Fixed
Related Reports
Blocks :  
JDK-8271083 - ☂ Missing documentation in JavaFX API
Relates :  
JDK-8250590 - Classes and methods in the javafx.css package are missing documentation
Relates :  
JDK-8227765 - {@inheritDoc} does not work for methods inherited from the JDK
Relates :  
JDK-8157000 - Do not generate javadoc for overridden method with no spec change
Description
The Javadoc HTML table for a class is messed up if any of the method documentation contains {@inheritDoc} tag.

This is specifically observed with openjfx17 javadoc, which are built with JDK 16.

It is not observed with openjfx16 javadoc which were build with JDK 15.

This came up during review of JDK-8250590.
See - https://github.com/openjdk/jfx/pull/589#issuecomment-888949660

It looks like this is the result of a javadoc tool bug that was introduced in JDK 16, although even in earlier versions of the JDK, the table has some problems with styling on the rows with overridden methods.
Comments
Changeset: fbeb0bbd Author: Kevin Rushforth <kcr@openjdk.org> Date: 2021-08-10 12:19:55 +0000 URL: https://git.openjdk.java.net/jfx/commit/fbeb0bbd1cec6616b01e8376013f833a191124e8
10-08-2021
We need to fix this for JavaFX 17. I can see three possible solutions: 1. Remove all `{@inheritDoc}` tags from overridden JDK methods 2. Build the javadocs with JDK 17 (this is a bit problematic) 3. Add the "--override-methods=summary" flag to suppress overridden methods that don't have additional documentation, which will avoid generating docs for the overridden methods in the first place I recommend option 3, since we don't currently get any useful documentation for the overridden methods and it matches the way the JDK docs are generated. The thinking behind the JDK change in JDK 10 (see JDK-8157000) is that there is no purpose in adding an entry for a method, such as toString or hashCode that you are only overriding to provide an implementation in the subclass. Unless there are API implications that a user of the API needs to know about, this is just an implementation detail and need not be in the generated docs. In we go with option 3, then we should probably also do option 1 as a cleanup step in JavaFX 18
29-07-2021