Proposed Javadoc Tags

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

• The standard tags currently implemented in Javadoc are documented at Javadoc 1.2 reference page (with Windows examples)   (with Solaris examples).

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.)