2

My goal is to "read" the Java classes of a certain package, then to process the Javadoc and annotations (preferably at the same time) on the classes within that package and on the methods within those classes. Solution must be implemented in Java 6 or 7, build tool is Maven 3. We're currently using the maven-compiler-plugin, version 2.5.1, but I can probably upgrade that further if available/necessary.

As I understand it, the purpose of the javax.annotation.processing classes are to do this kind of thing, and I believe Java code along the lines of this other SO answer should work for my purposes, but the practical details of how to get it actually running are still a little fuzzy.

All that being said, here's what I think I need:

  1. Java code to pick out the annotations and Javadoc items that I want, and then convert those items into the data model needed to create my custom documentation.
  2. Java code to then write this data model out to a docs file or directory of files
  3. Maven 3 configuration to:
    1. Run the annotation processor once at a good time
    2. Include the generated docs directory in the outputted war file

The Maven bits trip me up more than the Java code, so if you're only going to answer half, that's the half that'll get my check mark. Also, my preference would be to not put this annotation processor into a Maven repository as a separate plugin since it will be very tightly coupled with some custom annotations we're using.

Here's a brief listing of questions that I found as related from which I could not synthesize my own answer, though:

Community
  • 1
  • 1
Patrick
  • 2,672
  • 3
  • 31
  • 47

1 Answers1

0

I'm not sure if you can access the Javadoc from annotation processors. Consider to use the Doclet API:

http://docs.oracle.com/javase/7/docs/technotes/guides/javadoc/doclet/overview.html

Edit:

Here is an annotation processor I wrote. Maybe it can serve as a sample:

http://softsmithy.hg.sourceforge.net/hgweb/softsmithy/lib/main-golden/file/ae786193023d/softsmithy-lib-core/src/main/java/org/softsmithy/lib/util/impl/ServiceProviderAnnotationProcessor.java

http://softsmithy.hg.sourceforge.net/hgweb/softsmithy/lib/main-golden/file/ae786193023d/softsmithy-lib-core/pom.xml

http://softsmithy.hg.sourceforge.net/hgweb/softsmithy/softsmithy-parent/main-golden/file/9397853ba514/pom.xml

For Maven: as far as I can remember you have to pass -proc:none as compiler argument (compiler plugin) in the project that contains the annotation processor. In that project also add the following resource file: META-INF/services/javax.annotation.processing.Processor and add the fully qualified name of your annotation processor in the first line.

I usually package the annotation, the annotation processor and this "service registry file" in the same project A. Then in any other project B where I'm using the annotation and thus have a dependency on this project A, the annotation processor is picked up automatically.

I'm using the Maven Compiler Plugin v2.3.2 and Java SE 7.

Puce
  • 37,247
  • 13
  • 80
  • 152
  • I'd seen these before, but I did not get the impression that they could handle annotations. Some of my custom documentation is going to come from web service annotations like [@Path](http://jackson.codehaus.org/javadoc/jax-rs/1.0/javax/ws/rs/Path.html) and [@Transactional](http://static.springsource.org/spring/docs/3.0.x/api/org/springframework/transaction/annotation/Transactional.html) – Patrick Sep 28 '12 at 14:45
  • 2
    I might mistake the point of [getDocComment](http://docs.oracle.com/javase/6/docs/api/javax/lang/model/util/Elements.html#getDocComment%28javax.lang.model.element.Element%29) but I think it allows me to get Javadocs while doing annotation processing – Patrick Sep 28 '12 at 14:47
  • I'd guess if an annotation has the `@Documented` annotation, then you would have access to it. (This would be the case for `@Transactional` but not for @Path). – Puce Sep 28 '12 at 14:51
  • Maybe, but it seems just as a String. Maybe you can extract the meta information of the non-documented annotations you need with a annotation processor -> write this meta data in a file -> write a doclet which reads the Javadoc and your custom meta data. But maybe there is aneasier way. – Puce Sep 28 '12 at 14:55
  • Having to process the annotations as strings wouldn't be the worst thing ever to this particular endeavor, if that's easier than writing annotation processors. I still have no idea how to rig this up to run through Maven3, though. – Patrick Sep 28 '12 at 14:58