JDK-4902492 : javadoc is throwing breakiterator warnings at '?' on java.lang.Exception
  • Type: Bug
  • Component: docs
  • Sub-Component: guides
  • Affected Version: 5.0
  • Priority: P4
  • Status: Closed
  • Resolution: Not an Issue
  • OS: generic
  • CPU: generic
  • Submitted: 2003-08-07
  • Updated: 2004-04-05
  • Resolved: 2004-04-05
Related Reports
Relates :  
Description
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,

###@###.### 2003-08-06

Comments
PUBLIC COMMENTS -
10-06-2004

EVALUATION 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 ###@###.### 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. ###@###.### 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 ###@###.### 2004-04-05
05-04-2004

WORK AROUND Rewrite the first sentences and avoid the code fragments. Those can be deferred to the following sentence(s). ###@###.### 2003-08-06
06-08-2003