Can't workaround '?' in first sentence with -breakiterator. Document the breakiterator rules.

As specified in the
http://java.sun.com/j2se/javadoc/writingdoccomments/index.html#firstsentence
document, when delimeters have to be present in the first sentence,
the &xxx; or a html tag should legitimate the preceding delimeter.
However, for the following comment:

    /**
     * Write &lt;?<!-- -->xml declaration with encoding (if encoding not null)
     * and standalone flag (if standalone not null)
     * This method can only be called just after setOutput.
     */
    public void startDocument (String encoding, Boolean standalone)
        throws IOException, IllegalArgumentException, IllegalStateException;

javadoc generates the following warning:

  [javadoc] Generating /export1/ws/pv76716/ams/build/javadoc/index-all.html...
  [javadoc] /export1/ws/pv76716/ams/src/provisioning/share/org/xmlpull/v1/XmlSerializer.java:110: warning - The first sentence is interpreted to be:
  [javadoc] "Write &lt;?<!-- -->xml declaration with encoding (if encoding not null)
  [javadoc] and standalone flag (if standalone not null)
  [javadoc] This method can only be called just after setOutput."
  [javadoc] This sentence is different from what will be interpreted as the first sentence in the
  [javadoc] next major release (when that interpretation will be internationalized), which is:
  [javadoc] "Write &lt;?"
  [javadoc] To avoid this note, change the doc comment to make this a proper first sentence, then
  [javadoc] use -breakiterator from that point forward, which will output this new sentence.

disregarding whether the <!-- --> is present or not.

Doug added:
As indicated above, the first sentence is interpreted improperly when
-breakiterator is used:

   Write <?

The first sentence is interpreted properly (in 1.5.0 and earlier releases)
when -breakiterator is not used:

   Write <?xml declaration with encoding...


###@###.### 2005-1-06 17:00:41 GMT