javadoc (original) (raw)

Enables the javadoc command to interpret a simple, one-argument @tagname custom block tag in documentation comments. For the javadoc command to spell-check tag names, it is important to include a -tag option for every custom tag that is present in the source code, disabling (with X) those that are not being output in the current run.The colon (:) is always the separator. The -tag option outputs the tag heading taghead in bold, followed on the next line by the text from its single argument. Similar to any block tag, the argument text can contain inline tags, which are also interpreted. The output is similar to standard one-argument tags, such as the @return and @author tags. Omitting a value for taghead causes tagname to be the heading.

Placement of tags: The Xaoptcmf arguments determine where in the source code the tag is allowed to be placed, and whether the tag can be disabled (using X). You can supply either a, to allow the tag in all places, or any combination of the other letters:

X (disable tag)

a (all)

o (overview)

p (packages)

t (types, that is classes and interfaces)

c (constructors)

m (methods)

f (fields)

Examples of single tags: An example of a tag option for a tag that can be used anywhere in the source code is: -tag todo:a:"To Do:".

If you want the @todo tag to be used only with constructors, methods, and fields, then you use: -tag todo:cmf:"To Do:".

Notice the last colon (:) is not a parameter separator, but is part of the heading text. You would use either tag option for source code that contains the @todo tag, such as: @todo The documentation for this method needs work.

Colons in tag names: Use a backslash to escape a colon that you want to use in a tag name. Use the -tag ejb\\:bean:a:"EJB Bean:" option for the following documentation comment:

/**

Spell-checking tag names: Some developers put custom tags in the source code that they do not always want to output. In these cases, it is important to list all tags that are in the source code, enabling the ones you want to output and disabling the ones you do not want to output. The presence of X disables the tag, while its absence enables the tag. This gives the javadoc command enough information to know whether a tag it encounters is unknown, which is probably the results of a typographical error or a misspelling. The javadoc command prints a warning in these cases. You can add X to the placement values already present, so that when you want to enable the tag, you can simply delete the X. For example, if the @todo tag is a tag that you want to suppress on output, then you would use: -tag todo:Xcmf:"To Do:". If you would rather keep it simple, then use this: -tag todo:X. The syntax -tag todo:X works even when the @todo tag is defined by a taglet.

Order of tags: The order of the -ta g and -taglet options determines the order the tags are output. You can mix the custom tags with the standard tags to intersperse them. The tag options for standard tags are placeholders only for determining the order. They take only the standard tag's name. Subheadings for standard tags cannot be altered. This is illustrated in the following example.If the -tag option is missing, then the position of the -tagle t option determines its order. If they are both present, then whichever appears last on the command line determines its order. This happens because the tags and taglets are processed in the order that they appear on the command line. For example, if the -taglet and -tag options have the name todo value, then the one that appears last on the command line determines the order.

Example of a complete set of tags: This example inserts To Do after Parameters and before Throws in the output. By using X, it also specifies that the @example tag might be encountered in the source code that should not be output during this run. If you use the @argfile tag, then you can put the tags on separate lines in an argument file similar to this (no line continuation characters needed):

-tag param -tag return -tag todo:a:"To Do:" -tag throws -tag see -tag example:X

When the javadoc command parses the documentation comments, any tag encountered that is neither a standard tag nor passed in with the -tag or -taglet options is considered unknown, and a warning is thrown.

The standard tags are initially stored internally in a list in their default order. Whenever the -tag options are used, those tags get appended to this list. Standard tags are moved from their default position. Therefore, if a -tag option is omitted for a standard tag, then it remains in its default position.

Avoiding conflicts: If you want to create your own namespace, then you can use a dot-separated naming convention similar to that used for packages: com.mycompany.todo. Oracle will continue to create standard tags whose names do not contain dots. Any tag you create will override the behavior of a tag by the same name defined by Oracle. If you create a @todo tag or taglet, then it always has the same behavior you define, even when Oracle later creates a standard tag of the same name.

You can also create more complex block tags or custom inline tags with the -taglet option.