Use annotation to specify which classes/interfaces should be generate javadoc?

Question

Hi,

I have a java program and want to generate javadoc for classes/interfaces. However, I just want to generate javadoc for a certain classes and interfaces. I just want to know if there is any way that I can add an annotation at the beginning of each class/interface to indicate that this class/interface should not be generated javadoc (something like @no-generate-javadoc)

Does anyone have ideas, please?

Thanks

Answer 1

Writing your own doclet is realtively straightforward and will give you exactly what you want. You can still delegate to the standard doclet, so your implementation only needs to include your specific changes.

The ExcludeDoclet would be a good starting point. It reads excluded classes from a file. You get excludes by annotation by calling the annotations() method on ClassDoc (actually it's base class, ProgramElementDoc) to fetch the annotations, and then check these against your desired exclude annotations. If desired, you could also do this recursively for superclasses and implemented interfaces,

Answer 2

Thanks for mentioning our tool - DocFlex/Javadoc

By the way, simply excluding classes and members isn't the whole story. The generated JavaDoc must look consistent after that.

For instance, 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 should 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).

The same situation is with fields, which is actually even more complicated, because equally named fields 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 to do 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.

Does simple tweaking (delegating) of the Standard Doclet solves such problems?

Our tool does!