Lew said:
Most spell checkers would choke on "Javadoc". In fact, the one for my
newsreader flags it as a misspelling.
Then there's this:
/** Pick up the latest prices from the stock ticker.
* @param stockTicker <code>StockTicker</code> from which to get prices.
* @return Map < TickerSymbol, BigDecimal > map of TickerSymbol
prices.
* @throws IOException if there is a problem.
*/
Many, many of those words are flagged as misspellings, e.g., "param",
"stockTicker", "BigDecimal", "<", "IOException".
... your point being ...?
Spelling checkers can never declare that some sequence of
characters *is* a misspelled word (those that do so are buggy),
but can draw the human's attention to things that *might be*
misspelled. In this very paragraph, my E-mail client's spell
checker is unhappy with "human's," apparently confused by the
possessive. That doesn't cause me to go back and "correct" it,
but only to look twice to be sure I haven't typed "hmman's" or
"hunan's" or something. Nor does it cause me to turn off the
spelling checker on the grounds that it sometimes whines about
something that's perfectly all right; it's still, er, helpfull.
For Java source, a tool to improve Javadoc comments would
be nice. Something like a spell checker, but sensitive to the
"misspellings" that happen to match identifiers of parameters,
methods, classes and so on, combined with an HTML markup checker.
NetBeans' "autocomment" tool has just a tiny whiff of such a
capability, but not enough to overcome the big productivity drain
of using the stupid thing in the first place. (Why thrash your
hand back and forth from mouse to keyboard, pointing and clicking
and whirling instead of just <em>typing</em>, fer goodness' sake?)
Still, it's able to see that the `mode' parameter has no @param
tag but that there is a @param for the non-existent `mod', or
that there's a missing @throws, or that sort of thing. Some of
the capabilities of a useful tool must underlie this pile of
uselessness.
