-tag  tagname:Xaoptcmf:"taghead" Enables the Javadoc tool to interpret a simple, one-argument custom block tag @tagname in doc comments. So the Javadoc tool can "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. To use a colon in tagname, see Use of Colon in Tag Name. The -tag option outputs the tag's heading taghead in bold, followed on the next line by the text from its single argument, as shown in the example below. Like any block tag, this argument's text can contain inline tags, which are also interpreted. The output is similar to standard one-argument tags, such as @return and @author. Omitting taghead causes tagname to appear as the heading. Placement of tags - The Xaoptcmf part of the argument determines 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 wanted @todo to be used only with constructors, methods and fields, you would use: -tag todo:cmf:"To Do:" Notice the last colon (:) above is not a parameter separator, but is part of the heading text (as shown below). You would use either tag option for source code that contains the tag @todo, such as: @todo The documentation for this method needs work. Use of Colon in Tag Name - A colon can be used in a tag name if it is escaped with a backslash. For this doc comment: /** * @ejb:bean */ use this tag option: -tag ejb\\:bean:a:"EJB Bean:" Spell-checking tag names (Disabling tags) - Some developers put custom tags in the source code that they don't always want to output. In these cases, it is important to list all tags that are present in the source code, enabling the ones you want to output and disabling the ones you don't want to output. The presence of X disables the tag, while its absence enables the tag. This gives the Javadoc tool enough information to know if a tag it encounters is unknown, probably the results of a typo or a misspelling. It 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 @todo is a tag that you want to suppress on output, you would use: -tag todo:Xcmf:"To Do:" or, if you'd rather keep it simple: -tag todo:X The syntax -tag todo:X works even if @todo is defined by a taglet. Order of tags - The order of the -tag (and -taglet) options determine 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 -tag is missing, then the position of -taglet 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 -taglet and -tag both have the name "todo", the one that appears last on the command line will determine its 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 @example is a tag that might be encountered in the source code that should not be output during this run. Notice that if you use @argfile, you can put the tags on separate lines in an argument file like this (no line continuation characters needed): -tag param -tag return -tag todo:a:"To Do:" -tag throws -tag see -tag example:X When javadoc parses the doc comments, any tag encountered that is neither a standard tag nor passed in with -tag or -taglet is considered unknown, and a warning is thrown. The standard tags are initially stored internally in a list in their default order. Whenever -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, it remains in its default position. Avoiding Conflicts - If you want to slice out your own namespace, 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. In other words, if you create a tag or taglet @todo, it will always have the same behavior you define, even if Oracle later creates a standard tag of the same name. Annotations vs. Javadoc Tags - In general, if the markup you want to add is intended to affect or produce documentation, it should probably be a javadoc tag; otherwise, it should be an annotation. See Comparing Annotations and Javadoc Tags @ http://www.oracle.com/technetwork/java/javase/documentation/index-137868.html#annotations< You can also create more complex block tags, or custom inline tags with the -taglet option.