DocFlex/Javadoc - JavadocPro - Parameters

Window Title
Documentation Title
Generate
Include
Filter Classes & Members
Pagination

Parameter Name / Type / Description
Window Title windowTitle : string

Specifies the browser window title for the documentation. This is the same as -windowtitle option of the Standard Doclet. In addition, if the selected output format is RTF, the same text will appear on the page footers.

Default Value:

The default value of this parameter will be taken from the -windowtitle option found on the Javadoc command line.
Documentation Title docTitle : text

Specifies the title to be placed at the the top of the documentation overview (overview summary file). This is the same as -doctitle option of the Standard Doclet.

Default Value:

The default value of this parameter will be taken from the -doctitle option specified on the Javadoc command line.
See Also:
Generate | Title Page” parameter

“Generate” parameter group

The parameter group to control the overall content of the generated Java API documentation.

Parameter Name / Type / Description
Title Page gen.titlePage : boolean

Specify whether to generate the Title Page.

The title page is available only in single file documentation (generated with PlainDoc.tpl main template). When generated, it will be the very first page of the entire documentation.

Related Template:

The title page is generated by title-page.tpl template.
See Also:
Documentation Title” parameter
Table Of Contents gen.toc : boolean

Specify whether to insert the Table Of Contents of the documentation.

Currently, the Table Of Contents is available only in RTF documentation (generated with PlainDoc.tpl main template). However, it is not actually generated. Rather, a special RTF “{TOC}” field is inserted. The real Table Of Contents is generated by MS Word according to that field and style/level paragraph settings specified on the headings of some documentation section. This produces the Table Of Contents with the following structure:

Overview.......................
   Package Summary.............
   All Classes Summary.........
package1.......................
   class1......................
   class2......................
   ...
package2.......................
   ...
...
To have the Table Of Contents generated, the document should be loaded in MS Word and the {TOC} field updated. For instance, you can press Ctrl-A (select all) and then F9 (update selected fields).

Related Template:

The Table Of Contents is generated by TOC.tpl template.
See Also:
Pagination | Start from new page | Table Of Contents” parameter
Overview gen.overview : boolean

Specifies whether to generate the Overview page/section (an equivalent of the overview-summary.html file generated by the Standard Doclet).

It is the front page of Java API documentation and provides a list of all packages with a summary for each. This page can also contain an overall description of the set of packages.

In the case of framed HTML documentation (generated by FramedDoc.tpl), the Overview page is always generated and, therefore, this parameter is fixed.

In the case of single file (RTF) documentation (generated by PlainDoc.tpl), the Overview section may also include a summary of all documented classes. This is controlled by “Generate | Overview | All Classes Summary” parameter.

Related Template:

The Overview page/section is generated by overview.tpl template.
See Also:
Pagination | Start from new page | Overview” parameter

Package Summary

gen.overview.packages : boolean

Specify whether the documentation Overview will include the summary of all documented packages.

These are the packages containing any documented classes. For instance, when you document only a single class, there will be a package containing it, which will appear in the overview package summary, when this parameter is selected.

Related Template:

A package summary table is generated by package-summary.tpl template.

Package Groups

gen.overview.packages.groups : list of strings

This parameter is an analog of -group option provided by the Standard Doclet. It allows you to separates packages on the overview page into whatever groups you specify, one group per table.

The parameter accepts multiple (list) value. Each value item specifies a single package group.

Specifying Package Group

A package group is specified as follows:
packagepattern1:packagepattern2:...::groupheading
where
  • packagepattern can be any package name, or can be the start of any package name followed by an asterisk (*). The asterisk is a wildcard meaning “match any characters”. This is the only wildcard allowed.
  • groupheading can be any text (including white spaces). This text is placed in the table heading for the group

Example:

java.*:javax.*::This is a title

Specifying Multiple Package Groups

Different package groups should be specified with separate items of the whole parameter value. Each value item should define a single group as described above. The items must be separated with one of the allowed item separators (newline or ';').

Example:

