United StatesChange Country, Oracle Worldwide Web Sites Communities I am a... I want to...
Bug ID: JDK-4959985 Javadoc BreakIterator warning is no longer current.
JDK-4959985 : Javadoc BreakIterator warning is no longer current.

Details
Type:
Bug
Submit Date:
2003-11-26
Status:
Resolved
Updated Date:
2003-12-19
Project Name:
JDK
Resolved Date:
2003-12-19
Component:
tools
OS:
solaris_9
Sub-Component:
javadoc(tool)
CPU:
sparc
Priority:
P3
Resolution:
Fixed
Affected Versions:
5.0
Fixed Versions:
5.0 (b32)

Related Reports
Relates:
Relates:
Relates:
Relates:
Relates:

Sub Tasks

Description
In Merlin, a "javadoc -breakiterator" option was added.  For English
only, this forces the use of BreakIterator.  We also publicized our
intention to use BreakIterator exclusively in "the next major release".
When "-breakiterator" is not given and the two algorithms yield
different results, the following verbose warning is emitted by the tool:
 
    warning - The first sentence is interpreted to be:
    "..."
    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:
    "..."
    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.

However, it was decided that changing the default English algorithm
was ill-advised for Tiger, and probably any other release.  So, the
warning message should go away.

Furthermore, in a future release (hopefully 1.5.1) we will add new
javadoc tags to allow one to mark summaries explicitly and avoid using
heuristics of any kind.  This is how it probably should have been from
the start.  Given this the warning message can actually be seen as
doing harm, since its advice on how to fix problem comments does not
align with our actual plans.


More background info can be found here:

    4890489: -breakiterator should be the default (possibly only) option
    4921374: Add tag to explicitly mark the end of the summary
    4959973: please warn when I don't use @summary


                                    

Comments
EVALUATION


The warning is no longer current or appropriate.  It should be removed.

Keep track of warnings currently produced by the J2SE build, so that we
can fix our own doc comments at a future date.

###@###.### 2003-11-25

                                     
2003-11-25
PUBLIC COMMENTS

-
                                     
2004-06-10
CONVERTED DATA

BugTraq+ Release Management Values

COMMIT TO FIX:
tiger-beta

FIXED IN:
tiger-beta

INTEGRATED IN:
tiger-b32
tiger-beta


                                     
2004-06-14



Hardware and Software, Engineered to Work Together