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.