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

N/A

Appears like a valid bug.
  xxxxx@xxxxx   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.
  xxxxx@xxxxx   2002-07-08

After further thought on this I'm not sure that 
automatically inheriting runtime exceptions is the right 
thing to do. The problem is with 'optional' methods, such 
as those used in the Collections API. The generic method is 
described as optional and that it may throw 
UnsupportedOperationException - which is a runtime 
exception. The actual derived implementation supports the 
method and so never throws that exception, but according to 
the rules the javadoc for the @throws would be inherited. 
That would be wrong.

If runtime exception javadoc comments are automatically 
inherited then you also need a means to "un-inherit" them 
to solve the problem just mentioned.

Hey Guys! *READ* the bug report. This is NOT a duplicate of  
4317583. This is a bug in the current 1.4.0 release version of 
the javadoc tool, when compared with the documentation for 
that tool. The tool does not do what the docs says it should.

Just to clarify my comments above. The bug report has been 
edited since my complaint and is no longer closed as a 
duplicate bug.