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)
======================================================================