I did a recent javadoc build and found several warnings regarding the 
-breakiterator switch when parsing the java.lang.Exception class and 
it's descendents.  Many of these warning were propagated into the
JSN world by fixing 4496095.

I filed the following before finding out the root cause was actually
in Exception.

4901502
4901491
4901492

-------
/security/home/wetmore/ws/tiger-bolt/src/share/javax/net/ssl/SSLException.java:6
3: warning - The first sentence is interpreted to be:
"Creates a <code>SSLException</code> with the specified cause
 and a detail message of <tt>(cause==null ? null : cause.toString())</tt>
 (which typically contains the class and detail message of
 <tt>cause</tt>)."
This sentence is different from what would be generated using -breakiterator:
"Creates a <code>SSLException</code> with the specified cause
 and a detail message of <tt>(cause==null ? "
-------

Talking to Josh (fixer of "4209652 Chained Exception Facility" which
started these warnings), he made the following suggestion.

======
We need to attack this problem systematically, probably by adding a new Javadoc tag to delimit the initial sentence, where required.  (This is just a half-assed suggestion, but I think something along these lines will be required.)  I think that we should pass the problem off to the Javadoc team when they have the time.  Right now they're probably wilting under the strain of Generics/Varargs/Enums/Annotations:(

Josh
======

Not sure what the best solution is, but needs to be addressed before
the "next major revision" changes the behaviour.  :)

Thanks,

  xxxxx@xxxxx   2003-08-06

Rewrite the first sentences and avoid the code fragments.  Those can be 
deferred to the following sentence(s).

  xxxxx@xxxxx   2003-08-06

This is basically a duplicate of 
4810687: Can't workaround '?' in first sentence. Document the breakiterator rules.
But that only suggests changing the documentation to inform users of the
restriction.

Also related to  
4890489: -breakiterator should be the default (possibly only) option

  xxxxx@xxxxx   2003-08-27


BreakIterator is specifically *not* designed to work with math or programming
language fragments, so it's not surprising that it gets confused by question
marks (and this is only the tip of the iceberg).  The solution probably isn't 
to tweak BreakIterator, but rather to use this new feature once it gets
implemented:

4921374: Add tag to explicitly mark the end of the summary

Until then, closing this as "will not fix".  Note that -breakiterator
is not becoming the default algorithm in 1.5.


Scott Seligman wrote the above and closed the bug.  The underlying
problem is still there then, we need to update the various exception
classes which exhibit this behaviour.

I'm reopening and assigning to docs.  Please let me know if this is not
clear.

  xxxxx@xxxxx   2003-11-05

Closing out as no longer a bug (I wish there was a better reason to pick).  
The breakiterator error that Brad was seeing no longer occurs as of 
Dec 19, 2003 integration of the following bug, which removed that error message:

  4959985  Javadoc BreakIterator warning is no longer current.
  Integrated Dec 19, 2003

  xxxxx@xxxxx   2004-04-05