FULL PRODUCT VERSION :
java version "1.5.0_04"
Java(TM) 2 Runtime Environment, Standard Edition (build 1.5.0_04-b05)
Java HotSpot(TM) Client VM (build 1.5.0_04-b05, mixed mode)

ADDITIONAL OS VERSION INFORMATION :
Microsoft Windows XP [Version 5.1.2600]

A DESCRIPTION OF THE PROBLEM :
The getDocComments method on the implementation for the com.sun.mirror.declaration.Declaration interface on the APT mirror API does not consider the javadoc tags that refer to the appropriate declaration.

STEPS TO FOLLOW TO REPRODUCE THE PROBLEM :
Write a class with the following method, run APT against it and output the docComments for each declaration:

  /**
   * Removes an item from a collection.
   *
   * @param collection The collection from which to remove the item.
   * @param item the item to remove from the collection.
   * @return Whether the item was successfully removed.
   * @throws Exception If an error occurs.
   */
  public boolean removeChild(Collection collection, Object item) throws Exception {
    return false;
  }


EXPECTED VERSUS ACTUAL BEHAVIOR :
EXPECTED -
APT should consider the standard javadoc tags to assign the doc comments like so:

For the method declaration: "Removes an item from a collection."
For the parameter declaration for 'collection': "The collection from which to remove the item."
For the parameter declaration for 'item': "the item to remove from the collection."

And the comments: "Whether the item was successfully removed." and "If an error occurs." should probably be dropped since there is no associated declaration with either the return type or the thrown types.
ACTUAL -
getDocComments for the method declaration returns everything between the /* and the */.

REPRODUCIBILITY :
This bug can be reproduced always.