JDK-4679573 : @throws comments for runtime exceptions are not being inherited
  • Type: Bug
  • Status: Resolved
  • Resolution: Fixed
  • Component: tools
  • Sub-Component: javadoc(tool)
  • Priority: P3
  • Affected Version: 1.4.0
  • OS: windows_2000
  • CPU: x86
  • Submit Date: 2002-05-03
  • Updated Date: 2014-05-05
  • Resolved Date: 2002-08-26
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 Availabitlity Release.

To download the current JDK release, click here.
Other
1.4.2 mantisResolved
Related Reports
Relates :  
Relates :  
Description

Name: nt126004			Date: 05/03/2002


FULL PRODUCT VERSION :
java version "1.4.0"
Java(TM) 2 Runtime Environment, Standard Edition (build 1.4.0-b92)
Java HotSpot(TM) Client VM (build 1.4.0-b92, mixed mode)

FULL OPERATING SYSTEM VERSION : Microsoft Windows 2000
[Version 5.00.2195]


ADDITIONAL OPERATING SYSTEMS : ALL



A DESCRIPTION OF THE PROBLEM :
In 1.4 changes have been made to the way that @throws
comments are inherited. The javadoc manual
http://java.sun.com/j2se/1.4/docs/tooldocs/solaris/javadoc.html

  states:

"A @throws tag's comment documented in a superclass or
interface is inherited in two cases: (1) for a
corresponding exception declared in a throws clause of the
subclass and (2) for all runtime exceptions. If neither is
the case and you want to force the documentation to be
inherited, then use {@inheritDoc}. "

Case 2 does not seem to be being implemented in the current
javadoc tool. Yet it is very important that runtime
exception comments are inherited automatically.


Note that there are already known bugs with the new javadoc
behaviour for inheriting @throws and use of {@inheritDoc}

STEPS TO FOLLOW TO REPRODUCE THE PROBLEM :
1. Create the two sample files shown below
2. Run the javadoc tool on these two files.
3. Look at the generated HTML



EXPECTED VERSUS ACTUAL BEHAVIOR :
Derived.setX should inherit all doc comments from
Base.setX, including the @throws comment for the runtime
exception IllegalArgumentException.

Here is the html for Derived.setX and as you can see there
is no Throws section.

<!-- ============ METHOD DETAIL ========== -->

<A NAME="method_detail"><!-- --></A>
<TABLE BORDER="1" CELLPADDING="3" CELLSPACING="0"
WIDTH="100%">
<TR BGCOLOR="#CCCCFF" CLASS="TableHeadingColor">
<TD COLSPAN=1><FONT SIZE="+2">
<B>Method Detail</B></FONT></TD>
</TR>
</TABLE>

<A NAME="setX(int)"><!-- --></A><H3>
setX</H3>
<PRE>
public void <B>setX</B>(int&nbsp;newVal)</PRE>
<DL>
<DD><B>Description copied from class: <CODE><A
HREF="Base.html">Base</A></CODE></B></DD>
<DD>Set the value of x
<P>
<DD><DL>
<DT><B>Specified by:</B><DD><CODE><A HREF="Base.html#setX
(int)">setX</A></CODE> in class <CODE><A
HREF="Base.html">Base</A></CODE></DL>
</DD>
<DD><DL>
<DT><B>Parameters:</B><DD><CODE>newVal</CODE> - the new
value</DL>
</DD>
</DL>
<!-- ========= END OF CLASS DATA ========= -->

This bug can be reproduced always.

---------- BEGIN SOURCE ----------
Base.java:

  /**
   * A simple base class
   *
   */
   public abstract class Base {

     /**
       * Set the value of x
       * @param newVal the new value
       * @throws IllegalArgumentException if <code>newVal</code> is negative
       *
       */
       public abstract void setX(int newVal);
    }

Derived.java:

    /**
     * Derived class
     */
     public class Derived extends Base {
         int x;

         // inherit doc comments
         public void setX(int newVal){
             if (x < 0) {
                 throw new IllegalArgumentException();
             }
             x = newVal;
         }
    }


---------- END SOURCE ----------

CUSTOMER WORKAROUND :
Force case 1) to apply by declaring the runtime exception
in the throws clause of the derived method.
(Review ID: 146055) 
======================================================================

Comments
CONVERTED DATA BugTraq+ Release Management Values COMMIT TO FIX: mantis FIXED IN: mantis INTEGRATED IN: mantis
2004-06-14

PUBLIC COMMENTS When we fixed 4317583, we decided that the standard doclet will no longer blindly inherit exception documentation. If you want to inherit documentatinon, you must use the {@inheritDoc} inline tag. Another way to inherit @throws documentation is to declare the exception in the method signature. The doclet will automatically search the overriden method for the appropriate documentation to inherit. ###@###.### 2002-07-08 I think that 4679573 is a documentation bug. The following documentation states that @throws tags for runtime exceptions are automatically inherited: http://java.sun.com/j2se/1.4/docs/tooldocs/windows/javadoc.html#@throws The following documentation states an @throws tag is automatically inherited if and only if the exception is explicitely declared in the throws clause of the derived method: http://java.sun.com/j2se/1.4/docs/tooldocs/javadoc/whatsnew-1.4.html#@throwsnotc opied The first piece of documentation is incorrect. We decided as a team that @throws tags for runtime exceptions would not automatically be inherited unless the exceptions were explicitely declared in the throws clause. We will fix the documentation. ###@###.### 2002-08-22 I've changed it to this: The @throws documentation is copied from an overridden method to a subclass only when the exception is explicitly declared in the overridden method. The same is true for copying from an interface method to an implementing method. You can use {@inheritDoc} to force @throws to inherit documentation. The documentation used to say this: A <code>@throws</code> tag comment in a superclass or interface is inherited in two cases: (1) for a corresponding exception declared in a throws clause of the subclass and (2) for all runtime exceptions. If neither is the case and you want to force the documentation to be inherited, then use {@inheritDoc}. ###@###.### 2002-08-22 This documentation bug has been fixed and integrated.
2002-08-22

EVALUATION Appears like a valid bug. ###@###.### 2002-05-09 When we fixed 4317583, we decided that the standard doclet will no longer blindly inherit exception documentation. If you want to inherit documentatinon, you must use the {@inheritDoc} inline tag. Another way to inherit @throws documentation is to declare the exception in the method signature. The doclet will automatically search the overriden method for the appropriate documentation to inherit. ###@###.### 2002-07-08
2002-07-08