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

[Jonathan Gibbons]

On Tue, 27 Sep 2022 12:14:23 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.
>
> Pavel Rappo has updated the pull request incrementally with one additional commit since the last revision:
> 
>   revert an extraneous change to jdk.javadoc

I'm marking the change as approved, in terms of the cumulative efforts of those who have commented.

I've browsed all the changes and read the jshell files in more detail, since no once else has so far.

I understand the reason for the change, and generally approve of undoing the magic of the old feature in JDK-8287796. That being said, the proposed state is "not great", and feels like the interim stage of "one step back, to take two steps forward", even though I do not have a good sense at this time of what that future direction might be.

So, looks OK for now, but I hope we revisit this issue again sometime.  Thanks, in general, for taking on this topic.

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

Marked as reviewed by jjg (Reviewer).

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