include.tag.custom : list of strings
This parameter is an analog of the
-tag option provided by the
(See also Default Value below.)
It allows you to include in the generated output the documentation of your custom block tags, to specify the tag headings as well as their ordering.
You will be able also to redefine the headings and ordering of the standard tags
This parameter accepts multiple (list) value. Each value item specifies how a single tag should be documented.
Specifying Single Tag
Documenting of a single block tag is specified with the following expression:
which consists of several parts separated with colons (
Here are the descriptions of all parts:
The first three parts are the standard ones. They are the same as in the
option supported by the Standard Doclet. So, any value of that option can be equally processed as the value of this parameter
(see Default Value
Not all parts are required. However, since the standard three are identified by their positions, if any of them (or anything after them) is present,
those before must be present as well.
The last two parts are the feature of this template set. If present, they must follow the standard parts. However, their positions are not fixed.
Specify the name of the tag for which this setting applies.
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:
||Meaning / Location
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,
@see tags only for fields.
|types (that is classes and interfaces)
Specify the heading for the tag documentation.
For example, here
"To Do:" is the heading for
The tag heading can be omitted either by providing only those parts standing before it
or by specifying nothing at all in its place, e.g.:
taghead causes the
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.
When the tag heading ends with the colon (
) and other specification parts
then the colon should be escaped with a slash, e.g.
The same applies when a colon happens to be inside the heading.
See also: Using Escapes
Specify the group number, which the tag is assigned with, where
N is any integer number.
Tag groups are used as a way of global ordering of the tags.
In the output documentation, block tags are sorted first according their group numbers and, then,
according to the order of their specification in this parameter.
By default, all tags are assigned with the group number 1.
So, if you want to place some block tags before all others (including before the default ones),
just assign them with the group number 0.
Specify whether to not indent the documentation of this tag.
By default, in the output generated by this template set, the documentation (text) of each block tag
is indented to the left by a certain standard block width (the same as this description is indented against the item name).
This setting suppresses that indentation.
The following value item (of this parameter):
specifies a custom
threadsafe:a:Can be called safely from multiple threads
@threadsafe tag to be documented anywhere it is used with the heading message:
Can be called safely from multiple threads
This value item (of this parameter) specifies that
@todo tag should be processed only with constructors,
methods and fields and documented with "To Do:" heading:
If you have specified a
@todo tag somewhere like this:
that would produce the following documentation output:
@todo This method needs to be optimized.
This method needs to be optimized.
This tag is used frequently in Java SE API documentation.
Its effect is appending an additional description section headed «Implementation Note:»,
which looks just like the continuation of the main description.
Here is how that tag can be specified with this parameter to have the same effect:
"gr0" ensures that this tag will be documented just after the description text
"noindent" – that the tag text will not be indented anyhow.
Now, suppose we have the following doc-comment in the Java code:
That would produce the following documentation output:
* Main description text ...
* @author John Smith
* @implNote <i>Something about the implementation</i>
Main description text ...
Something about the implementation
Specifying Multiple Tags
Documenting of different block tags should be specified with different items
of the whole value of this parameter (which is a list). Each value item should define how to document a single tag as described
above. The items must be separated with one of the allowed item separator characters (
These two lines specify respectively
or the same as a single line:
The last form can be used to specify both tags on the Javadoc command-line:
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 successive
Since the full parameter value here contains spaces, it is enclosed in quotes to have it treated as a single command-line
Each -p option adds a separate value item to
-p "include.tag.custom=ejb\:bean:a:EJB Bean:"
-p "include.tag.custom=todo:cmf:To Do:"
The block tags will appear in the output documentation sorted, first, according their group numbers
and, then, according to the order of their specification in this parameter.
For instance, in the example above, the documentation of
'@ejb:bean' tag will be followed by the documentation of
Using this parameter, you can also redefine the ordering of the standard tags, for example:
This setting says that
version;todo:cmf:To Do:gr0;see;ejb\:bean:a:EJB Bean:
- The custom
@todo tag should appear before all other block tags (because its group number is 0).
@version tag should be documented before the
@see tags followed by the documentation of
Any other standard block tags will be documented as usual in a certain predefined order after
@todo tag, however,
Each character that serves as a value item separator can be equally used within the value items
if escaped with a backslash. For example, documenting of the tag:
can be specified like this:
If a backslash is not consumed by an escape it will be remained in the text as is.
To make sure that a backslash is not part of some escape, you may add another backslash.
A sequence of two backslashes (
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:
will be initially processed and broken into two value items:
my\;odd\;tag:a:\My Odd Title\\;ejb\:bean:a:EJB Bean:
which are processed further to document all tags
my;odd;tag:a:\My Odd Title\
with the title «
\My Odd Title\»,
and all tags
with the title «
The default value of this parameter is produced from all
options found on the Javadoc command-line. Each
is converted to a single value item of this parameter.
So, you can use Standard Doclet's
-tag options instead of specifying this parameter directly.