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