The new @inheritDoc javadoc tag is very useful, but a slightly more
general facility would greatly enhance its usefulness.

The main issue with the tag is that it inherits the entire comment
from the class or interface which is being overridden or implemented.
Sometimes the origin of the doc comment needs to include a sentence
or two describing the role of the method in the overall design in
general terms. Such a comment may be out of place or redundant in
the documentation of the importing class as a more specific role or
behavior may be documented more specifically there. An example
could be:

public interface Displayable {
    /**
     * Display the contents on the output by either
     * rendering it directly or by providing a path
     * to an image containing the contents to be
     * rendered.
     * <p>
     * All state must be made consistent with the
     * current display parameters using the validate()
     * method before the current state is displayed.
     * <p>
     * This method must not invoke any of the
     * asynchronous display methods which may generate
     * an exception.
     * <p>
     * This method may only be called while the
     * target is visible on the screen.
     * Behavior when it is called under other
     * circumstances is undefined.
     */
    public void display();
}

Now imagine a class implementing this method. It might start out
by saying "Display the contents by rendering it directly" since
this particular implementor knows that it will always choose that
option. If it then uses @inheritDoc to include all of the details
from the interface it will end up importing some text which mentions
the potential choice of how the contents should be displayed, which
will confuse developers since the doc comments now contain contradictory
text - will it use direct rendering as it first said, or will it use
either as it said later?

It would be much nicer if doc comments could define an "inheritable
section" which was written so as to be neutral with respect to choices
made by subclasses. For example, {@beginInherit} and {@endInherit}
could bracket the section that should be copied when an implementor
uses {@inheritDoc}.

An even more flexible utility would allow arbitrary blocking of
doc sections which could be flexibly included cafeteria-style.
Tags such as {@beginSection <name>}, {@endSection <name>} could
delineate multiple sections which can be referred to or included in
other doc comments using @see <name>, {@link <name>} or {@includeDoc <name>}
tags. One could envision that each of the paragraphs in the example
could be separately named and the implementing method could choose
to include the sections by name (eg. validConstraint, AsyncConstraint,
VisibilityRequirement} depending on which may apply or which may
represent choices made by this particular implementation.

The linking aspects of the last facility can currently be achieved by
inlining HTML, but that practice is both awkward in the context of
javadoc comments, and is potentially less flexible for providing
better support for these referent sections in the javadoc output.
One could imagine including them in an "index" (optionally if the
tag asks for it, or doesn't request exclusion), double checking to
make sure that the links and references both exist, etc.