Products         News         Downloads         Licensing         Shop         Support    

 DocFlex Technology
Overview
Features
Documentation
 DocFlex/XML
Overview
Features
Documentation
XSDDoc
WSDLDoc
DiagramKit
Integrations
 DocFlex/Javadoc
Overview
Documentation
JavadocClassic
Templates
Parameters
Examples
Tutorials
 DocFlex/Together
Overview
Examples
Basic Templates
Documentation
Tutorials
 Try
Downloads
Registration
Trial License
 Use
Licensing
Shop
Support
 Company
News
Products
Customers
About Us
Imprint
Legal
Contact
Links
 

DocFlex/Javadoc - JavadocClassic - Parameters

Parameter Tree


“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 “Generate | Cross-Reference Pages | Deprecated List” parameter, 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.
See Also:
Generate | Cross-Reference Pages | Deprecated List” parameter
Tags include.tag

This group of parameters controls whether to include in the generated docs the sections associated with some tags.

@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 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.

Specifying Single Tag

Documenting of a single tag is specified with the following expression:
tagname:Xaoptcmf:taghead
The 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
see:X
will suppress documenting of all @see tags. However,
see:Xf
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
specifies a custom @threadsafe tag to be documented anywhere it is used with the heading message:
Can be called safely from multiple threads
The following value item specifies that @todo tag should be processed only with constructors, methods and fields:
todo:cmf:To Do:
Notice the last colon (:) above is not a 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.
This line would produce output something like:
To Do:
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 the following setting of the parameter value:
ejb\:bean:a:EJB Bean:

Specifying Multiple Tags

Documenting of different tags should be specified in different items of the whole parameter value. 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:

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:"
(Note: Because the full parameter value here contains spaces, it is enclosed in quotes in order to make it treated as a single command-line argument.)

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:"
Each -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
This setting says that @version tag should be documented before the custom @todo tag followed by the documentation of @see tags.

Any other standard tags will be documented as usual in a certain some predefined order before the tags specified in this parameter.

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:
then, processed further to document all '@my;odd;tag' tags with "\My Odd Title\" title and all '@ejb:bean' tags with "EJB Bean:" title.

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.

Copyright© 2018 Filigris Works, Leonid Rudy Softwareprodukte. All rights reserved.