JDK-4915434 : @param, @return and some @throws don't inherit comments properly
  • Type: Bug
  • Component: tools
  • Sub-Component: javadoc(tool)
  • Affected Version: 1.4.2
  • Priority: P3
  • Status: Resolved
  • Resolution: Fixed
  • OS: other
  • CPU: generic
  • Submitted: 2003-09-01
  • Updated: 2014-05-05
  • Resolved: 2003-11-23
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
5.0 b30Fixed
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
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

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

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