On Tue, 27 Sep 2022 11:43:08 GMT, Pavel Rappo <pra...@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 <pra...@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