FlexDoc/Javadoc - JavadocClassic - Parameters

[.]
Generate
Include
Show
Filter Classes & Members
- By Tags
  - For packages
  - Include
  - Exclude
- By Annotations
  - For
    - active set only
    - packages
  - Include
  - Exclude
- Suppress empty packages
Pagination

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

Explicitly -- those that are marked with including tags/annotations
Implicitly -- those that are not marked with the excluding tags/annotations

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:

class C1 extends class C2
class C2 extends class C3
class C3 contains a public method m() -- which is supposed to be documented

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:

class C1 extends class C2
class C2 implements interface I
class C2 contains a private field F
interface I contains a public field F -- which might be documented

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<V> {
  ...
  public void mmm (V param);
}

and 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 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: FlexDoc/Javadoc \| Documentation \| FlexDoc 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: The class has one of the specified tags. 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: 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. The member's class has one of the specified tags. 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: FlexDoc/Javadoc \| Documentation \| FlexDoc 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: FlexDoc/Javadoc \| Documentation \| FlexDoc 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. 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: FlexDoc/Javadoc \| Documentation \| FlexDoc 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: The class has one of the specified tags. 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: The member has one of the specified tags. The member's class has one of the specified tags. 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: FlexDoc/Javadoc \| Documentation \| FlexDoc 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: The class has one of the specified tags. 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: FlexDoc/Javadoc \| Documentation \| FlexDoc 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: FlexDoc/Javadoc \| Documentation \| FlexDoc 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: FlexDoc/Javadoc \| Documentation \| FlexDoc 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: The class has an annotation of one of the specified types. 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: 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. The member's class has an annotation of one of the specified types. 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: FlexDoc/Javadoc \| Documentation \| FlexDoc 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: FlexDoc/Javadoc \| Documentation \| FlexDoc 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. 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: FlexDoc/Javadoc \| Documentation \| FlexDoc 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: The class has an annotation of one of the specified types. 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: The member has an annotation of one of the specified types. The member's class has an annotation of one of the specified types. 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: FlexDoc/Javadoc \| Documentation \| FlexDoc 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: The class has an annotation of one of the specified types. 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: FlexDoc/Javadoc \| Documentation \| FlexDoc 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: FlexDoc/Javadoc \| Documentation \| FlexDoc 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.