United StatesChange Country, Oracle Worldwide Web Sites Communities I am a... I want to...
Bug ID: JDK-4921374 Add tag to explicitly mark the end of the summary or mark the entire summary
JDK-4921374 : Add tag to explicitly mark the end of the summary or mark the entire summary

Details
Type:
Enhancement
Submit Date:
2003-09-11
Status:
Open
Updated Date:
2012-11-08
Project Name:
JDK
Resolved Date:
Component:
tools
OS:
other,windows_xp
Sub-Component:
javadoc(tool)
CPU:
x86,generic
Priority:
P4
Resolution:
Unresolved
Affected Versions:
1.4.2,5.0
Targeted Versions:

Related Reports
Duplicate:
Relates:
Relates:
Relates:
Relates:

Sub Tasks

Description
We need a way to explicitly mark a doc comment summary ("first 
sentence") break at an odd place.  This will help with the transition
from -breakiterator option (in 1.4.0) to it being the default in 1.5.0.

The summary is the description that appears in the table listing
the packages. classes or members.

One possible solution is an inline {@summaryBreak} tag.
Note that {@summaryBreak} does not necessarily indicate the end of 
the first sentence -- using it would make it possible to include two (or more)
sentences in the summary.

Another possible solution is a pair of block tags:  @summary and @description.
These would provide even greater flexibility, allowing the full description
to begin with something other than the summary sentence.


                                    

Comments
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
                                     
2005-06-09
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.
                                     
2007-08-06



Hardware and Software, Engineered to Work Together