Integrated: 8294377: Prepare to stop auto-inheriting documentation for subclasses of exceptions whose documentation is inherited

[Pavel Rappo]

On Tue, 27 Sep 2022 11:43:08 GMT, Pavel Rappo <prappo at openjdk.org> wrote:

> This adds exception documentation to JDK methods that would otherwise lose that documentation once JDK-8287796 is integrated. While adding this exception documentation now does not change [^1] the JDK API Documentation, it will automatically counterbalance the effect that JDK-8287796 will have.
> 
> JDK-8287796 seeks to remove an old, undocumented, and esoteric javadoc feature that cannot be suppressed [^2]. The feature is so little known about that IDEs either do not implement it correctly or do not implement it at all, thus rendering documentation differently from how the javadoc tool renders it.
> 
> That feature was introduced in JDK-4947455 and manifests as follows. If a method inherits documentation for an exception, along with that documentation the method automatically inherits documentation for all exceptions that are subclasses of that former exception and are documented in an overridden method.
> 
> To illustrate that behavior, consider the following example. A method `Subtype.m` inherits documentation for `SuperException`, while the overridden method `Supertype.m` documents `SuperException`, `SubExceptionA` and `SubExceptionB`, where the latter two exceptions are subclasses of the former exception:
> 
>     public class Subtype extends Supertype {
> 
>         @Override
>         public void m() throws SuperException {
>     ...
> 
>     public class Supertype {
> 
>         /**
>          * @throws SuperException general problem
>          * @throws SubExceptionA  specific problem A
>          * @throws SubExceptionB  specific problem B
>          */
>         public void m() throws SuperException {
>     ...
> 
>     public class SuperException extends Exception {
>     ...
> 
>     public class SubExceptionA extends SuperException {
>     ...
> 
>     public class SubExceptionB extends SuperException {
>     ...
> 
> For the above example, the API Documentation for `Subtype.m` will contain documentation for all three exceptions; the page fragment for `Subtype.m` in "Method Details" will look like this:
> 
>     public void m()
>            throws SuperException
> 
>     Overrides:
>         m in class Supertype
>     Throws:
>         SuperException - general problem
>         SubExceptionA - specific problem A
>         SubExceptionB - specific problem B 
> 
> It works for checked and unchecked exceptions, for methods in classes and interfaces.
> 
> 
> If it's the first time you hear about that behavior and this change affects your area, it's a good opportunity to reflect on whether the exception documentation this change adds is really needed or you were simply unaware of the fact that it was automatically added before. If exception documentation is not needed, please comment on this PR. Otherwise, consider approving it.
> 
> Keep in mind that if some exception documentation is not needed, **leaving it out** from this PR might require a CSR.
> 
> 
> [^1]: Aside from insignificant changes on class-use and index pages. There's one relatively significant change. This change is in jdk.jshell, where some methods disappeared from "Methods declared in ..." section and other irregularities. We are aware of this and have filed JDK-8291803 to fix the root cause.
> [^2]: In reality, the feature can be suppressed, but it looks like a bug rather than intentional design. If we legitimize the feature and its suppression behavior, the model for exception documentation inheritance might become much more complicated.

This pull request has now been integrated.

Changeset: eb90c4fc
Author:    Pavel Rappo <prappo at openjdk.org>
URL:       https://git.openjdk.org/jdk/commit/eb90c4fc0479379c8c1452afca8f37746c762e18
Stats:     320 lines in 14 files changed: 310 ins; 0 del; 10 mod

8294377: Prepare to stop auto-inheriting documentation for subclasses of exceptions whose documentation is inherited

Reviewed-by: jjg

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

PR: https://git.openjdk.org/jdk/pull/10449