United StatesChange Country, Oracle Worldwide Web Sites Communities I am a... I want to...
Bug ID: JDK-4679573 @throws comments for runtime exceptions are not being inherited
JDK-4679573 : @throws comments for runtime exceptions are not being inherited

Details
Type:
Bug
Submit Date:
2002-05-03
Status:
Resolved
Updated Date:
2002-12-05
Project Name:
JDK
Resolved Date:
2002-08-26
Component:
docs
OS:
windows_2000
Sub-Component:
doclet
CPU:
x86
Priority:
P3
Resolution:
Fixed
Affected Versions:
1.4.0
Fixed Versions:
1.4.2 (mantis)

Related Reports
Relates:
Relates:

Sub Tasks

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
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
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
CONVERTED DATA

BugTraq+ Release Management Values

COMMIT TO FIX:
mantis

FIXED IN:
mantis

INTEGRATED IN:
mantis


                                     
2004-06-14



Hardware and Software, Engineered to Work Together