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!