Doc comment tags appear in source code documentation comments. They provide
structure that Javadoc can process into typographical formats for
presentation and cross-reference.
This document lists standard tags that Javadoc currently recognizes, and
proposed tags that the Javadoc standard doclet may someday recognize.
The purpose of this document is to stimulate discussion and provide notice
for tags we may be using in the future.
Standard Tags
Proposed Tags
- The following are tags that Sun may implement in Javadoc someday.
In this sense, these tags are "reserved".
Developers may use these tags now, at their own risk, for the
purposes stated below, and write their own doclets that make use
of them. The syntax for some of these tags is under consideration;
feel free to open a discussion in the
Javadoc news group.
While there is value in standardizing on tags,
Sun has not yet committed to handling these tags in the standard
doclet.
| Proposed Tag | Purpose |
@category | For logically grouping
classes, methods, fields (possibly shortened to @cat). Possible
syntax: @category name
For one interpretation of this tag, see:
Feature
Request #4085608 in Developer Connection. |
@example | For an example source code file
(*.java), either in-place or a link to an example. Syntax probably:
@example text
For more discussion, see:
Feature
Request #4075480 in Developer Connection. |
@tutorial | For a link to a
tutorial. Syntax undecided, with several choices.
For more discussion, see:
Feature
Request #4125834 in Developer Connection. |
@index | For text to appear in the
alphabetic Index. Possible syntax:
@index entry[:sub-entry]*
For more discussion, see:
Feature
Request #4034228 in Developer Connection. |
@exclude | For API to be excluded from
generation by Javadoc. Programmer would mark a class, interface,
constructor, method or field with @exclude. Presence of tag
would cause API to be excluded from the generated documentation. Text
following tag could explain reason for exclusion, but would be ignored
by Javadoc. (Formerly proposed as @hide, but the term
"hide" is more appropriate for run-time dynamic show/hide
capability.) For more discussion, see:
Feature
Request #4058216 in Developer Connection. |
@todo |
Indicates that work needs to be done on this part of the code.
This tag takes a text argument that is a description of the needed work.
|
@internal | For holding comments that are
internal to the company developing the code. This might contain comments
about implementation details which might not be relevant to end users who
are going to be using the class files. This would enable companies
to have an internal version of the generated documentation that would
contain more information to help other developers who may be new to the
project. This information could be filtered out with a switch on the
Javadoc command line when generating the documentation to distribute to
clients. Syntax: @internal text
For more discussion, see:
Feature
Request #4102647 in Developer Connection. |
@obsolete | To be used when deprecated API
is actually removed (if ever). Syntax to be determined. |
@threadsafety | Indicates whether a class or method is thread safe or not. Example:
@threadsafety This class and its methods are thread safe |
NOTE: @event is not needed. An important feature we want to add to Javadoc
is to list all events that can be generated
by a particular class. However, no tag (such as @event) is needed for this.
We determined we can automate this as follows. 1) Search through class
and superclasses for pattern "addxListener", delete duplicates, and then create
links to the "xEvent" class. (Problem: Which package is xEvent located in? Can
possibly tell by constructor "new pkg.xEvent")
NOTE: @source is not needed. One popular feature is adding source links
to the generated class files. This does not require adding any tag --
it can be handled by a command-line option specifying the source path.
Hence, @source is not listed here.
Third-Party Tags
- We currently do not list third-party tags.
Please send comments or questions about Javadoc tags to:  .
(This address is not selectable or clickable to prevent
email crawlers from getting it.)
|
