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

Daniel Fuchs dfuchs at openjdk.org
Wed Sep 28 13:38:37 UTC 2022


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

The changes to JNDI and NIO look reasonable to me - though I haven't verified whether anything was missing (or no longer needed). If you can assert that the generated docs are the same before and after the proposed change then that's enough for me.

src/java.naming/share/classes/javax/naming/directory/InitialDirContext.java line 186:

> 184:     /**
> 185:      * @throws  AttributeModificationException {@inheritDoc}
> 186:      */

Isn't `{@inheritDoc}` needed in this case to preserve the method & params  description?

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

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



More information about the client-libs-dev mailing list