On Jan 30, 2006, at 11:34 PM, Jacob Kjome wrote:
Have either of you looked at the Ant docs for the Javadoc task
since Ant-1.6 came out (a long, long, time ago, I might add)? It
includes a "breakiterator" attribute which, as I understand it,
takes effect under JDK1.4+. I could be wrong, since I've never
actually tested it under JDK1.3.1, but it seems to me that the
smart way to implement the feature would be to ignore
breakiterator="true" in cases where the JDK is less than 1.4. That
way, the build is not tied to a particular JDK as additionalparam="-
breakiterator" would do. Please let me know if I'm wrong. But if
I'm not, it would make sense to use breakiterator="true"
Using the breakiterator attribute on the javadoc task would have
fixed the problem without requiring changes to the documentation
comments. It hadn't crossed my mind that additionalparam="-
breakiterator" could have been a legacy from Ant 1.5.
However, the changes made to the doc comments were desirable since
the places where the original sentence analyzer and the breakiterator
differed in their analysis were places where there should have been a
sentence and wasn't. The only marginal case was:
- Return <code>true</code> if the buffer is full, i.e. of the
+ Return <code>true</code> if the buffer is full, that is the
number of elements in the buffer equals the buffer size. */
Where the period after the "i" in "i.e." was considered the end of
the first sentence by the original sentence scanner and breakiterator
would have ended after "size". I replaced "i.e." with its English
equivalent which eliminated the discrepancy. I had a vague
recollection that Strunk and White's "The Elements of Style" had an
explicit prohibition on "i.e." and "e.g.". I couldn't find it, but
you could infer it from "19. Do not take shortcuts at the cost of
clarity" and "20. Avoid foreign languages".
Since using the BreakIterator as the default analyzer in Javadoc has
been abandoned, I do not think it is desirable to add it back into
the build since the switch will likely eventually disappear in a
decade or two. At the moment, it would make no difference since the
cases where it did make a difference has been eliminated.
---------------------------------------------------------------------
To unsubscribe, e-mail: [EMAIL PROTECTED]
For additional commands, e-mail: [EMAIL PROTECTED]
