JDK-8264217 : Overriding method with absent spec is not mentioned as overriding in the JavaSE class specification
  • Type: Bug
  • Component: tools
  • Sub-Component: javadoc(tool)
  • Affected Version: 10,11,12,13,14,15,16,17
  • Priority: P2
  • Status: Resolved
  • Resolution: Won't Fix
  • Submitted: 2021-03-25
  • Updated: 2021-05-07
  • Resolved: 2021-05-07
Related Reports
Duplicate :  
JDK-8264218 - Public method javax.swing.JMenu.setComponentOrientation() has no spec
Relates :  
JDK-8264218 - Public method javax.swing.JMenu.setComponentOrientation() has no spec
Relates :  
JDK-8157000 - Do not generate javadoc for overridden method with no spec change
Description
the following method
https://github.com/openjdk/jdk/blob/master/src/java.desktop/share/classes/javax/swing/JMenu.java#L1258 (Also please see the screenshot)

is not mentioned as overriding in the generated javadoc specification:
https://docs.oracle.com/en/java/javase/15/docs/api/java.desktop/javax/swing/JMenu.html

in fact JMenu overrides this method declared in java.awt.Component
Comments
Closing as "won't fix" as it is the intended behaviour of the javadoc standard doclet when running with `--override-methods summary` option to just summarize methods overridden without spec change. This can be changed by using `--override-methods detail`, which is also the default behaviour when the option is not specified. If this is a bug it should be reopened as an infrastructure/build issue.
07-05-2021
[~jjg] The spec above does not mention anything related to this behavior ->> "javadoc has determined there is no user-visible change, and so there is nothing to be gained by explicitly documenting the method as member of the class." But that spec mentioned when the comments should be inherited, and the current case is covered there, isn't it?
01-04-2021
Strictly speaking, docs.oracle.com is an Oracle site that provides information about the Oracle JDK. For example, visit https://docs.oracle.com/en/java/javase/16/ and observe that "Download the JDK" takes you to the download page for the OTN-licensed Oracle JDK. Some of the information on docs.oracle.com is a javadoc presentation of the Java SE API spec. (It so happens that Oracle's OpenJDK builds point to that information too.) I don't think the JCK team should assume that javadoc presented on docs.oracle.com is suitable "out of the box" for any and all JCK purposes. The Spec Lead of JSR 390 (Java SE 15) chooses to host the Reference Implementation at http://jdk.java.net/java-se-ri/15 -- that is the site I would expect to present the Java SE API spec in a manner agreeable to the JCK, e.g., by showing all overriding methods for alignment with SigTest.
30-03-2021
It is admirable that the JCK team chooses to create and provide information to licensees. It is admirable that you treat all methods equally. This implies you should not need to know which methods have been overridden for implementation reasons. It is disappointing that you appear to have missed the significance of my comment here: https://bugs.openjdk.java.net/browse/JDK-8264217?focusedCommentId=14410371&page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel#comment-14410371
30-03-2021
[~vrudomet] Having a public method that does not override anything and does not have a spec is clearly not good. Having a public method that overrides a method with a spec, and which has nothing more to add to the spec, is a reasonable construct, and may be done for implementation reasons that should not be documented. It would also be silly to explicitly document that it does exactly as specified in the overridden method ... that would be pointless noise, and potentially an imposition on other implementations who might feel obligated to override the method unnecessarily as well. Are we OK to close this bug out, for real, as Not An Issue?
30-03-2021
This is caused by the --override-methods feature introduced in 10 with JDK-8157000. JDK platform docs are built with --override-methods=summary option which causes method details for overridden methods to be generated only if there is a spec change. The simplest way to change the spec on the overriding methods is to add a doc comment. You can use the {@inheritDoc} tag to copy the description of the overridden method and add to it in the overriding method.
29-03-2021
In jdk7 the spec was there: https://docs.oracle.com/javase/7/docs/api/javax/swing/JMenu.html#setComponentOrientation(java.awt.ComponentOrientation)
27-03-2021