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.
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.
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.
For an example source code file (*.java), either in-place or a link to an example. Syntax probably: @exampletext For more discussion, see: Feature Request #4075480 in Developer Connection.
For a link to a tutorial. Syntax undecided, with several choices. For more discussion, see: Feature Request #4125834 in Developer Connection.
For text to appear in the alphabetic Index. Possible syntax: @index entry[:sub-entry]* For more discussion, see: Feature Request #4034228 in Developer Connection.
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.
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.
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: @internaltext For more discussion, see: Feature Request #4102647 in Developer Connection.
To be used when deprecated API is actually removed (if ever). Syntax to be determined.
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.