The submitter of RFE 6429199 noticed a few problems in the documentation:
In your review you suggest the Visitor pattern as a possible solution, I was actually using the visitor pattern when I came upon the problem. I was trying to process an annotation from within Jackpot using the Jackpot extensions to the Tree API. The problem is knowing what visitors to write when you want to cover all possibilities (essemtially I want to do the same thing regardless of how the annotation is represented in the source). Another possibility is to use a type mirror, this may well be the best approach for me. The point of the RFE is to say that more documentation would be nice and as a second point I suggested using interfaces to document the Trees returned rather than Javadoc since the interfaces also provide additional functionality and most importantly can be unit tested (you can't unit test a Javadoc). To explain myself more, here is the mistake I made:
1. I looked at the documentation for getAnnotation it says "The Java Language Specification, 3rd ed, section 9.6".
2. Firstly that reference is wrong or incomplete, it should say 9.7 or say both 9.6 and 9.7. I am not sure which of these options, it isn't clear when you might encounter an AnnotationTree!
3. Section 9.7 says:
Annotation:
NormalAnnotation
MarkerAnnotation
SingleElementAnnotation
4. Which would lead one to expect the Tree API to contain NormalAnnotationTree, MarkerAnnotationTree, and SingleElementAnnotationTree. None of which are present. Infact getAnnotation returns the identifier associated with the annotation, not the annotation as described in the JLS.
The fact that getAnnotation is incorectly documented, wrong or missing JLS section, shows the weakness of using Javadocs and the power of using an interface. The interface can be unit tested, the Javadoc can't.
A further point is that referencing the JLS isn't that helpful, because the Tree API doesn't follow the notation in JLS :(
In your review you suggest the Visitor pattern as a possible solution, I was actually using the visitor pattern when I came upon the problem. I was trying to process an annotation from within Jackpot using the Jackpot extensions to the Tree API. The problem is knowing what visitors to write when you want to cover all possibilities (essemtially I want to do the same thing regardless of how the annotation is represented in the source). Another possibility is to use a type mirror, this may well be the best approach for me. The point of the RFE is to say that more documentation would be nice and as a second point I suggested using interfaces to document the Trees returned rather than Javadoc since the interfaces also provide additional functionality and most importantly can be unit tested (you can't unit test a Javadoc). To explain myself more, here is the mistake I made:
1. I looked at the documentation for getAnnotation it says "The Java Language Specification, 3rd ed, section 9.6".
2. Firstly that reference is wrong or incomplete, it should say 9.7 or say both 9.6 and 9.7. I am not sure which of these options, it isn't clear when you might encounter an AnnotationTree!
3. Section 9.7 says:
Annotation:
NormalAnnotation
MarkerAnnotation
SingleElementAnnotation
4. Which would lead one to expect the Tree API to contain NormalAnnotationTree, MarkerAnnotationTree, and SingleElementAnnotationTree. None of which are present. Infact getAnnotation returns the identifier associated with the annotation, not the annotation as described in the JLS.
The fact that getAnnotation is incorectly documented, wrong or missing JLS section, shows the weakness of using Javadocs and the power of using an interface. The interface can be unit tested, the Javadoc can't.
A further point is that referencing the JLS isn't that helpful, because the Tree API doesn't follow the notation in JLS :(
- relates to
-
JDK-6429199 Detail (document) return types for get methods, e.g. getAnnotationType
-
- Closed
-