Uploaded image for project: 'JDK'
  1. JDK
  2. JDK-4959985

Javadoc BreakIterator warning is no longer current.

    XMLWordPrintable

Details

    • Bug
    • Resolution: Fixed
    • P3
    • 5.0
    • 5.0
    • tools
    • b32
    • sparc
    • solaris_9

    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

      Attachments

        Issue Links

          Activity

            People

              sseligmasunw Scott Seligman (Inactive)
              sseligmasunw Scott Seligman (Inactive)
              Votes:
              0 Vote for this issue
              Watchers:
              0 Start watching this issue

              Dates

                Created:
                Updated:
                Resolved:
                Imported:
                Indexed: