Retain only javadoc from classes that have the @RetainJavadoc or some other annotation

[jhameier]

So things have been working fairly well and of course like most development work there is feature creep. I've been asked to run the javadoc reader as a maven plugin. I thought okay shouldn't be that big of a deal, moved the reader and markdown generation code to a new project and included the primary jar with the have the generated json files). So far so good.

Then I realized that I'm getting a json file for every class within the primary jar. With 6000+ classes at 2K each that is quite a bit more data that is not really needed in our jar at runtime since the document is getting created and that is what I need not the javadoc itself. Yea I know its an edge case.

What I really need is a way to specify only the classes that are either marked with the @RetainJavadcoc (which is currently about 100 classes in dozens of packages) or a way to specify a different Annotation to pass to a filter for the annotation processor to use. It doesn't seem right to pass it to the PackageFilter as the name implies its to filter packages.

Looking through the code I see that if I use the -A when compiling that I can specify specific packages but by default it includes everything.

1) Is there a way to specify NO packages (this way at worse case I add the @RetainJavadoc annotation to the classes I want to retain.

2) Is there a way (or could there be) a way to specify different annotations for retention (that would allow me to use existing annotations as a kind of filter for which classes I would generate for). This one is a long shot but have to ask anyway.

Thanks in advance!

[dnault]

Hi John,

Is there a way to specify NO packages (this way at worse case I add the @RetainJavadoc annotation to the classes I want to retain.

Sure, you can pass a bogus package name like -Ajavadoc.packages=none (there's nothing special about the value "none" -- it's just a top-level package that doesn't exist).

Alternatively, if you don't need the Javadoc once you've create your markdown, maybe you could strip all of the Javadoc JSON files from the JAR?

Is there a way (or could there be) a way to specify different annotations for retention (that would allow me to use existing annotations as a kind of filter for which classes I would generate for).

I'm not positive, but I think you can use @RetainJavadoc as a meta-annotation. That is, you could annotate your classes with @Foo, and annotate @Foo with @RetainJavadoc, instead of directly annotating your classes with @RetainJavadoc. I know this isn't exactly what you're looking for, but it's a way to minimize the intrusiveness. I'm also pretty sure the search for the RetainJavadoc as a meta-annotation is not recursive -- Each annotation you want to use to indicate retention would have to be directly annotated with RetainJavadoc.

Do these ideas work for your situation?

[jhameier]

Those could certainly be work arounds for this project. I will take a look at this and let you know but it certainly looks promising.

[jhameier]

you can pass a bogus package name like -Ajavadoc.packages=none

This works out fine. And this is an acceptable use. While its not a property it still value based and can be documented as what it is doing, so I think this is all good!

I think you can use @RetainJavadoc as a meta-annotation.

Yes this also works out nicely. I was able to reduce the jar size by almost 12 MB when including all the javadoc down to to 0.20 MB with just the optional class javadocs! Very significant savings.