FlexDoc/Javadoc - JavadocClassic - Parameters

About JavadocClassic parameters

«Include» parameter group

Specify what additional information should be included in the documentation.

Parameter Name / Type / Description
Deprecated API include.deprecated : boolean

Specify whether to include deprecated API in the documentation.

When the parameter is unselected (false), no deprecated API will be documented at all. This will also override the setting of the parameter (in FramedDoc.tpl):

Generate | Cross-Reference Pages | Deprecated List
so no deprecated APIs list file and the «Deprecated» link in the navigation bar will be generated.

Default Value:

The default value of this parameter is set according to the -nodeprecated option found on the Javadoc command-line. When this option is specified, the default value is false, otherwise it is true.
Descriptions include.desc : boolean

Specify whether to include main descriptions found in doc-comments.

Default Value:

The default value of this parameter is set according to the -nocomment option found on the Javadoc command-line. When this option is specified, the default value is false, otherwise it is true.
Related Templates:
text.tpl, summary.tpl
Tag include.tag : boolean

Specify whether to document block tags found in doc-comments as well as to include any other descriptions coming from block tags.

The nested parameters control the documenting of particular block tags.

Default Value:

The default value of this parameter is set according to the -nocomment option found on the Javadoc command-line. When this option is specified, the default value is false, otherwise it is true.
Related Templates:
block-tags.tpl, text.tpl

@since

include.tag.since : boolean

Include in the generated docs the "Since" sections associated with the @since tags.

Default Value:

The default value of this parameter is set according to the -nosince option found on the Javadoc command-line. If this option is specified, the default value is false, otherwise it is true.

@version

include.tag.version : boolean

Include the @version text in the generated docs.

Default Value:

The default value of this parameter is set according to the -version option found on the Javadoc command-line. If this option is specified, the default value is true, otherwise it is false.

@author

include.tag.author : boolean

Include the @author text in the generated docs.

Default Value:

The default value of this parameter is set according to the -author option found on the Javadoc command-line. If this option is specified, the default value is true, otherwise it is false.

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
  1. The custom @todo tag should appear before all other block tags (because its group number is 0).
  2. @version tag should be documented before the @see tags followed by the documentation of @ejb:bean tag.
  3. 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.