EVALUATION

Here's the most up-to-date version of the proposal.  A goal is
to have the common case look just like we have it today.

Add two new tags -- @summary and @detail -- which can be used like this:

    @summary  Removes the specified element from this set.
    @detail   More formally, removes an element {@code e} such that...

If either or both tags are present, then any text preceding 
the first block tag has an implied @summary tag.

Therefore the use of @summary is entirely optional -- if omitted
it will be added implicitly:

    Removes the specified element from this set.
    @detail   More formally, removes an element {@code e} such that...

Additional rules:

- If neither tag is present, behavior is as today.
- If only @summary is present, behavior is as if an empty @detail block
  follows.
- If multiple @summary blocks are present, all but first is ignored 
  and a warning is emitted.
- If multiple @detail blocks are present, their text is concatenated together
  in order.  This would be useful for alternating with, for example, tags
  like the proposed @nonSpec. 

Stylistic guidance -- recommended practice but not to be required:

- Omit the explicit @summary tag, and rely on it being implicitly added
  to any text before the first block tag.  This keeps the feel of the docs
  much like it is today, while simplifying the underlying model (since a
  doc comment becomes a sequence of block tags, plain and simple).
- Omit the explicit @detail tag whenever the summary is such a simple
  sentence that there is no question of the "default algorithm" getting it
  wrong.
- Using @summary without @detail is fine.
- Omitting both tags is fine.  In fact, it should be overwhelmingly the
  most common case.
- The @summary tag (if present) should always be the first block tag, and
  @detail the next.
                                     

EVALUATION

Doug wrote:

/**
* This is the first sentence. {@break}
* Now the rest...
*/

Not bad.  It's the least perturbation to existing code, and
seems to solve the problem in the most intelligent way.
It's intuitively clear that the sentence ahead of it is in fact the
first sentence of the generated description.  It doesn't suffer
from the ambiguity that @summary has where someone
might think it's only for the summary and nothing else.

If the author is writing a comment and isn't sure they are
going to get the proper sentence break, they just insert this
tag and move on.  It makes less sense for them to have to
introduce two new tags @summary and @detail just to
define the end of the first sentence.

--------------
Scott replied:

Well, my first (unsent) attempt used {@endSummary}.
There also {@summaryEnd} or {@summaryBreak}.

-------------
Doug replied:

{@summaryBreak} is more descriptive (though longer) than {@break}.

This is quite subtle, but I lean slightly toward "break" rather than "end" 
because the tag signifies a break in the overall comment.  Whereas 
"endSummary" might be interpreted to infer that what follows is the 
start of something else, which it isn't.   The term "break" is also 
tied to the name BreakIterator.

Explicitly specifying the break will also enable users to include two 
sentences in the summary, which a couple of developers have asked for.

###@###.### 2003-09-11


The latest proposal on the table was suggested by Robert Field.  A new
@summary block tag gives the summary if present; otherwise the summary is
taken as the first sentence of the description.  A new @description block
tag gives the description if present; otherwise, all text preceding the first
block tag is treated as the text of an implicit @description tag.

Having both an @description tag and text preceding the block tags
is treated as an error.  The @description tag "wins", and the
other text is discarded with a warning message.

Some methods in the Doclet API must have their descriptions updated to 
reflect the fact that the summary and the description may now be taken
from these new tags.  The signatures of these methods need not be changed.

Robert writes:

tags are not ordered, don't require pairs and, if you want
semantic simplisity -- an untagged beginning is equalivalent to @description
Thus these are equivalent --

/**
 * Comment.  More.
 */
 
/**
 * @description   Comment.   More.
 */
 
/**
 * @summary       Comment. 
 * @description   Comment.   More.
 */
 
/**
 * @description   Comment.   More.
 * @summary       Comment. 
 */
 

/**
 * Comment.   More.
 * @summary       Comment. 
 */

###@###.### 2003-09-22

Also see related bug:

    4959973: please warn when I don't use @summary

###@###.### 2004-01-25


A downside of the above block-tag proposal is the duplication of the
summary in the overwhelmingly-most-common case where you *do* want the
summary to lead the full description.

So here's a proposed modification:

a) If you use the block tag @summary, the summary is automatically prepended
   to the full description.
b) There's no way around (a).
c) It's OK that there's no way around (a).  There's no way around it
   today, and few people are complaining.  What they're complaining about
   is the separator (sentence break) issue, and that issue is orthogonal.
d) If some day we decide that we need to address (a), we'll deal with it
   then, separately.

This modified version makes me want to rename @description to @detail, so:

	@summary  Removes the specified element from this set.
	@detail   More formally, removes an element e such that...

###@###.### 2005-06-09 23:44:19 GMT