Custom tags
|
include.tag.custom : list of strings
This parameter is an analog of the -tag option provided by the
Standard Doclet.
(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
(such as @param , @see , @author , etc).
This parameter accepts multiple (list) value. Each value item specifies how a single tag should be documented.
Further Contents:
Specifying Single Tag
Documenting of a single block tag is specified with the following expression:
-
tagname:Xaosptcmf:taghead:grN:noindent
which consists of several parts separated with colons (':' ).
The first three parts are the standard ones. They are the same as in the
-tag
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.
Here are the descriptions of all parts:
tagname
-
Specify the name of the tag for which this setting applies.
Xaosptcmf
-
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
see:X
will suppress documenting of all @see tags. However,
see:Xf
suppresses @see tags only for fields.
|
a |
all locations |
o |
project overview |
s |
module description |
p |
package description |
t |
types (that is classes and interfaces) |
c |
constructors |
m |
methods |
f |
fields |
taghead
-
Specify the heading for the tag documentation.
For example, here "To Do:" is the heading for "todo" tag:
todo:cmf:To Do:
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.:
todo
todo:cmf
todo:cmf::gr3
Omitting taghead causes the tagname to be used as the heading (unless this is a standard tag).
When the tag heading ends with the colon ( ':' ) and other specification parts follow it,
then the colon should be escaped with a slash, e.g.
todo:cmf:To Do\::gr3
The same applies when a colon happens to be inside the heading.
See also: Using Escapes
If the tag has no text (specified in the Java comment), only the heading will appear in the generated output.
grN
-
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.
noindent
-
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.
Examples:
@threadsafe
-
The following value item (of this parameter):
-
threadsafe:a:Can be called safely from multiple threads
specifies a custom @threadsafe tag to be documented anywhere it is used with the heading message:
-
Can be called safely from multiple threads
@todo
-
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:
todo:cmf:To Do:
If you have specified a @todo tag somewhere like this:
-
@todo This method needs to be optimized.
that would produce the following documentation output:
-
To Do:
-
This method needs to be optimized.
@implNote
-
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:
-
implNote:a:Implementation Note\::gr0:noindent
Here, "gr0" ensures that this tag will be documented just after the description text
and "noindent" – that the tag text will not be indented anyhow.
Now, suppose we have the following doc-comment in the Java code:
-
/**
* Main description text ...
*
* @author John Smith
* @implNote <i>Something about the implementation</i>
*/
That would produce the following documentation output:
-
Main description text ...
Implementation Note:
Something about the implementation
Author:
-
John Smith
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 (newline or ';' ).
Example:
These two lines specify respectively @ejb:bean and @todo tags:
ejb\:bean:a:EJB Bean:
todo:cmf:To Do:
or the same as a single line:
ejb\:bean:a:EJB Bean:;todo:cmf:To Do:
The last form can be used to specify both tags on the Javadoc command-line:
-p "include.tag.custom=ejb\:bean:a:EJB Bean:;todo:cmf:To Do:"
Since the full parameter value here contains spaces, it is enclosed in quotes to have it treated as a single command-line argument.
The same can be also specified with two successive -p options:
-
-p "include.tag.custom=ejb\:bean:a:EJB Bean:"
-p "include.tag.custom=todo:cmf:To Do:"
Each -p option adds a separate value item to 'include.tag.custom' parameter.
Tag Ordering
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 '@todo' tag.
Using this parameter, you can also redefine the ordering of the standard tags, for example:
version;todo:cmf:To Do:gr0;see;ejb\:bean:a:EJB Bean:
This setting says that
- 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 @ejb:bean tag.
-
Any other standard block tags will be documented as usual in a certain predefined order after
@todo tag, however,
before @version tag.
Using Escapes
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:
-
@my;odd;tag
can be specified like this:
-
my\;odd\;tag:a:My odd tag:
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 ("\\" ) 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:
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
with the title «\My Odd Title\ »,
and all tags
-
@ejb:bean
with the title «EJB Bean: »
Default Value
The default value of this parameter is produced from all
-tag
options found on the Javadoc command-line. Each -tag option
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.
|