Bug ID: JDK-4914500 Spurious breakiterator warning due to not recognizing period in {@inheritDoc}

Type: Bug
Component: tools
Sub-Component: javadoc(tool)
Affected Version: 1.4.2

Priority: P4
Status: Resolved
Resolution: Not an Issue
OS: other
CPU: generic

Submitted: 2003-08-28
Updated: 2024-04-12
Resolved: 2018-03-01

Other
tbdResolved

There's a "spurious" warning from javadoc concerning breakiterator -

it doesn't like a doc comment that starts:

   /**
     * {@inheritDoc}
     *
     * <p>additional text ...
     */

With the -breakiterator option, there is no warning.
Without the -breakiterator option, the warning is:

C.java:8: warning - The first sentence is interpreted to be:
"{@inheritDoc}"
This sentence is different from what will be interpreted as the first sentence 
in the next major release (when that interpretation will be internationalized),
which is:
"{@inheritDoc}

 <p>additional text ..."
To avoid this note, change the doc comment to make this a proper first sentence, 
then use -breakiterator from that point forward, which will output this new
sentence.

This has been resolved with the new doclet implementation, no longer an issue.

01-03-2018

EVALUATION Doug wrote: Note: The warning might go away when -breakiterator is made the default. This problem sounds familiar -- could the warning be the same bug where it picks up the first sentence from the *uninterpreted* comment: 4767038: first sentence not determined correctly with use of {@inheritDoc} ###@###.### replied: No, this is not a dupe. Bug 4767038 is fixed at the top of the tree. The first sentence is now interpreted correctly when using @inheritDoc. The bug mentioned below is that Javadoc gives an erroneous warning. We mentioned this to Neal in the past but I guess it was not fixed. He did give us a workaround though. Just put a period after {@inheritDoc}. That avoids the error. You might want to do a search and then submit a bug if there isn't one already. This is a known problem though. Doug wrote: Putting a period after {@inheritDoc} prevents the warning, but it seems that would simply cause the first sentence to typically end with two periods rather than one (which is worse than the warning). ###@###.### 2003-08-28 ###@###.### wrote: Sorry, I thought the doclet was smart enough to not print the extra period but it does do that in 1.4.2_01. This has been fixed in 1.5 and will be checked in soon. If we are removing the warning, 4914500 should definitely be closed. I was only letting the user put a period there to avoid the warning. If there is no warning, the period should not be used. ###@###.### 11-07-2003 I just ran this with 1.5.0 GA, and it gives these results: SOURCE: public class MySubClassUppercase extends MyClass { /** * {@inheritDoc} * * <p>Initial uppercase text in comment of the subclass. */ public void myMethod() { } } RESULTS FOR TEXT IN METHOD SUMMARY: void myMethod() Comment from MyClass. Initial uppercase text in comment of the subclass. Of course, no warning appears (because it was removed). However, notice that this appears to demonstrate that this bug was not really fixed: 4767038: first sentence not determined correctly with use of {@inheritDoc} I looked at the regression test for this to see why it is not failing, and it appears it is not a proper test. Here is the doc comment: public class Foo extends BaseTaglet { /** * {@inheritDoc} */ public TagletOutput getTagletOutput(Tag tag, TagletWriter writer) { ... } } Notice there is no sentence after {@inheritDoc}, so it is not possible to tell if the summary is picking up that sentence. Apparently the bug that was fixed was to stop after the first sentence in the {@inheritDoc} block, but it didn't consider also stopping after that block was interpreted. Here is the chain from which the paragraph was inherited: public interface Taglet { ... /** * Given the <code>Tag</code> representation of this custom * tag, return its TagletOutput representation, which is output * to the generated page. */ public abstract TagletOutput getTagletOutput(Tag tag, TagletWriter writer); } public abstract class BaseTaglet implements Taglet { ... /** * {@inheritDoc} */ public TagletOutput getTagletOutput(Tag tag, TagletWriter writer) { ###@###.### 2005-1-06 21:09:54 GMT ###@###.### 2005-1-06 21:46:50 GMT

06-01-2005