JDK-8005622 : Inherited Javadoc missing @throws
  • Type: Bug
  • Component: tools
  • Sub-Component: javadoc(tool)
  • Affected Version: 8
  • Priority: P4
  • Status: Resolved
  • Resolution: Fixed
  • OS: generic
  • CPU: generic
  • Submitted: 2012-12-31
  • Updated: 2024-01-25
  • Resolved: 2024-01-18
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.
JDK 22 JDK 23
22Fixed 23 b07Fixed
Related Reports
Relates :  
JDK-4947455 - @throws documentation should be auto inherited if exception is checked
Relates :  
JDK-8048264 - StringBuffer's codePoint methods throw unspecified IndexOutOfBoundsException
Relates :  
JDK-8285368 - Overhaul doc-comment inheritance
Description
A concrete method implementation that inherits javadoc from an interface gets all of the javadoc from the interface defining the method but not the throws clauses. Is this a bug or can the intended behavior be defined.
Comments
There's even an in-code description added to DocFinder in JDK-4947455: /** * When automatically inheriting throws tags, you sometimes must inherit * more than one tag. For example, if a method declares that it throws * IOException and the overridden method has {@code @throws} tags for IOException and * ZipException, both tags would be inherited because ZipException is a * subclass of IOException. This allows multiple tag inheritance. */ public final List<DocTree> tagList = new ArrayList<>();
29-04-2022
Linked JDK-4947455.
29-04-2022
I've traced peculiar behavior that I found in code to JDK-4947455. I cannot find that behavior described in that technetwork document, "Documentation Comment Specification for the Standard Doclet", or "The Java Programming Language". Ouch! [~jjg], I think we should explore and figure out what to do with it as far as the "Documentation Comment Specification for the Standard Doclet" is concerned.
29-04-2022
This is not a bug. That behavior and the rationale for it are described in "The Java Programming Language, Fourth Edition"; see the attached photo of my paper copy. If I read it correctly, that behavior is also described in the "Documentation Comment Specification for the Standard Doclet": https://docs.oracle.com/en/java/javase/18/docs/specs/javadoc/doc-comment-spec.html#throws I think we could address this issue by restructuring the spec description and making that description more prominent. P.S. Thanks for providing a link to that technetwork document, Roger. It's quite old and has a few historical bits, which I've never seen before, such as: - Multiple @throws tags (also known as @exception) should be listed alphabetically by the exception names.
29-04-2022
Sample interface, implementation in Netbeans project.
31-12-2012
Note that the javadoc comment is included if the throws clause in concrete method mentions the exception. Including an @throws tag for the exception and using {@inheritDoc} works also. Also, since unchecked exceptions are not typically included in the throws clause it is not clear which guidance to follow so that the exception is documented as part of the method specification. This javadoc describes conventions for documenting exceptions: http://www.oracle.com/technetwork/java/javase/documentation/index-137868.html#throwstag Probably not a bug but not easy to figure out the best practice.
31-12-2012