Difficulty with javadoc {@inheritdoc} tag

[Jonathan Sachs]

I'm using the {@inheritdoc} tag to help document a group of parent
classes and subclasses, and it's not working out very well. The
problem is that {@inheritdoc} assumes that one of three cases must
apply when writing a part of the Javadoc for a method in a subclass:

1. The parent class's Javadoc fully describes the subclass. (Use
{@inheritdoc} alone.)

2. The parent class's Javadoc partially describes the subclass. (Use
{@inheritdoc} and write additional text for the subclass.)

3. The parent class's Javadoc does not apply to the subclass. (Omit
{@inheritdoc} and write a full description for the subclass.)

There are, of course, two other cases: part of the parent class's
Javadoc (4) fully or (5) partially describes the subclass, the rest
being inapplicable and possibly misleading.

In practice I have found that case 5 is at least as common as case 1
or 2, but Javadoc seems to afford no way to say, "This part of the
parent class's Javadoc is inheritable; this part is not."

The only way I know to work around this limitation is to forget about
using {@inheritdoc} at all. Is there a better way?