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