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:
- 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 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 classC2
- class
C2
extends classC3
- class
C3
contains a public methodm()
-- which is supposed to be documented
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 classC2
- class
C2
implements interfaceI
- class
C2
contains a private fieldF
- interface
I
contains a public fieldF
-- which might be documented
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 classC1
defined like this:
-
class C1<V> { ... public void mmm (V param); }
C2
that extends C1
:
-
class C2 extends C1<String> { ... }
C1
should be excluded from the documentation,
but its method C1.mmm()
should not.
Then, showing that method like:
-
C2.mmm (V param)
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)
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:
-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) |
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 (
* ).
The asterisk is a wildcard meaning “match any characters”. This is the only wildcard allowed.
See Also: |
|
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. |
|
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:
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:
|
|
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:
|
|
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:
|
|
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). |
|
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 multiple exclude-tag names must be separated with new lines ('\n'), semicolons (';') or colons (':'). For example:
|
|
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 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:
|
|
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:
|
|
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):
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: Now, you can use this annotation type to mark your internal classes. Here is how:
'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! |
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. |
|
filter.byAnns.for.activeSet : boolean
When this parameter is selected (
These are all classes (and packages) initially specified to Javadoc to be documented
and filtered according to the access control options
( |
|
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 (
* ).
The asterisk is a wildcard meaning “match any characters”. This is the only wildcard allowed.
See Also: |
|
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). |
|
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:
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:
|
|
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:
|
|
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:
java.lang.Deprecated ).
Multiple annotation type names must be separated with new lines ('\n'), semicolons (';') or colons (':').
For example:
|
|
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). |
|
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:
Each annotation type must be specified with its fully qualified name (e.g.
|
|
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 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.
|
|
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.
|
|
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. |