This bug has been fixed.  The method to compute which documentation should be inherited now accepts a flag to indicate whether or not the method should only return the first sentence.When {@inheritDoc} is used to inherit the beginning of the description of a method comment, the determination of the "first sentence" of the [overriding] method's comment doesn't seem to properly consider the content of the text that will be inherited; instead, the determination of the end of the first sentence seems to consider the description text before expanding the {@inheritDoc}.

Here is an example:

public class Super {
    /**
     * This is the first sentence of Super's method doc comment.
     * This is the rest of Super's method doc comment.
     */
    public void method() { }
}

public class Sub extends Super {
    /**
     * {@inheritDoc}
     * This is the first sentence of Sub's method doc comment.
     * This is the rest of Sub's method doc comment.
     */
    public void method() { }
}

I would like and desired the first sentence of Sub.method's doc comment to be considered to be

	This is the first sentence of Super's method doc comment.

but instead, the description of Sub.method in Sub's "Method Summary" is generated to be

	This is the first sentence of Super's method doc comment. This is
	the rest of Super's method doc comment. This is the first sentence of
	Sub's method doc comment.

It seems that the end of the Sub.method's first sentence is being chosen where it is because that's where the first period followed by a space (and a capital letter) is found *without* expanding the {@inheritDoc} for that consideration.





DESCRIPTION OF THE PROBLEM :
Javadoc includes the whole inherited method comment in the
first sentence summary, even when it contains many sentences.

I haven't looked at the source, but javadoc seems to be
parsing for the breakiterator before evaluating the inline
taglets.  Thus the first-sentence-summary contains all the
sentences of the superclass plus the first sentence of the
subclass, if the {@inheritDoc} appears before the end of the
first sentence.

STEPS TO FOLLOW TO REPRODUCE THE PROBLEM :
1. javadoc SuperClass.java SubClass.java
(same results, regardless of -breakiterator)

EXPECTED VERSUS ACTUAL BEHAVIOR :
SubClass's METHOD SUMMARY contents:

expected:
foo()
          First sentence from superclass.

actual:
foo()
          First sentence from superclass. Second sentence
from superclass. First sentence from subclass.

REPRODUCIBILITY :
This bug can be reproduced always.

---------- BEGIN SOURCE ----------
public class SuperClass {
        /**
         * First sentence from superclass.  Second sentence from superclass.
         */
        public void foo() {}
}

public class SubClass extends SuperClass {
        /**
         * {@inheritDoc} First sentence from subclass.  Second sentence from
subclass.
         */
        public void foo() {}
}

---------- END SOURCE ----------

(Review ID: 181837)
======================================================================

A workaround is to insert another sentence as the first sentence,
and use {@inheritDoc} after the first sentence.

 xxxxx@xxxxx  2002-12-11

Perhaps whenever the standard doclet finds {@inheritDoc} 
in the first sentence, it should expand it, parse the first 
sentence (using a copy of the algorithm that the Doclet API uses) 
and then use that instead of the first sentence handed to 
it by the Doclet API.

neal.gafter replied:
Reasonable, except it must be done without copying any code at
all or we risk getting them out of sync.

 xxxxx@xxxxx  2002-10-27

I fixed this bug by following Neals advice.  When the first sentence starts with {@inheritDoc}, inherit the first sentence and ignore the text that follows {@inheritDoc}.  There is no need to insert a period after {@inheritDoc} to make it work.

Using {@inheritDoc} without a period probably causes a "first sentence break iterator" warning though.  We will have to do something about this in the next release.

 xxxxx@xxxxx  2002-12-09

FYI, this bug was introduced in 1.4.1.  This bug does not show up at 
all in the J2SE API docs, because {@inheritDoc} is not used in the docs 
(I did a grep).  It only appears in documentation that uses {@inheritDoc}.  

 xxxxx@xxxxx  2002-12-11

FYI, this bug is still in the FIP state because it was fixed during our tiger refactoring.  After the doclet toolkit is reviewed, this bug fix will be putback.
 xxxxx@xxxxx  2003-07-01

I don't think this bug has been fixed, or there is a deep
misunderstanding.

The two following javadoc comments:

/**
 *
 */

and

/**
 * {@inheritDoc}
 */

when applied to an overriding method definition should have
identical effects.  However, if the overridden method 
"description" consists of more than one sentence, then the
"first sentence" of the first doc comment above is the
same as the "first sentence" of the overriden method (correct),
while the "first sentence" of the second doc comment is the
entire "description" of the overridden method (incorrect).
 xxxxx@xxxxx  2005-04-08 23:26:02 GMT

I've understood the nature of the failure I was seeing;
I think this is a slightly different bug; so I'll reset this to
Fix Delivered and will file a new bug.
 xxxxx@xxxxx  2005-04-11 21:38:58 GMT

This is a problem whether -breakiterator is used or not, I
have not been able to find a workaround, and unfortunately
it seems to render the {@inheritDoc} tag pretty much
useless. Clearly the substitution should occur before the
first sentence calculation.

I have just thought of another enhancement thats needed for
the inheritDoc tag.  Take the following situation:

public interface Something
{
        /**
         * Does soomething.
         */
        public void  doSomething();

        /**
         * Does something important.
         */
        public void  doSomethingImportant();
}

public abstract class AbstractSomething implements Something
{
        /**
         * {@inheritDoc}
         * <p>
         * This uses iteration to do something interesting.
         * </p>
         */
        public void  doSomething()
        {
                for (int i=0; i<10; i++)
                {
                }
        }

        /**
         * {@inheritDoc}
         */
        public void  doSomethingImportant()
        {
                // Actually do something
        }
}

public class ConcreteSomething extends Something
{
        /**
         * {@inheritDoc}
         * <p>
         * This decides to not do anything interesting.
         * </p>
         */
        public void  doSomething()
        {
        }
}

Whilst a little contrived, the example is valid in that
often classes extend abstract classes to provide more
efficient implementations of methods, just check out the
collections API.  Here we have ConcreteSomething deciding to
override just 1 of the methods that AbstractSomething
provides, but by using the inheritDoc tag, what happens is
that the implementation comment from AbstractSomething gets
copied with the final comment being :

        Does soomething.
        This uses iteration to do something interesting.
        This decides to not do anything interesting.

when what was wanted was

        Does soomething.
        This decides to not do anything interesting.

i.e. skipping out the implementation details added by the
abstract class.  It should be possible to specify
{@inheritDoc:className} as long as className is a superclass
or superinterface of the current class.  This would solve
the problem where a class implements two interfaces with a
method of the same signature - it would actually be possible
to specify which one you are really implementing.

The only way to achieve the desired output currently is to
copy and paste the comment from interface Something to class
ConcreteSomething.  And if this happened you can immediately
see that the spelling mistake is now in two places.

Is there any news about the suggested enhancement
{@inheritDoc:className} to avoid copying intermediate
comments?  I am not aware of any issues with this, are there
potential problems?

Can we re-open this as an RFE please?

> Is there any news about the suggested enhancement
> {@inheritDoc:className} to avoid copying intermediate
> comments?  Can we re-open this as an RFE please?

There's been no work on this.  Please submit this as
an RFE using the procedure described at:

http://java.sun.com/j2se/javadoc/faq/index.html#submitbugs

-Doug Kramer
Javadoc team