Name: rm29839 Date: 05/20/98


The rule for which text from a method's document
comment that JavaDoc includes in the method index
is ambiguous, or at least is not fully compatible
with normal English punctuation.

For example, see the Method Summary section for
UndoableEdit:

 String
       getRedoPresentationName()
           Provide a localized, human readable
           description of the redoable form of
           this edit, e.g.
 
 String
       getUndoPresentationName()
           Provide a localized, human readable
           description of the undoable form of
           this edit, e.g.

JavaDoc shouldn't be trying to parse English
sentences, given that that's nontrivial and
given that it doesn't get it right.

JavaDoc should use something less ambiguous to
define the separation between the introductory
text (included in the index) from the detailed
description (included only in the full method
description).

You should use something like a blank line, an
HTML tag (e.g., <P>), or something else definite
like those, to separate the index comment from
the full description.

Also, JavaDoc overdefines the policy that the
index comment is one sentence. That is, if one
really needs to be two sentences, the programmer/
documenter should be stopped by the tool from
doing that.

Please think about cleaning up this behavior
a bit.
(Review ID: 28765)
======================================================================