JDK-4947455 : @throws documentation should be auto inherited if exception is checked
  • Type: Bug
  • Component: tools
  • Sub-Component: javadoc(tool)
  • Affected Version: 5.0
  • Priority: P3
  • Status: Resolved
  • Resolution: Fixed
  • OS: generic
  • CPU: generic
  • Submitted: 2003-11-01
  • Updated: 2022-09-28
  • Resolved: 2003-12-19
The Version table provides details related to the release that this issue/RFE will be addressed.

Unresolved : Release in which this issue/RFE will be addressed.
Resolved: Release in which this issue/RFE has been resolved.
Fixed : Release in which this issue/RFE has been fixed. The release containing this fix may be available for download as an Early Access Release or a General Availability Release.

To download the current JDK release, click here.
Other
5.0 b32Fixed
Related Reports
Relates :  
JDK-8005622 - Inherited Javadoc missing @throws
Relates :  
JDK-8287796 - Stop auto-inheriting documentation for subclasses of exceptions whose documentation is inherited
Description
Martin Buchholz brought up a very good point.  Suppose a method documents that
it throws A and B, where B is a subclass of A.  If an overriden method only has 
A in the throws clause, the doclet should inherit @throws documentation for A 
and B.  Although B is not explicitly in the throws clause, it is a subclass of 
A, so it is still checked.
Comments
I've recently discovered that the feature can be opted out of individually, per doc comment. However, it seems that the opt-out capability is a result of a bug, rather than design. Here's how opting out works. If an overriding method aims to inherit just exception documentation for X, rather than for X and all its subclasses documented in the overridden method, then the overriding method simply documents X as follows: @throws X {@inheritDoc} If the method aims to inherit X and *some* of the subclasses of X (Y1, Y2, ... Yn), then the method documents exceptions as follows: @throws X {@inheritDoc} @throws Y1 {@inheritDoc} @throws Y2 {@inheritDoc} ... @throws Yn {@inheritDoc} All other exceptions Z1, Z2, ... Zn, that are subclasses of X and aren't among Y1, Y2, ... Yn, will not be documented in the overriding method.
28-09-2022
I have only the haziest memory of having been involved with this bug. Probably only checked exceptions are being discussed here. Because checked exceptions must be declared in a throws clause, it is possible for an overriding method to "undeclare" that a particular exception is thrown. Except in this special case of two checked exceptions in an inheritance hierarchy. Today my inclination would be that the @throws clause for B **NOT** be javadoc-inherited, contrary to what I might have said 20 years ago. Having different behavior for "throws A, B" versus "throws A" allows the programmer to control the exception spec, and it is unsurprising when the generated javadoc matches the throws clause. OTOH we always need a good reason to change existing behavior.
11-05-2022
While that might come in handy for some APIs, it won't be correct for others; especially taking into account that the overrider cannot opt out of the described behavior.
10-05-2022
CONVERTED DATA BugTraq+ Release Management Values COMMIT TO FIX: tiger-beta FIXED IN: tiger-beta INTEGRATED IN: tiger-b32 tiger-beta
14-06-2004
PUBLIC COMMENTS This bug has been fixed. ###@###.### 2003-12-01
01-12-2003
EVALUATION Accepted. ###@###.### 2003-11-03 Fixed. ###@###.### 2003-12-01
03-11-2003