United StatesChange Country, Oracle Worldwide Web Sites Communities I am a... I want to...
Bug ID: JDK-4915434 @param, @return and some @throws don't inherit comments properly
JDK-4915434 : @param, @return and some @throws don't inherit comments properly

Details
Type:
Bug
Submit Date:
2003-09-01
Status:
Resolved
Updated Date:
2003-11-23
Project Name:
JDK
Resolved Date:
2003-11-23
Component:
docs
OS:
other
Sub-Component:
doclet
CPU:
generic
Priority:
P3
Resolution:
Fixed
Affected Versions:
1.4.2
Fixed Versions:
5.0 (b30)

Related Reports

Sub Tasks

Description
We have a hierarchy similar to the following (should be familiar to
you ):

public interface Collection {
	/**
	* Add a new element to the collection.
	* @param x the new element
	* @return true if the element was added, false otherwise
	* @throws NullPointerException if x is null and nulls are not allowed
	*/
	boolean add(Object x);
}

public interface BoundedQueue extends Collection {

  /**
   * @throws IllegalStateException if the queue is full
   * @throws NullPointerException {@inheritDoc}
   */
  boolean add(Object x);
}

public abstract class AbstractCollection implements Collection {

   /** @throws NullPointerException {@inheritDoc} */
   public boolean add(Object x) {
	return true;
  }
}

public class ArrayBoundedQueue extends AbstractCollection implements
BoundedQueue {

   /**
    * @throws IllegalStateException {@inheritDoc}
    * @throws NullPointerException {@inheritDoc}
    */
    public boolean add(Object x) {
       return super.add(x);
    }
}

At each step we explicitly list the runtime exceptions, using
{@inheritDoc} where applicable (though for this problem it doesn't
matter if we use {@inheritDoc} or just write the text directly).

Based on the above I expect the following for ArrayBoundedQueue.add:
- it will inherit everything from Collection.add
- it will also inherit the IllegalStateException comment from
BoundedQueue.add

What actually happens is this:

<<<<<
Description copied from interface: Collection
   Add a new element to the collection.

Specified by:
   add in interface BoundedQueue
Overrides:
   add in class AbstractCollection
Throws:
   java.lang.IllegalStateException
   java.lang.NullPointerException - if x is null and nulls are not
allowed

>>>>>>>>


We have failed to inherit comments for the @param and @return from
Collection.add.
We have also failed to inherit the comment for @throws
IllegalStateException from BoundedQueue.add.

For the record, Collection.add, AbstractCollection.add and
BoundedQueue.add all have the correct doc comments.

My understanding on the way inherited comments are found leads me to
believe this is a bug in the recursive lookup process. But I may be
misunderstanding how/if the recursive lookup is applied on a tag by
tag basis.

                                    

Comments
EVALUATION

The comments should be copied to ArrayBoundedQueue.add.
The Javadoc documentation says:
   When a main description, or @return, @param or @throws tag is missing from a method comment, the Javadoc tool copies the corresponding main description or tag comment from the method it overrides or implements (if any), according to the algorithm below.

###@###.### 2003-08-31

Fixed.
###@###.### 2003-11-15
                                     
2003-08-31
PUBLIC COMMENTS

Fixed.  The inheritence code is can now handle this rare case where you must inherit tags from multiple parents.
###@###.### 2003-11-15
                                     
2003-11-15
CONVERTED DATA

BugTraq+ Release Management Values

COMMIT TO FIX:
tiger
tiger-beta

FIXED IN:
tiger-beta

INTEGRATED IN:
tiger-b30
tiger-beta


                                     
2004-06-14



Hardware and Software, Engineered to Work Together