JDK-4921374 : Add tag to explicitly mark the end of the summary or mark the entire summary
  • Type: Enhancement
  • Component: tools
  • Sub-Component: javadoc(tool)
  • Affected Version: 1.4.2,5.0
  • Priority: P4
  • Status: Resolved
  • Resolution: Duplicate
  • OS: other,windows_xp
  • CPU: generic,x86
  • Submitted: 2003-09-11
  • Updated: 2018-02-08
  • Resolved: 2018-02-08
The Version table provides details related to the release that this issue/RFE will be addressed.

Unresolved : Release in which this issue/RFE will be addressed.
Resolved: Release in which this issue/RFE has been resolved.
Fixed : Release in which this issue/RFE has been fixed. The release containing this fix may be available for download as an Early Access Release or a General Availability Release.

To download the current JDK release, click here.
JDK 10
10Resolved
Related Reports
Duplicate :  
JDK-4935515 - Cannot override Javadoc's sentence bounary algorithm
Duplicate :  
JDK-8173425 - Javadoc needs a new tag to specify the summary.
Relates :  
JDK-4890489 - -breakiterator should be the default (possibly only) option
Relates :  
JDK-4902492 - javadoc is throwing breakiterator warnings at '?' on java.lang.Exception
Relates :  
JDK-4959973 - please warn when I don't use @summary
Relates :  
JDK-4959985 - Javadoc BreakIterator warning is no longer current.
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
Duplicate of JDK-8173425
08-02-2018
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.
06-08-2007
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
09-06-2005