United StatesChange Country, Oracle Worldwide Web Sites Communities I am a... I want to...
Bug ID: JDK-4767038 first sentence not determined correctly with use of {@inheritDoc}
JDK-4767038 : first sentence not determined correctly with use of {@inheritDoc}

Details
Type:
Bug
Submit Date:
2002-10-23
Status:
Resolved
Updated Date:
2005-04-11
Project Name:
JDK
Resolved Date:
2005-04-11
Component:
docs
OS:
solaris_8,linux
Sub-Component:
doclet
CPU:
x86,sparc
Priority:
P3
Resolution:
Fixed
Affected Versions:
1.4.1,1.4.2
Fixed Versions:
5.0 (tiger)

Related Reports
Duplicate:

Sub Tasks

Description
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.


Name: rmT116609			Date: 02/27/2003


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)
======================================================================

                                    

Comments
WORK AROUND

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

###@###.### 2002-12-11
                                     
2002-12-11
PUBLIC COMMENTS

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.
                                     
2004-06-10
CONVERTED DATA

BugTraq+ Release Management Values

COMMIT TO FIX:
tiger

FIXED IN:
tiger

INTEGRATED IN:
tiger
tiger-b22


                                     
2004-06-14
EVALUATION

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.

###@###.### 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.

###@###.### 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}.  

###@###.### 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.
###@###.### 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).
###@###.### 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.
###@###.### 2005-04-11 21:38:58 GMT
                                     
2005-04-11



Hardware and Software, Engineered to Work Together