-
Bug
-
Resolution: Fixed
-
P3
-
11, 12, 13
-
b30
-
generic
-
generic
Issue | Fix Version | Assignee | Priority | Status | Resolution | Resolved In Build |
---|---|---|---|---|---|---|
JDK-8258767 | 17 | Hannes Wallnoefer | P3 | Resolved | Fixed | b03 |
JDK-8260058 | 16.0.1 | Hannes Wallnoefer | P3 | Resolved | Fixed | b03 |
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.
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:
- @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.
- backported by
-
JDK-8258767 --override-methods=summary ignores some signature changes
- Resolved
-
JDK-8260058 --override-methods=summary ignores some signature changes
- Resolved
- duplicates
-
JDK-8258429 Refine inheritDoc tag effect for certain user-visible method signature changes
- Closed
- relates to
-
JDK-8219147 Javadoc should expose covariant return type overrides
- Resolved
-
JDK-8258429 Refine inheritDoc tag effect for certain user-visible method signature changes
- Closed
(3 links to)