A DESCRIPTION OF THE REQUEST :
In the Tree API there are many instances where a method returns a Tree. Taking the alphabetically 1st example! In:

com.sun.source.tree.Interface AnnotationTree

method:

Tree getAnnotationType();

returns a Tree. However it can only return a few of the many possible Trees. It would be helpful if it was documented, some how, what Trees where possibly returned. (In general, this would vary with Java version and knowing how this varied would be useful information.) One possibility would be via Javadoc comments. Another option would be:

Add a new method to AnnotationTree:

PossibleAnnotationTrees getAnnotation();

Where:

interface PossibleIdentifier {
  boolean isIdentifier();
  IdentifierTree getIdentifier() throws ClassCastException; // if not an Identifier
}

interface PossibleMemberSelect {
  boolean isMemberSelect();
  MemberSelectTree getMemberSelect() throws ClassCastException; // if not a MemberSelect
}

interface PossibleAnnotationTrees extends PossibleIdentifier, PossibleMemberSelect {}

The reason for composing PossibleAnnotationTrees from PossibleIdentifier and PossibleMemberSelect is so that it can be changed in the future to some other composition of PossibleXXX interfaces. Thus allowing for future changes in the Java language.

As a general comment on the Tree API: the Javadocs are minimal :(

JUSTIFICATION :
It would make the Tree API easier to use


CUSTOMER SUBMITTED WORKAROUND :
If, and this is a big if, you are good enough at the details of Java you can guess the types of Trees that are possibly returned.