CODEWITHSUNDEEP
javaannotationscommentsmetaprogramming
basszero
basszero

Reputation: 30014

Can the Pluggable Annotation Processor API retrieve source code comments?

I am using the pluggable annotation processing api withing Java6+ to automatically create some deployment XML files. Part of these XML files contains a description of the object. The description is ALWAYS the same content as the Javadoc associated with the class itself. I could force the comment to be a field of the @Block annotation, but that duplicates the information. Is there any way during annotation processing to get the contents of the class/type comment?

In this example, I want to get "A nice description of my block" during annotation processing.

/**
* A nice description of my block
**/
@Block
public class CustomBlock {
}

Upvotes: 15

Views: 3260

Answers (3)

basszero
basszero

Reputation: 30014

I seem to always find the answer right after I post on SO.

For future reference, here is the solution

import java.util.Set;
import javax.annotation.processing.AbstractProcessor;
import javax.annotation.processing.RoundEnvironment;
import javax.lang.model.element.TypeElement;

public class CustomAnnotationProcessor extends AbstractProcessor
{
    @Override
    public boolean process(Set<? extends TypeElement> set, RoundEnvironment re)
    {
 
        // use the protected member, processingEnv
        
        String comment = processingEnv.getElementUtils().getDocComment(anyElement);
    }
}

Upvotes: 27

kapex
kapex

Reputation: 29959

There is getDocComment which sounds like it should return the comment.

Update: It got moved to the elements utitlity.

Upvotes: 1

G_H
G_H

Reputation: 12009

The annotation processing API makes use of classes in the javax.lang.model(.*) packages. These model language constructs and said models must be generated during compilation. Since a compiler is intended to ignore comments and documentation, there doesn't seem to be anything in those packages, nor did I expect there to be, that gives you access to comments/doc.

I'm not certain how the javadoc facility performs its work, maybe that can be of help.

Kapep's answer looks interesting, but do mind that it uses stuff from a com.sun.* package, which is implementation-specific. Unless you're absolutely sure that the resources offered to your annotatation processor environment are implemented using those classes and you can safely downcast from the interfaces, it's best not to use that. It'd be a brittle solution at best.

EDIT: as an aside, I'm also using custom annotations + processor to generate metadata in XML format for wiring, validation etc. And I also need descriptions. So what I do is keep the JavaDoc for programming purposes and details that might be interesting to someone directly using the class in code, while having some description key in the annotation (or a default based on class name/other annotation values if none is given) that can be used to obtain a description from some resource file. The description is intended for the "end user" and focuses on high-level stuff, not code specifics. It has the added benefit of facilitating internationalization. I'm not certain this would be of any use to you, but there's my two cents.

Upvotes: 0

Related Questions