Details
-
Enhancement
-
Resolution: Won't Fix
-
P3
-
5.0
-
generic
-
generic
Description
As JSR 260 works on standardizing a set of tags, and there are plenty
of proposals around (For example, these:
http://java.sun.com/j2se/javadoc/6/tags.html), it might be useful to
define, if possible, a criteria by which a tag can be identified as a
candidate to become a standard tag, and other tags may be skipped from
consideration.
Previously, Sun was using the criteria based on usefulness of the tag to
Java Platform API or to the very broad set of developers (that
information was acquired through voting or other means to get such
information). Now, as of this JSR, the opinion of community plays more
important role in establishing this criteria, and we can acquire it
explicitly through this JSR.
I'd like to know what is your opinion, as the representatives from Java
community, on when the tag may be considered a standard tag.
As a starting point, the following may be considered as a criteria:
The tag may be considered a standard tag, if:
- it's tied to a declaration (@param, @return,@throws, @serial)
- it's tied to an implementation (@version, @since, @deprecated)
- it has broad, general value to documentation (@author,
@see, {@link}, {@inherited})
Thanks.
-----------------------------------------------------------
> The purpose of the original question about the standard tag
> criteria was to see if it is possible to arrive at a criteria
> we can use to filter current and future tags as candidates
> for standard tags.
>
> When we first created Javadoc tags, the guidelines were that
> we include tags if they were useful for Sun to generate the
> Java Platform API. We would not include tags that were
> useful only to other APIs (@example is such a case --
> we had no plans to add examples, though others did).
>
> We'd like the team to come up with a statement as to what
> criteria should be met for a tag to become a standard tag,
> so it could be a published criteria.
>
> If it's a narrow definition, then perhaps we can close
> out many of the tag requests to become standard tags
> as will not fix. When new requests come in to make a
> tag standard, most just sit in the open state because
> we have no well-thought-out criteria for denying them
> as standard tags.
>
> If requests need to be handled one-by-one, then we
> will just keep requests open until the next Javadoc
> JSR.
Comments below from:
DM: Denis.Mikhalkin
SS: Scott.Seligman
DK: Douglas.Kramer
STANDARD PRIORITY (P4)
4619333 Separate out static factory methods and add @factory tag (0 votes)
DM: *** Already separately considered.
4921374 Add tag to explicitly mark end of or entire summary (0 votes)
DM: *** Already separately considered.
4948031 Support @link tags in user's html files in doc-files directory (3 votes)
DM: Not an extension of any javadoc specification; this is a tool issue.
4738591 Allow {@inheritDoc} to work with more tags (0 votes)
DM: Requests a modification to an existing spec, but the existing spec
hasn't been written.
4810216 Allow {@inheritDoc name} for constructors (1 vote)
DM: Requests a modification to an existing spec, but the existing spec hasn't
been written.
4077833 List the generated events for each class -- @event tag? (0 votes)
DM: *** Already separately considered. Very little customer call for this:
no votes, one comment, so we should probably not do it.
4517437 @author should work with member documentation (0 votes)
DM: Requests a modification to an existing spec, but the existing spec
hasn't been written.
4102647 Consider making @internal a standard tag (3 votes)
DM: This is being addressed in 1.7 by a language change.
DK: Not by the "friends" mechanism--this is a request for internal documentation.
4465111 Consider making @todo a standard tag (0 votes)
DM: Unclear what the benefit is to the user, as you can already use @todo.
4669046 Consider making {@date format} a standard tag (0 votes)
DM: Zero votes or JDC comments. Perhaps nobody cares.
4214766 Consider making {@class} {@parent} {@package} {@member} standard tags (3 votes)
DM: Hard to see what pressing problem is solved.
4213984 @insert or @include reference material (source, overview) (1 vote)
DM: Doesn't this undermine the idea of javadoc being the true source of
documentation? Only one vote, comment.
DK: I think you mean the doc comments as being the true source.
The intent is to include reference material already in the source tree.
We already allow linking to HTML files in doc-files/ directory --
this is quite analogous.
4725927 Javadoc needs a standard thread safety tag (0 votes)
DM: No votes, semantics unclear.
4343993 More replacement tags in Javadoc -eg- {@date} and {#buildNo} (0 votes)
DM: No votes, comments.
4058216 Exclude classes/members (e.g. RMI stubs and skeletons) @docset tag (48 votes)
DM: May be addressed as a friend-like mechanism in Dolphin (7.0)
5073382 Inline tags for marking program elements: {@class}, {@method}, {@field}, {@arg} (0 votes)
DM: No votes, comments.
5021058 Please allow Class.member notation in @see and @link (0 votes)
SS: This is a a tools issue -- at its core an RFE for the Doclet API.
It should be addressed, but not here.
4802498 Enable @param to validate & document multiple params: @param x,y (1 vote)
DM: This is a modificaton to a spec that doesn't yet exist.
LOWER PRIORITY (P5)
4034228 Add @index doc-comment tag for generating index from common words (0 votes)
4034242 Add @footnote and @footnoteref doc-comment tags (0 votes)
DM: These two are for controlling the generated docs, not code documentation.
4075480 Add example support in doc with @example tag (7 votes)
DM: *** Seems frequently useful. Has many votes and comments.
4405627 Proposal for @performance javadoc tag (4 votes)
DM: No comments, few votes, unclear benefit from "standardization".
4125834 Add @tutorial tag for linking to the Java Tutorial (4 votes)
DM: This is so J2SE-specific, and of much less use to Java developers outside the
J2SE developers.
SS: Perhaps this could be generalized so as to serve our needs without
being completely JDK-specific.
4219357 Add @protected, @package and @private tags for hiding public members (0 votes)
DM: More appropraitely addressed as language change currently considered for JDK7.
4137085 Design By Contract Support (@inv, @pre, @post) (13 votes)
DM: Very controversial - see the JDC thread. Debate unlikely to be resolved in
time for JDK6.
4777110 Propose @realizes javadoc tag (1 vote)
DM: Read the RFE; this is what JSR175 is for.
DK: Closed request.
4722209 Support XML tags as input to javadoc (0 votes)
DM: The only reason this hasn't been closed is that the submitter can't be contacted.
4359486 Add tag @spellskip to list words to skip when spell-checking (0 votes)
DM: These tags are for controlling external tools, not for documenting java code.
-----
SS: Some meta-comments...
>>Requests a modification to an existing spec, but the existing spec
>>hasn't been written.
SS: While somewhat true, that it itself shouldn't keep an issue from
being addressed. The javadoc reference pages are a spec, though
informal, and modifying them in certain ways may be quite appropriate.
###@###.### 2005-05-26 16:18:18 GMT
of proposals around (For example, these:
http://java.sun.com/j2se/javadoc/6/tags.html), it might be useful to
define, if possible, a criteria by which a tag can be identified as a
candidate to become a standard tag, and other tags may be skipped from
consideration.
Previously, Sun was using the criteria based on usefulness of the tag to
Java Platform API or to the very broad set of developers (that
information was acquired through voting or other means to get such
information). Now, as of this JSR, the opinion of community plays more
important role in establishing this criteria, and we can acquire it
explicitly through this JSR.
I'd like to know what is your opinion, as the representatives from Java
community, on when the tag may be considered a standard tag.
As a starting point, the following may be considered as a criteria:
The tag may be considered a standard tag, if:
- it's tied to a declaration (@param, @return,@throws, @serial)
- it's tied to an implementation (@version, @since, @deprecated)
- it has broad, general value to documentation (@author,
@see, {@link}, {@inherited})
Thanks.
-----------------------------------------------------------
> The purpose of the original question about the standard tag
> criteria was to see if it is possible to arrive at a criteria
> we can use to filter current and future tags as candidates
> for standard tags.
>
> When we first created Javadoc tags, the guidelines were that
> we include tags if they were useful for Sun to generate the
> Java Platform API. We would not include tags that were
> useful only to other APIs (@example is such a case --
> we had no plans to add examples, though others did).
>
> We'd like the team to come up with a statement as to what
> criteria should be met for a tag to become a standard tag,
> so it could be a published criteria.
>
> If it's a narrow definition, then perhaps we can close
> out many of the tag requests to become standard tags
> as will not fix. When new requests come in to make a
> tag standard, most just sit in the open state because
> we have no well-thought-out criteria for denying them
> as standard tags.
>
> If requests need to be handled one-by-one, then we
> will just keep requests open until the next Javadoc
> JSR.
Comments below from:
DM: Denis.Mikhalkin
SS: Scott.Seligman
DK: Douglas.Kramer
STANDARD PRIORITY (P4)
4619333 Separate out static factory methods and add @factory tag (0 votes)
DM: *** Already separately considered.
4921374 Add tag to explicitly mark end of or entire summary (0 votes)
DM: *** Already separately considered.
4948031 Support @link tags in user's html files in doc-files directory (3 votes)
DM: Not an extension of any javadoc specification; this is a tool issue.
4738591 Allow {@inheritDoc} to work with more tags (0 votes)
DM: Requests a modification to an existing spec, but the existing spec
hasn't been written.
4810216 Allow {@inheritDoc name} for constructors (1 vote)
DM: Requests a modification to an existing spec, but the existing spec hasn't
been written.
4077833 List the generated events for each class -- @event tag? (0 votes)
DM: *** Already separately considered. Very little customer call for this:
no votes, one comment, so we should probably not do it.
4517437 @author should work with member documentation (0 votes)
DM: Requests a modification to an existing spec, but the existing spec
hasn't been written.
4102647 Consider making @internal a standard tag (3 votes)
DM: This is being addressed in 1.7 by a language change.
DK: Not by the "friends" mechanism--this is a request for internal documentation.
4465111 Consider making @todo a standard tag (0 votes)
DM: Unclear what the benefit is to the user, as you can already use @todo.
4669046 Consider making {@date format} a standard tag (0 votes)
DM: Zero votes or JDC comments. Perhaps nobody cares.
4214766 Consider making {@class} {@parent} {@package} {@member} standard tags (3 votes)
DM: Hard to see what pressing problem is solved.
4213984 @insert or @include reference material (source, overview) (1 vote)
DM: Doesn't this undermine the idea of javadoc being the true source of
documentation? Only one vote, comment.
DK: I think you mean the doc comments as being the true source.
The intent is to include reference material already in the source tree.
We already allow linking to HTML files in doc-files/ directory --
this is quite analogous.
4725927 Javadoc needs a standard thread safety tag (0 votes)
DM: No votes, semantics unclear.
4343993 More replacement tags in Javadoc -eg- {@date} and {#buildNo} (0 votes)
DM: No votes, comments.
4058216 Exclude classes/members (e.g. RMI stubs and skeletons) @docset tag (48 votes)
DM: May be addressed as a friend-like mechanism in Dolphin (7.0)
5073382 Inline tags for marking program elements: {@class}, {@method}, {@field}, {@arg} (0 votes)
DM: No votes, comments.
5021058 Please allow Class.member notation in @see and @link (0 votes)
SS: This is a a tools issue -- at its core an RFE for the Doclet API.
It should be addressed, but not here.
4802498 Enable @param to validate & document multiple params: @param x,y (1 vote)
DM: This is a modificaton to a spec that doesn't yet exist.
LOWER PRIORITY (P5)
4034228 Add @index doc-comment tag for generating index from common words (0 votes)
4034242 Add @footnote and @footnoteref doc-comment tags (0 votes)
DM: These two are for controlling the generated docs, not code documentation.
4075480 Add example support in doc with @example tag (7 votes)
DM: *** Seems frequently useful. Has many votes and comments.
4405627 Proposal for @performance javadoc tag (4 votes)
DM: No comments, few votes, unclear benefit from "standardization".
4125834 Add @tutorial tag for linking to the Java Tutorial (4 votes)
DM: This is so J2SE-specific, and of much less use to Java developers outside the
J2SE developers.
SS: Perhaps this could be generalized so as to serve our needs without
being completely JDK-specific.
4219357 Add @protected, @package and @private tags for hiding public members (0 votes)
DM: More appropraitely addressed as language change currently considered for JDK7.
4137085 Design By Contract Support (@inv, @pre, @post) (13 votes)
DM: Very controversial - see the JDC thread. Debate unlikely to be resolved in
time for JDK6.
4777110 Propose @realizes javadoc tag (1 vote)
DM: Read the RFE; this is what JSR175 is for.
DK: Closed request.
4722209 Support XML tags as input to javadoc (0 votes)
DM: The only reason this hasn't been closed is that the submitter can't be contacted.
4359486 Add tag @spellskip to list words to skip when spell-checking (0 votes)
DM: These tags are for controlling external tools, not for documenting java code.
-----
SS: Some meta-comments...
>>Requests a modification to an existing spec, but the existing spec
>>hasn't been written.
SS: While somewhat true, that it itself shouldn't keep an issue from
being addressed. The javadoc reference pages are a spec, though
informal, and modifying them in certain ways may be quite appropriate.
###@###.### 2005-05-26 16:18:18 GMT