|
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
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.
xxxxx@xxxxx 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.
*/
xxxxx@xxxxx 2003-09-22
Also see related bug:
4959973: please warn when I don't use @summary
xxxxx@xxxxx 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...
xxxxx@xxxxx 2005-06-09 23:44:19 GMT
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.
Posted Date : 2007-08-06 06:56:23.0
|
