JDK-8223607 : --override-methods=summary ignores some signature changes
  • Type: Bug
  • Component: tools
  • Sub-Component: javadoc(tool)
  • Affected Version: 11,12,13
  • Priority: P3
  • Status: Resolved
  • Resolution: Fixed
  • OS: generic
  • CPU: generic
  • Submitted: 2019-05-01
  • Updated: 2021-01-20
  • Resolved: 2020-12-18
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.
JDK 16 JDK 17
16 b30Fixed 17Fixed
Related Reports
Duplicate :  
Relates :  
Relates :  
Description
A DESCRIPTION OF THE PROBLEM :
When using javadoc with `--override-methods=summary`, then some changes to the signature of the overriding method are ignored and the method is listed under "Methods declared in".

Affected changes:
- Covariant return type: JDK-8219147
- @Documented annotation on method or its parameters
- Changed `throws` clause:
  - Added unchecked exception
  - Removed exceptions
- Changed parameter name (could be intended)

STEPS TO FOLLOW TO REPRODUCE THE PROBLEM :
1. Create the javadoc for the classes below using `--override-methods=summary`.
2. Look at the doc for `Sub`

EXPECTED VERSUS ACTUAL BEHAVIOR :
EXPECTED -
The method `doSomething` is listed under "Method Detail" and the user sees the changes to its signature.
ACTUAL -
The method `doSomething` is listed under "Methods declared in"; the user does not see any of the changes to its signature.

---------- BEGIN SOURCE ----------
import java.lang.annotation.Documented;

@Documented
public @interface MyAnnotation { }

-----

public interface Parent {
    /**
     * Method
     * 
     * @param a arg
     * @return value
     * @throws Exception never
     */
    Parent doSomething(int a) throws Exception;
}

-----

public interface Sub extends Parent {
    /*
     * Changes:
     *  - Return type
     *  - Used @Documented annotation:
     *    - Method
     *    - Parameter
     *  - `throws` clause:
     *    - Not throwing `Exception`
     *    - Throwing `IllegalArgumentException`
     *  - Parameter name (could be intended that change is ignored)
     */
    @Override
    @MyAnnotation 
    Sub doSomething(@MyAnnotation int aNewName) throws IllegalArgumentException;
}
---------- END SOURCE ----------


It appears this also affects changes to the visibility: 
public class A { 
    /** 
     * Does something 
     */ 
    protected void doSomething() { } 
} 

public class B { 
    @Override 
    public void doSomething() { } 
} 

----- 

The documentation for B does not show "doSomething" under "Method Detail" so the user does not know it is public. 
Comments
Changeset: 45bd3b9e Author: Hannes Walln��fer <hannesw@openjdk.org> Date: 2020-12-18 15:46:25 +0000 URL: https://git.openjdk.java.net/jdk16/commit/45bd3b9e
18-12-2020

Also consider changes in access modifiers, e.g., from `protected` to `public`.
16-12-2020

JDK-8258429 also lists the following notable changes: change in abstractness change in finality
16-12-2020

It's probably reasonable to set the bar fairly low to promote a method from the inherited section to the main summary section.
29-04-2020

The differences are of varying importance. Changing the access modifier is notable. Reducing the set of thrown exceptions is notable. Increasing the set of unchecked thrown exceptions and changing parameter names are significantly less notable -- unless also accompanied by corresponding changes in the documentation comment in which case the method would be explicitly listed in the summary.
09-05-2019

Verified the issue it is reproducible in 13 ea b08 also.
09-05-2019