FlexDoc/Javadoc - JavadocClassic - Parameters

About JavadocClassic parameters

«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:

Further Contents:

Class Filtering Effects

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

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

In that case, the generated Java API documentation will effectively refactor your actual Java implementation by 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 refactoring, because the standard Javadoc actually does it too. For instance, when you specify documenting only public classes, the package-private ones will get excluded, but the public members defined in them may show up as a 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.

Automatic extension of type variables

For example, we have a class C1 defined like this: 

class C1<V> {
  ...
  public void mmm (V param) { }
}
and a class C2 that extends C1: 

class C2 extends C1<String> {
  ...
}
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 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 ('\n') or colons (':'). For example:

com.company.project.*
org.project.*

A qualified name pattern can be any Java qualified name appropriate in the given context, or it can be the start of such a qualified name followed by an asterisk (*). The asterisk is a wildcard meaning match any characters. This is the only wildcard allowed.

Include

filter.byTags.include

This group of parameters allows you to include in the generated documentation only classes and class members, i.e.

  • fields
  • enum constants
  • constructors
  • methods
  • annotation type elements
marked with the specified tags.

classes & members

filter.byTags.include.all : list of strings

Specify tags, by which both classes and class members 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 a nested 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.

    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 a nested 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

classes

filter.byTags.include.classes : list of strings

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

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.

Notes:
  • Any inheritable member of an excluded class that 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 inclusion condition above are only necessary for a class 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

members

filter.byTags.include.members : list of strings

This parameter allows you to identify explicitly which class members 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.

Notes:
  • 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 inclusion 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

Exclude

filter.byTags.exclude

This group of parameters allows you to exclude from the generated documentation classes and class members, i.e.

  • fields
  • enum constants
  • constructors
  • methods
  • annotation type elements

classes & members

filter.byTags.exclude.all : list of strings

Specify tags by which both classes and class members 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 a nested 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 a nested 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 nested 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

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 follows. Any class that has one of the specified tags will be is excluded from the documentation.

Notes:
  • The exclusion criteria specified with this parameter affect only the class itself, but not its nested classes. They may still show up in the documentation, if they are not excluded by other criteria.
  • Any inheritable member of an excluded class that 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 declaring class.
The overall effect should be that the generated documentation will look as if the excluded classes themselves never existed at all, however, everything else is in place and correct. For more details, see the 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
Default Value:
The default value of this parameter specifies '@hidden' tag. This is the standard Javadoc tag introduced since JDK 9 to make possible the arbitrary of hiding program elements from the generated API documentation.

Along with setting it as the default value of “Filter Classes & Members | By Tags | Exclude | members” parameter, that will cause all @hidden tags to be interpretted by default in the same was as done by the Standard Doclet.

members

filter.byTags.exclude.members : list of strings

Specify tags by which only class members 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
Default Value:
The default value of this parameter specifies '@hidden' tag. This is the standard Javadoc tag introduced since JDK 9 to make possible the arbitrary hiding of program elements from the generated API documentation.

Along with setting it as the default value of “Filter Classes & Members | By Tags | Exclude | classes” parameter, that will cause all @hidden tags to be interpretted by default in the same was as done by the Standard Doclet.

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 ('\n') or colons (':'). For example:

com.company.project.*
org.project.*

A qualified name pattern can be any Java qualified name appropriate in the given context, or it can be the start of such a qualified name followed by an asterisk (*). The asterisk is a wildcard meaning match any characters. This is the only wildcard allowed.

Include

filter.byAnns.include

This group of parameters allows you to include in the generated documentation only classes and class members, i.e.

  • fields
  • enum constants
  • constructors
  • methods
  • annotation type elements
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 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 a nested 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.

    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 a nested 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

classes

filter.byAnns.include.classes : list of strings

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

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.

Notes:
  • 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 inclusion condition above are only necessary for a class 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

members

filter.byAnns.include.members : list of strings

This parameter allows you to identify explicitly which class members 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.

Notes:
  • 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

Exclude

filter.byAnns.exclude

This group of parameters allows you to exclude from the generated documentation classes and class members, i.e.

  • fields
  • enum constants
  • constructors
  • methods
  • annotation type elements
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 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 a nested 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 a nested 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 nested 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

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 follows. Any class that has one of the specified annotations will be is excluded from the documentation.

Notes:
  • The exclusion criteria specified with this parameter affect only the class itself, but not its nested classes. They may still show up in the documentation, if they are not excluded by other criteria.
  • Any inheritable member of an excluded class that 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 declaring 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 more details, see 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

members

filter.byAnns.exclude.members : list of strings

Specify annotation types by which only class members 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
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.