United StatesChange Country, Oracle Worldwide Web Sites Communities I am a... I want to...
Bug ID: JDK-4172961 First sentence does not stop if it ends in a capital letter - propose {@period}
JDK-4172961 : First sentence does not stop if it ends in a capital letter - propose {@period}

Details
Type:
Bug
Submit Date:
1998-09-11
Status:
Closed
Updated Date:
1998-09-11
Project Name:
JDK
Resolved Date:
1998-09-11
Component:
docs
OS:
windows_nt
Sub-Component:
doclet
CPU:
x86
Priority:
P4
Resolution:
Duplicate
Affected Versions:
1.2.0
Fixed Versions:

Related Reports
Duplicate:
Relates:
Relates:

Sub Tasks

Description

Name: tb29552			Date: 09/11/98

=20
The JLS says:
> The first sentence of each documentation comment should be a summary sent=
ence, containing a concise but complete description of
> the declared entity. This sentence ends at the first period that is follo=
wed by a blank, tab, or line terminator, or at the first tagline (as
> defined below).

But the following sentence
    This package contains the core classes of our SDK. More precisely...
will give
    This package contains the core classes of our SDK. More precisely.

A period is ignored if it is preceded by anything but a lowercase letter. T=
his is inconsistent with the JLS and the JavaDoc documentation.
  From the related (but this is not a duplicate) bugs, 4140384, 4158381 and=
 4165985 I was under the impression that this is caused=20
by the use of java.text.BreakIterator. If it is so and you persist in using=
 it then the JavaDoc must be updated. This will spare=20
developers a lot of time when they try to understand why one sentence break=
s correctly and not the other one.

4140384 - design bug: ambiguous "first sentence" rule - closed, fixed in 1.=
2fcs
4158381 - sentence BreakIterator stops too soon (more) - in progress
4165985 - Use BreakIterator to determine end of first sentence - in progres=
s

I would be very much in favor of something less error prone than relying on=
 a period. Or maybe we could introduce an {@period} tag.
 - sentences that break too early could be fixed by using '.' which =
although unrecognized by some browsers is part of HTML 3.2.
 - the end of the sentence could be detected either using the regular rules=
 for java.text.BreakIterator or by using the {@period} tag.

or provide two new tags:

  /**
   * @summary This is the summary sentence. This could even be more than ju=
st one sentence actually.
   * @description This is the description. To form the complete description=
 we would prepend the summary.
   */

Both proposals should be backward compatible.
(Review ID: 38648)
======================================================================

                                    

Comments



Hardware and Software, Engineered to Work Together