This parameter duplicates the functionality of the -tag
option supported by the Standard Doclet.
It allows you to include in the generated output the documentation of your custom tags, specify the tag headings as well as their ordering. You will be able also to redefine the headings and ordering of the standard tags (such as @param, @see, @author etc).
This parameter accepts multiple (list) value. Each value item specifies how a single tag should be documented.
tagname:Xaoptcmf:taghead
tagname
is the name of the tag for which this setting applies.
The taghead
is the heading for the tag documentation. Omitting taghead
causes tagname
to be used as the heading (unless this is a standard tag). If the tag has no text (specified in the Java comment), only the heading will appear in the generated output.
The Xaoptcmf
part determines the locations in the source code where the tag is to be processed/documented. Each letter specify possible tag locations according to this table:
Letter | Meaning / Location |
X |
Rather than including the tag, this letter indicates that the tag should be ignored in the specified locations. For example, specifying
will suppress documenting of all @see tags. However,
suppresses @see tags only for fields.
|
a |
all locations |
o |
project overview |
p |
packages overviews |
t |
types (that is classes and interfaces) |
c |
constructors |
m |
methods |
f |
fields |
Examples:
The following parameter value item:
threadsafe:a:Can be called safely from multiple threads
@threadsafe
tag to be documented anywhere it is used with the heading message:
@todo
tag should be processed only with constructors, methods and fields:
todo:cmf:To Do:
@todo The documentation for this method needs work.
The documentation for this method needs work.
A colon can be used in a tag name if it is escaped with a backslash. For this doc comment:
use the following setting of the parameter value:/** * @ejb:bean */
ejb\:bean:a:EJB Bean:
newline
or ';'
).
Example:
ejb\:bean:a:EJB Bean:
todo:cmf:To Do:
ejb\:bean:a:EJB Bean:;todo:cmf:To Do:
-p:include.tag.custom "ejb\:bean:a:EJB Bean:;todo:cmf:To Do:"
The same can be also specified with two -p
options:
-p:include.tag.custom "ejb\:bean:a:EJB Bean:"
-p:include.tag.custom "todo:cmf:To Do:"
-p
option adds a separate value item to 'include.tag.custom'
parameter.
Tag Ordering
The tags will appear in the output documentation in the same order as they are specified in the value items of this parameter. For instance, in the example above, the documentation of '@ejb:bean'
tag will be followed by the documentation of '@todo'
tag.
Using this parameter, you can also redefine the ordering of the standard tags, for example:
version;todo:cmf:To Do:;see
Any other standard tags will be documented as usual in a certain some predefined order before the tags specified in this parameter.
@my;odd;tag
my\;odd\;tag:a:My odd tag:
"\\"
) is an escape by itself, which represents a single backslash.
This is important because backslashes may be used also in a secondary system of escapes (e.g. to escape ':'
within the tag name).
For example, a string like this:
my\;odd\;tag:a:\My Odd Title:\\;ejb\:bean:a:EJB Bean:
my;odd;tag:a:\My Odd Title\
ejb\:bean:a:EJB Bean:
'@my;odd;tag'
tags
with "\My Odd Title\" title and all '@ejb:bean'
tags with
"EJB Bean:" title.