java.awt.*:javax.swing.*::Java GUI API
org.w3c.*::W3C API
or the same as a single line:
java.awt.*:javax.swing.*::Java GUI API;org.w3c.*::W3C API
The last form can be used to specify both groups on the Javadoc command line:
-p:gen.overview.packages.groups "java.awt.*:javax.swing.*::Java GUI API;org.w3c.*::W3C API"
(Note: Because here the full parameter value 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 -P options:

-p:gen.overview.packages.groups "java.awt.*:javax.swing.*::Java GUI API" -p:gen.overview.packages.groups "org.w3c.*::W3C API"
Each -P option adds a separate value item to the 'gen.overview.packages.groups' parameter.

Using Escapes

Each character that serves as a value item separator can be equally used within the value item if escaped with a backslash. 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.

For example, a package group with the title:

The API to process ';' and '\' in text
can be specified like this:
textmill.semicolon.*:textmill.slash.*::The API to process '\;' and '\\' in text

Sorting Order

The groups appear on the page in the order of the parameter's value items specifying each group (i.e. in the same order as the package groups are specified on the command line). The packages are alphabetized within a group.

Packages Outside Groups

If you specify no package groups (the parameter value is empty), all packages are placed in one group with the heading “Packages”.

If the all groups do not include all documented packages, any leftover packages appear in a separate group with the heading “Other Packages”, which is printed the last.

Default Value

The default value of this parameter is produced from all -group options found on the Javadoc command line. Each -group option is converted to a single value item of this parameter.

So, you can use Standard Doclet's -group options instead of specifying this parameter directly.

All Classes Summary

gen.overview.allClasses : boolean

Specify whether the documentation Overview will include the summary of all documented classes.

Related Template:

A class summary table is generated by class-summary.tpl template.
See Also:
Pagination | Start from new page | All Classes Summary” parameter
Package Overviews gen.package : boolean

Specifies whether to generate a Package Overview page/section for every documented package (an equivalent of the package-summary.html file generated by the Standard Doclet).

When this parameter is selected (true), a Package Overview will be generated for every package containing at least one documented class.

Note:

This parameter/group is available only in PlainDoc.tpl template. In case of framed documentation, the Package Overviews are generated anyway.
Related Template:
A Package Overview page/section is generated by package.tpl template.
See Also:
Pagination | Start from new page | Package Overviews” parameter

Class Summary

gen.package.classes : boolean

Specify whether Package Overview will include the summary of all documented classes contained in that package.

Related Template:

A class summary table is generated by class-summary.tpl template.
Class Detail gen.class : boolean

Specify whether to generate a Class Details page/section for each class or interface being documented.

It includes the class description, various reference lists about it, as well as the details of all documented members of that class (except nested classes). This provides the bulk of the whole Java API documentation.

Note:

In the case of framed HTML documentation (generated by FramedDoc.tpl), the class details are always generated and, therefore, this parameter cannot be unchecked.
Related Template:
Each Class Detail page/section is generated by class.tpl template.
See Also:
Pagination | Start from new page | Class Detail” parameter

Member Summary

gen.class.member.summary : boolean

Specifies whether to include the summary of class members (i.e. fields and methods) and inner classes.

Inherited Members

gen.class.member.summary.inherited : boolean

Specify whether to include the lists of inherited inner classes, fields or methods.

Exclude for Packages

gen.class.member.summary.inherited.exclude : list of strings

This parameter allows you to exclude the lists of inner classes, fields or methods that are inherited from the classes/interfaces which belong to the specified packages.

For instance, you may want to suppress the long lists of the class members inherited from standard Java API classes and, thereby, to reduce the output documentation

The packages, whose classes/interfaces should not appear in the "inherited from ..." lists, are specified as the list of package patterns separated with newlines or colons (:). For example:

java.lang.*
javax.swing.*
A package pattern can be any package name, or can be the start of any package name followed by an asterisk (*). The asterisk is a wildcard meaning “match any characters”. This is the only wildcard allowed.

See Also:

DocFlex/Javadoc | Documentation | DocFlex Doclet | Handling Template Parameters | Multi-valued (List) Parameters

Member Detail

gen.class.member.detail : boolean

Specify whether to include the details of class members (i.e. fields and methods). If false (unchecked), only overview for each class will be generated without the details for the class' members.

Constant Field Values

gen.class.member.detail.constantValues : boolean

Specify whether to show the constant field values directly in the field documentation headers. For example:

public static final byte CONTROL = 15
This is an alternative to the constant field values page offered by the standard Javadoc (which can be equally generated by JavadocPro template set).

See Also:

Generate | Cross-Reference Pages | Constant Field Values” parameter
Cross-Reference Pages gen.refs

The parameter group to control the generation of various reference pages.

Note:

These parameters are avalaible only in FramedDoc.tpl main template, which generates framed HTML documentation.

All Classes Summary

gen.refs.allClasses : boolean

Specify whether to generated All Class Summary page, which is loaded when clicking on “All Classes” item in the navigation bar.

It is a replacement of the standard 'allclasses-noframe.html' file (generated by the Standard Doclet), which is intended to view in NO FRAMES mode.

Unlike the standard one, All Class Summary page shows not just the list of pure class names but rather a summary of all classes with the first sentence description of each class. It is also available in the FRAMES mode.

Related Template:

The All Classes page is generated by class-summary.tpl template.

Use (Package/Class)

gen.refs.use : boolean

Specify whether to generate a “use” page for each documented class and package. The page describes what packages, classes, methods, constructors and fields use any API of the given class or package.

Default Value:

The default value of this parameter is set according to the -use option found on the Javadoc command line. If this option is specified, the default value is true, otherwise it is false.
Related Templates:
The Use pages are generated by package-use.tpl and class-use.tpl templates.

Tree (Class Hierarchy)

gen.refs.tree : boolean

Specify whether to generate class/interface hierarchy pages. These are the pages you reach using the “Tree” button in the navigation bar.

Default Value:

The default value of this parameter is set according to the -notree option found on the Javadoc command line. If this option is specified, the default value is false, otherwise it is true.
Related Template:
The Class Hierarchy pages are generated by class-tree.tpl template.

Deprecated List

gen.refs.deprecatedList : boolean

Specify whether to generate the deprecated API page ('deprecated-list.html' file), which contains the list of deprecated APIs, and the “Deprecated” link in the navigation bar to that page.

Note:

This parameter has no effect on the generation of the deprecated API throughout the rest of the documentation, which is controlled separately by “Include | Deprecated API” parameter.
Default Value:
The default value of this parameter is set according to the -nodeprecatedlist option found on the Javadoc command line. When this option is specified, the default value is false, otherwise it is true.
Related Template:
The Deprecated API page is generated by deprecated-list.tpl template.

Index

gen.refs.index : boolean

Specify whether to generate an index.

Default Value:

The default value of this parameter is set according to the -noindex option found on the Javadoc command line. If this option is specified, the default value is false, otherwise it is true.
Related Templates:
The index is generated by two templates:
  1. index-all.tpl generates a single 'index-all.html' file
  2. index-letter.tpl generats either separate index files for each particular letter or corresponding sections of the single index file.

Split

gen.refs.index.split : boolean

Specify whether to split the index file into multiple files, alphabetically, one file per letter, plus a file for any index entries that start with non-alphabetical characters.

Default Value:

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

Serialized Form

gen.refs.serializedForm : boolean

Specify whether to generate the serialized form page.

That page contains information about serializable and externalizable classes. Each such class has a description of its serialization fields and methods. This information is of interest to re-implementors, not to developers using the API. While there is no link in the navigation bar, you can get to this information by going to any serialized class and clicking “Serialized Form” in the “See also” section of the class comment.

Related Template:

The Serialized Form page is generated by serialized-form.tpl template.

Constant Field Values

gen.refs.constantValues : boolean

Specify whether to generate the constant field values page ('constant-values.html' file), which lists the static final fields and their values.

Related Template:

The Constant Field Values page is generated by constant-values.tpl template.
See Also:
Generate | Class Detail | Member Detail | Constant Field Values” parameter
Help gen.help : boolean

Specify whether to generate the help page. This is the page you reach using the “Help” button in the navigation bar.

Default Value:

The default value of this parameter is set according to the -nohelp option found on the Javadoc command line. If this option is specified, the default value is false, otherwise it is true.
Related Template:
The Help page is generated by help-doc.tpl template.
Navigation bar gen.navbar : boolean

Specify whether to generate the navigation bar located at the top and bottom of the generated HTML pages.

Notes:

Default Value:
The default value of this parameter is set according to the -nonavbar option found on the Javadoc command line. If this option is specified, the default value is false, otherwise it is true.
Related Template:
All navigation bars are generated by the same navbar.tpl template.

Header Text

gen.navbar.headerText : text

This parameter is similar to -header option provided by the Standard Doclet. It specifies the header text to be placed at the top of each detail page. The header will be placed to the right of the upper navigation bar.

Additionally, when the header text is specified, it is inserted also at the top of the 'overview-frame.html' file (generated by overview-frame.tpl), used in the upper-left frame.

Default Value:

The default value of this parameter will be taken from the -header option found on the Javadoc command line.

Footer Text

gen.navbar.footerText : text

This parameter is similar to -footer option provided by the Standard Doclet. It specifies the footer text to be placed at the bottom of each each detail page. The footer will be placed to the right of the lower navigation bar.

The footer text may contain HTML tags and white space.

Note:

When the footer text is not specified, the header text (specified in “Header Text” parameter) will be used instead of it.
Default Value:
The default value of this parameter will be taken from the -footer option found on the Javadoc command line.
Bottom Text gen.bottomText : text

This parameter is similar to -bottom option provided by the Standard Doclet. It specifies the text to be placed at the bottom of each detail page/file, below the lower navigation bar.

The bottom text may contain HTML tags and white space.

Default Value:

The default value of this parameter will be taken from the -bottom option found on the Javadoc command line.
About (footer) gen.about : enum {"full", "short", "none"}

Specify whether to generate the “About” section added at the bottom of each generated document.

This section shows certain information about DocFlex/Javadoc software, which powers this Java API Documentation Generator.

Possible Values:

"full"
Generate the detailed information.
"short"
Generate only a brief notice.
"none"
Do not generate the “About” section.
Related Template:
Actually, all what you can see in the “About” section is generated entirely by about.tpl template.

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

“Show” parameter group

This parameter group controls the generation of various small fragments (like parts of qualified names, specific sections etc.)

Parameter Name / Type / Description
Package Qualifiers show.qualifier : boolean

This parameter/group controls whether to show qualifying package name ahead of class names in parameters, types, referenced classes (like exception lists, implemented interfaces, etc.), specified with @see tags and {@link} tags in comments.

When this parameter is unchecked (false), all package qualifiers will be omitted.

Note:

To omit package qualifiers only for selected packages, please use the nested parameter “Omit for Packages”.
Default Value:
The default value of this parameter is calculated according to the -noqualifier option provided by the Standard Doclet.

If that option is specified on the Javadoc command line as

-noqualifier all
the default value of this parameter is false, otherwise it is true.

Omit for Packages

show.qualifier.omit : list of strings

Specify the packages whose qualifying names should be omitted from ahead of class names in the output.

The packages to omit are specified as the list of package patterns separated with newlines or colons (:). For example:

java.lang.*
javax.swing.*
A package pattern can be any package name, or can be the start of any package name followed by an asterisk (*). The asterisk is a wildcard meaning “match any characters”. This is the only wildcard allowed.

Default Value:

The default value of this parameter is calculated according to the -noqualifier option provided by the Standard Doclet.

If that option is found on the Javadoc command line like:

-noqualifier packagepattern1:packagepattern2:...
the specified list of package patterns will be used as the default value of this parameter.
See Also:
DocFlex/Javadoc | Documentation | DocFlex Doclet | Handling Template Parameters | Multi-valued (List) Parameters
Link Titles (Tooltips) show.linkTitle : boolean

Specify whether to generate hyperlink titles.

In HTML, hyperlink titles are specified using title attribute, like this:

<a ... title="link tooltip text"> ... </a>
Most browsers will interpret it as a hyperlink tooltip (a tiny window with the text that appears near the hyperlink when the mouse cursor is moved over it).

Such tooltips can be used to quickly see additional information about the linked text. For instance, when the link appears on a Java class name, its tooltip may reveal what kind of class it is (e.g. ordinary class, interface, enum or annotation type) and which package it belongs to.

“Filter Classes & Members” parameter group

This group of parameters allows you to filter classes and members that will appear in the generated Java API documentation.

You can identify classes and members to be documented both:

Exclusion of Classes

The inclusion/exclusions of classes is controlled separately, which allows you to exclude specific classes from the documentation, yet to let some their public/protected members be visible still.

The overall effect will be that the generated JavaDoc will look as if the excluded classes themselves did never exist at all, however, everything else is in place and correct.

In that case, the generated Java API documentation will effectively reorganize your actual Java implementation, excluding certain classes and showing some of their member as if they belong to other classes (derived from the excluded ones).

In fact, there is nothing wrong with such a reorganization, because the standard Javadoc actually does it too. For instance, when you specify documenting only public classes, the package-local ones will get excluded, but the public members defined in them may show up as part of the documented classes, which inherit them.

Inheriting methods of excluded classes

As an example, suppose we have the following situation: Now, let's assume that the class C3 must be excluded from the documentation. What will happen with the method m()? It will be shown in the documentation as declared in the class C2! Then, for the class C1, m() must appear as inherited from the class C2 (rather than from the class C3, as it actually is in the code).

Shadowing of equally named fields

The same situation is with fields, which is actually even more complicated, because equally named fields do not overload but shadow each other. For example: Let's assume the interface I must be excluded from the documentation. What will happen with the field I.F? Actually, nothing! It shouldn't get in the documentation because it is shadowed by C2.F, which is private and, therefore, must be invisible.

Dynamic extension of type variables

For example, we have a class C1 defined like this:
class C1 {
  ...
  public void mmm (V param);
}
and class C2 that extends C1:
class C2 extends C1 {
  ...
}
Now, suppose that class C1 should be excluded from the documentation, but its method C1.mmm() should not. Then, showing that method like:
C2.mmm (V param)
would be incorrect because class C2 has no type variable 'V' (and even if it had that would be actually a different variable). So, what would be correct then? Actually this:
C2.mmm (String param)
And that's how it will be process and documented by this template set!

Parameter Name / Type / Description
By Tags filter.byTags

This group of parameters allows you to filter classes and members by tags. You can identify classes and members to be documented both:

  • Explicitly -- those that are marked with including tags
  • Implicitly -- those that are not marked with the excluding tags
Note that since any tags are embedded in Java doc comments, they are not stored in the compiled Java code. So, you can filter by tags only classes and members whose Java sources have been specified on the Javadoc command line (with -sourcepath option or directly).

If you need to filter anything contained in the compiled object code, use filtering by annotations instead (see “Filter Classes & Members | By Annotations” parameter group)

For packages

filter.byTags.for.packages : list of strings

Specify the packages, for which filtering by tags applies.

When this parameter is specified, only classes that belong to the specified packages may be excluded from the documentation according to any filtering by tags criteria (both explicit and implicit ones).

The packages are specified as the list of package patterns separated with newlines or colons (:). For example:

com.company.project.*
org.project.*
A package pattern can be any package name, or can be the start of any package name followed by an asterisk (*). The asterisk is a wildcard meaning “match any characters”. This is the only wildcard allowed.

See Also:

DocFlex/Javadoc | Documentation | DocFlex Doclet | Handling Template Parameters | Multi-valued (List) Parameters

Include

filter.byTags.include

This group of parameters allows you to include in the generated documentation only classes, fields and methods marked with the specified tags.

classes & members

filter.byTags.include.all : list of strings

Specify tags, by which both classes and class members (i.e. fields, constructors and methods) are included in the generated documentation.

When this parameter is specified, the entire documentation scope will be limited as follows.

A class is included in the documentation only when at least one of the conditions is met:

  1. The class has one of the specified tags.
  2. This is an inner class and one of its enclosing classes has one of the specified tags.
A class member is included according to one of the conditions:
  1. The member has one of the specified tags.

    Note: When the class containing the member must be excluded, the member itself may still appear in the documentation. If that class has documented subclasses, the member will be shown as if it belongs to those of them, which are the nearest descendants of the member's original class.

  2. The member's class has one of the specified tags.
  3. The member's class is an inner class and one of its enclosing classes has one of the specified tags.

When you specify this parameter, the criteria above are only necessary for a class or member to be actually included in the documentation scope. However, they do not guarantee it. Using other include/exclude parameters, you can limit the documentation scope even further!

The multiple exclude-tag names must be separated with new lines ('\n'), semicolons (';') or colons (':'). For example:
@api
@include
See Also:
DocFlex/Javadoc | Documentation | DocFlex Doclet | Handling Template Parameters | Multi-valued (List) Parameters

classes

filter.byTags.include.classes : list of strings

With this parameter you can explicitly identify classes to be documented, while keeping in the documentation some of the fields and methods defined in the classes to be excluded.

The tags specified in this parameter are treated as follows.

A class is included in the documentation only when it has one of the specified tags.

Each inheritable member of any excluded class, which has subclasses to be documented, will be shown as if it belongs to those of them that are the nearest descendants of the member's original class.

When you specify this parameter, the criteria above are only necessary for a class or member to be actually included in the documentation scope. However, they do not guarantee it. Using other include/exclude parameters, you can limit the documentation scope even further!

The multiple exclude-tag names must be separated with new lines ('\n'), semicolons (';') or colons (':'). For example:
@api
@include
See Also:
DocFlex/Javadoc | Documentation | DocFlex Doclet | Handling Template Parameters | Multi-valued (List) Parameters

members

filter.byTags.include.members : list of strings

This parameter allows you to specify precisely which class members (fields & methods) should be documented.

The tags specified in this parameter are treated as follows.

A class member is included in the documentation only when it has one of the specified tags.

Note: When the class containing such a member must be excluded, the member itself may still appear in the documentation. If that class has subclasses to be documented, the member will be shown as if it belongs to those of them, which are the nearest descendants of the member's original class.

When you specify this parameter, the condition above is only necessary for a member to be actually included in the documentation scope. Using other include/exclude parameters, you can limit which members are included even further!

The multiple exclude-tag names must be separated with new lines ('\n'), semicolons (';') or colons (':'). For example:
@api
@include
See Also:
DocFlex/Javadoc | Documentation | DocFlex Doclet | Handling Template Parameters | Multi-valued (List) Parameters

Exclude

filter.byTags.exclude

This group of parameters allows you to exclude from the generated documentation classes, fields and methods with the specified tags (custom or not).

classes & members

filter.byTags.exclude.all : list of strings

Specify tags by which both classes and class members (i.e. fields, constructors and methods) are completely excluded from the generated documentation.

A class is excluded when at least one of the conditions is met:

  1. The class has one of the specified tags.
  2. This is an inner class and one of its enclosing classes has one of the specified tags.
A class member is excluded according to one of the conditions:
  1. The member has one of the specified tags.
  2. The member's class has one of the specified tags.
  3. The member's class is an inner class and one of its enclosing classes has one of the specified tags.
Therefore, when a class has one of the tags specified in this parameter, neither that class nor anything defined in it (i.e. members and inner classes) will ever appear in the documentation.

The multiple exclude-tag names must be separated with new lines ('\n'), semicolons (';') or colons (':'). For example:

@exclude
@omit
See Also:
DocFlex/Javadoc | Documentation | DocFlex Doclet | Handling Template Parameters | Multi-valued (List) Parameters

classes

filter.byTags.exclude.classes : list of strings

This parameter allows you to hide completely from the generated documentation some intermediate classes of your internal implementation (that for some reasons need to be public), while keeping in the documentation some of the fields and methods defined in those excluded classes, which you actually want to be part of your open API.

The tags specified in this parameter are treated as the following.

A class will be never mentioned in the documentation when at least one of the conditions is met:

  1. The class has one of the specified tags.
  2. This is an inner class and one of its enclosing classes has one of the specified tags.
Each inheritable member of any excluded class, which has subclasses to be documented, will be shown as if it belongs to those of them that are the nearest descendants of the member's original class.

The overall effect should be that the generated documentation will look as if the excluded classes themselves did never exist at all, however, everything else is in place and correct. (For that matter, see also description of the "Filter Classes & Members" parameter group.)

The multiple exclude-tag names must be separated with new lines ('\n'), semicolons (';') or colons (':'). For example:

@exclude
@omit
See Also:
DocFlex/Javadoc | Documentation | DocFlex Doclet | Handling Template Parameters | Multi-valued (List) Parameters

members

filter.byTags.exclude.members : list of strings

Specify tags by which only class members (i.e. fields, constructors and methods) are selectively excluded from the generated documentation.

A class member, which otherwise (without this parameter) would be documented, is excluded when it has at least one of the specified tags.

The multiple exclude-tag names must be separated with new lines ('\n'), semicolons (';') or colons (':'). For example:

@exclude
@omit
See Also:
DocFlex/Javadoc | Documentation | DocFlex Doclet | Handling Template Parameters | Multi-valued (List) Parameters
By Annotations filter.byAnns

This group of parameters provides an alternative way to filter classes and members that appear in the generated documentation.

As you know, one of the new language features introduced in Java 5 is annotations. Annotations are essentially similar to tags. However, unlike tags, they are specified not within Java comments, but directly in Java code. That is, annotations are processed by the Java compiler itself and can be retained in the compiled binary classes (which is impossible with tags).

So, you can use annotations the same as tags to mark some of your classes and members to filter them out or retain in the generated documentation.

But, why would you need to use annotations? Why are tags not enough?

Let's suppose, you have a library of some core Java classes for internal use. That library is quite a separate thing. So, you may use it in different projects (or different people are using it). Therefore, you maintain that library in a pre-compiled binary form as a jar-file.

Now, you develop a project, in which you use that internal library. You want to publish certain classes of that project as an open API to your system. But some of those classes are inherited from the classes contained in your internal library (or implement interfaces from it). An ordinary Java API documentation generated by Javadoc would mention those internal classes as superclasses (implemented interfaces) of your API. But you want them to be invisible in the published documentation. They are internal after all! So, how can you do that?

Marking your internal classes with tags will not work, because your tags will not get into the compiled jar-file.

Here is where annotations can help! Let's see how you can do it.

First, you need to define your annotation type like the following (all names are for example):

package myprojects.core.util;

public @interface Internal {
}
Those lines should be saved as Internal.java file located in 'myprojects/core/util' package.

Note that as with any Java class, the defined annotation type has a fully qualified name, which will be the string: "myprojects.core.util.Internal". Only the fully qualified name can be used to find annotations of a given type.

Now, you can use this annotation type to mark your internal classes. Here is how:

package myprojects.core.classes;
...
import myprojects.core.util.Internal;

@Internal
public class MyIterator {
...
}
After that, you can exclude all classes marked with that annotation from the generated documentation by specifying the annotation type qualified name 'myprojects.core.util.Internal' in the “Filter Classes & Members | By Annotations | Exclude | Classes” parameter.

This will equally work both with the classes defined in the Java sources and the binary classes found on the Javadoc classpath!

For

filter.byAnns.for

With these parameters you can limit the scope, to which filtering by annotations applies. (That is the classes that may be excluded from the documentation according to any filtering by annotation criteria -- both explicit and implicitly ones).

The limitation is needed because since filtering by annotations potentially extends to all classes involved (including those contained in pre-compiled Java libraries), it may have unwanted side effects.

For instance, when you include only classes marked with the specified annotations (using “Filter Classes & Members | By Annotations | Include | Classes” parameter), without any limitation to what this applies, all standard Java SDK classes (e.g. even java.lang.Object) will get excluded from being mentioned as ancestors of your classes. That will be wrong, of course!

But even more surprising would be to see all public fields and methods of those standard Java classes to show up in your documentation as if they are defined in your own classes you document.

active set only

filter.byAnns.for.activeSet : boolean

When this parameter is selected (true) the filtering by annotations will apply only for classes and members included in the “documented” set.

These are all classes (and packages) initially specified to Javadoc to be documented and filtered according to the access control options (-public, -protected, -package, and -private).

packages

filter.byAnns.for.packages : list of strings

Specify the packages, for which filtering by annotations applies.

When this parameter is specified, only classes that belong to the specified packages may be excluded from the documentation according to any filtering by annotation criteria (both explicit and implicit ones).

The packages are specified as the list of package patterns separated with newlines or colons (:). For example:

com.company.project.*
org.project.*
A package pattern can be any package name, or can be the start of any package name followed by an asterisk (*). The asterisk is a wildcard meaning “match any characters”. This is the only wildcard allowed.

See Also:

DocFlex/Javadoc | Documentation | DocFlex Doclet | Handling Template Parameters | Multi-valued (List) Parameters

Include

filter.byAnns.include

This group of parameters allows you to include in the generated documentation only classes, fields and methods marked with the specified annotations (custom or not).

classes & members

filter.byAnns.include.all : list of strings

Specify annotation types, by which both classes and class members (i.e. fields, constructors and methods) are included in the generated documentation.

When this parameter is specified, the entire documentation scope will be limited as follows.

A class is included in the documentation only when at least one of the conditions is met:

  1. The class has an annotation of one of the specified types.
  2. This is an inner class and one of its enclosing classes has an annotation of one of the specified types.
A class member is included according to one of the conditions:
  1. The member has an annotation of one of the specified types.

    Note: When the class containing the member must be excluded, the member itself may still appear in the documentation. If that class has documented subclasses, the member will be shown as if it belongs to those of them, which are the nearest descendants of the member's original class.

  2. The member's class has an annotation of one of the specified types.
  3. The member's class is an inner class and one of its enclosing classes has an annotation of one of the specified types.

When you specify this parameter, the criteria above are only necessary for a class or member to be actually included in the documentation scope. However, they do not guarantee it. Using other include/exclude parameters, you can limit the documentation scope even further!

Each annotation type must be specified with its fully qualified name (e.g. java.lang.Deprecated). Multiple annotation type names must be separated with new lines ('\n'), semicolons (';') or colons (':'). For example:
my.core.util.Public
my.project.api.Include
See Also:
DocFlex/Javadoc | Documentation | DocFlex Doclet | Handling Template Parameters | Multi-valued (List) Parameters

classes

filter.byAnns.include.classes : list of strings

With this parameter you can explicitly identify classes to be documented, while keeping in the documentation some of the fields and methods defined in the classes to be excluded.

The annotation types specified in this parameter are treated as follows.

A class is included in the documentation only when it has an annotation of one of the specified types.

Each inheritable member of any excluded class, which has subclasses to be documented, will be shown as if it belongs to those of them that are the nearest descendants of the member's original class.

When you specify this parameter, the criteria above are only necessary for a class or member to be actually included in the documentation scope. However, they do not guarantee it. Using other include/exclude parameters, you can limit the documentation scope even further!

Each annotation type must be specified with its fully qualified name (e.g. java.lang.Deprecated). Multiple annotation type names must be separated with new lines ('\n'), semicolons (';') or colons (':'). For example:
my.core.util.Public
my.project.api.Include
See Also:
DocFlex/Javadoc | Documentation | DocFlex Doclet | Handling Template Parameters | Multi-valued (List) Parameters

members

filter.byAnns.include.members : list of strings

This parameter allows you to specify precisely which class members (fields & methods) should be documented.

The annotation types specified in this parameter are treated as follows.

A class member is included in the documentation only when it has an annotation of one of the specified types.

Note: When the class containing such a member must be excluded, the member itself may still appear in the documentation. If that class has subclasses to be documented, the member will be shown as if it belongs to those of them, which are the nearest descendants of the member's original class.

When you specify this parameter, the condition above is only necessary for a member to be actually included in the documentation scope. Using other include/exclude parameters, you can limit which members are included even further!

Each annotation type must be specified with its fully qualified name (e.g. java.lang.Deprecated). Multiple annotation type names must be separated with new lines ('\n'), semicolons (';') or colons (':'). For example:
my.core.util.Public
my.project.api.Include
See Also:
DocFlex/Javadoc | Documentation | DocFlex Doclet | Handling Template Parameters | Multi-valued (List) Parameters

Exclude

filter.byAnns.exclude

This group of parameters allows you to exclude from the generated documentation classes, fields and methods with the specified annotations (custom or not).

classes & members

filter.byAnns.exclude.all : list of strings

Specify annotation types by which both classes and class members (i.e. fields, constructors and methods) are completely excluded from the generated documentation.

A class is excluded when at least one of the conditions is met:

  1. The class has an annotation of one of the specified types.
  2. This is an inner class and one of its enclosing classes has an annotation of one of the specified types.
A class member is excluded according to one of the conditions:
  1. The member has an annotation of one of the specified types.
  2. The member's class has an annotation of one of the specified types.
  3. The member's class is an inner class and one of its enclosing classes has an annotation of one of the specified types.
Therefore, when a class has one of the annotations specified in this parameter, neither that class nor anything defined in it (i.e. members and inner classes) will appear in the documentation.

Each annotation type must be specified with its fully qualified name (e.g. java.lang.Deprecated). Multiple annotation type names must be separated with new lines ('\n'), semicolons (';') or colons (':'). For example:

my.core.util.Internal
my.project.api.Exclude
See Also:
DocFlex/Javadoc | Documentation | DocFlex Doclet | Handling Template Parameters | Multi-valued (List) Parameters

classes

filter.byAnns.exclude.classes : list of strings

This parameter allows to hide completely from the generated documentation some intermediate classes of your internal implementation (that for some reasons need to be public), however, to preserve documenting of some fields and methods (defined within those classes), which are supposed to be part of an open API.

This may be particularly helpful when you will need next time to change your implementation while keeping intact what you have declared in your open API.

The annotation types specified in this parameter are treated as the following.

A class will be never mentioned in the documentation when at least one of the conditions is met:

  1. The class has an annotation of one of the specified types.
  2. This is an inner class and one of its enclosing classes has an annotation of one of the specified types.
Each inheritable member of any excluded class, which has subclasses to be documented, will be shown as if it belongs to those of them that are the nearest descendants of the member's original class.

The overall effect should be that the generated documentation will look as if the excluded classes themselves did never exist at all, however, everything else is in place and correct. (For that matter, see also the description of the "Filter Classes & Members" parameter group.)

Each annotation type must be specified with its fully qualified name (e.g. java.lang.Deprecated). Multiple annotation type names must be separated with new lines ('\n'), semicolons (';') or colons (':'). For example:

my.core.util.Internal
my.project.api.Exclude
See Also:
DocFlex/Javadoc | Documentation | DocFlex Doclet | Handling Template Parameters | Multi-valued (List) Parameters

members

filter.byAnns.exclude.members : list of strings

Specify annotation types by which only class members (i.e. fields, constructors and methods) are selectively excluded from the generated documentation.

A class member, which otherwise (without this parameter) would be documented, is excluded when it has an annotation of one of the specified types.

Each annotation type must be specified with its fully qualified name (e.g. java.lang.Deprecated). Multiple annotation type names must be separated with new lines ('\n'), semicolons (';') or colons (':'). For example:

my.core.util.Internal
my.project.api.Exclude
See Also:
DocFlex/Javadoc | Documentation | DocFlex Doclet | Handling Template Parameters | Multi-valued (List) Parameters
Suppress empty packages filter.suppressEmptyPackages : boolean

Do not document packages that contain no classes or interfaces included in the documentation scope.

Normally, Javadoc does not document empty paclages. But when filtering by tags/annotations is applied, some of the packages may become effectively empty. Yet, they will be still visible in the documentation. This parameter allows you to suppress documenting such packages.

“Pagination” parameter group

This group of parameters is related specifically to printable documentation (e.g. in RTF format).

It is available only in PlainDoc.tpl main template.

Parameter Name / Type / Description
Generate page columns page.columns : boolean

Specify whether to generate page number columns in summary tables.

Page numbers substitute for hyperlinks in printed documentation and help to navigate it.

Start from new page page.start : boolean

This group of parameters specifies which documentation blocks should start from a new page.

It has effect only when you generate RTF documentation.

Table Of Contents

page.start.toc : boolean

Specify whether the Table Of Contents should start from a new page.

See Also:

Generate | Table Of Contents” parameter

Overview

page.start.overview : boolean

Specify whether the documentation Overview should start from a new page.

See Also:

Generate | Overview” parameter

All Classes Summary

page.start.overview.allClasses : boolean

Specify whether the All Classes Summary should start from a new page.

See Also:

Generate | Overview | All Classes Summary” parameter

Package Overviews

page.start.package : boolean

Specify whether each Package Overview should start from a new page.

See Also:

Generate | Package Overviews” parameter

Class Detail

page.start.class : boolean

Specify whether each class documentation should started from a new page.

See Also:

Generate | Class Detail” parameter


Copyright© 2003-2012 Filigris Works, Leonid Rudy Softwareprodukte. All rights reserved.
To contact us, please visit www.filigris.com or e-mail to: contact@filigris.com