Duplicate :
|
|
Relates :
|
|
Relates :
|
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) ======================================================================