It would be helpful if javadoc emitted a conditional warning for an ambiguous {@inheritDoc ...} (directed or otherwise).

Such a warning could provide (i) the location of the ambiguous tag (ii) the automatic resolution that javadoc made: that is, the method where documentation was copied from, and (iii) the suggestion on how to eliminate ambiguity.

{@inheritDoc ...} is ambiguous if any of these are true:
 * there are more than one resolution to it (i.e. more than one method to copy documentation from)
 * it resolves to another ambiguous {@inheritDoc ...}

Ambiguity is resolved by automatic documentation algorithm.

The purpose of this RFE is to provide a tool to wean authors off the magic of documentation inheritance, which is not always correct.