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
