Can the Pluggable Annotation Processor API retrieve source code comments?

Question

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 {
}

score 25 · Answer 1 · edited Nov 23 '21 at 08:27

25

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);
    }
}

edited Nov 23 '21 at 08:27

Aleksandr Dubinsky

22,436
15
82
99

answered Oct 28 '11 at 17:18

basszero

29,624
9
57
79

Awesome! I was looking at the Element and Mirror classes, since I expected those to contain references to whatever comment might be on them (makes sense, right?) I had no idea about this! – G_H Oct 28 '11 at 17:24
I think in SO, the `Ask question`'s search better than just `search` ;） – Yu Jiaao Mar 07 '23 at 02:05

kapex · Answer 2 · 2011-10-28T17:22:29.510

0

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

Update: It got moved to the elements utitlity.

edited Oct 28 '11 at 17:22

answered Oct 28 '11 at 17:13

kapex

28,903
6
107
121

Except Java6 pluggable annotation API doesn't have that class. That is part of the older, more painful to configure APT suite – basszero Oct 28 '11 at 17:16
@basszero You are right. Looks like it's still available for the newer API, in the `Elements` util. – kapex Oct 28 '11 at 17:26

score 0 · Answer 3 · answered Oct 28 '11 at 17:18

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.

Can the Pluggable Annotation Processor API retrieve source code comments?

3 Answers3

Linked