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)
======================================================================