CompilationUnit
	/**
	 * Finds the corresponding AST node in the given compilation unit from 
	 * which the given binding originated. Returns <code>null</code> if the
	 * binding does not correspond to any node in this compilation unit.
	 *
	 * This method always returns
	 * <code>null</code> when the binding object comes from a different AST.
	 * 
	 * @param instance the binding
	 * @return the corresponding node where the given binding is declared,
	 * or <code>null</code> if the binding does not correspond to a node in this
	 * compilation unit or if bindings were not requested when this AST was built
	 * @see #findDeclaringNode(String)
	 */
	public ASTNode findDeclaringNode(IAnnotationInstance instance) {
		return this.ast.getBindingResolver().findDeclaringNode(instance);
	}

// seems like a heavy operation; only works if bindings asked for
// do we have precedent?



// missing spec
Annotation
 public IAnnotationInstance resolveAnnotation()
	{ return this.ast.getBindingResolver().resolveAnnotation(this); }


/**
 * Represents an instance of JSR 175 Annotation.
 */
public interface IAnnotationInstance 
{
	/**
	 * Type of the annotation, which will always
	 * return <code>true</code>	to <code>ITypeBinding.isAnnotation()</code>
	 * @return the type of the annotation.
	 */
	ITypeBinding getAnnotationType();
	
	/**
	 * @return the array of declared element value pair of the annotation.
	 */
	IElementValuePair[] getDeclaredElementValuePairs();
}

// should not be public (not API)
public class AnnotationInstance implements IAnnotationInstance
	

/**
 * Represents an element value pair of an 175 Annotation instance.
 */
public interface IElementValuePair 
{
	/**
	 * @return the name of the member
	 */
	public String getName();
	
	/**
	 * @return the method binding that defines this element value pair.
	 */
	public IMethodBinding getMethodBinding();
	
	/**
	 * This will determine the type of object returned in the {@link #getElementValue()}
	 * @return the type of the element value.
	 * 
	 */
	public ITypeBinding getElementType();
	
	/**
	 * If {@link #getElementType()} returns a primitive type, the result is the box 
	 * equivalent. (i.e. <code>Integer</code> for type "int").
	 * Return <code>String</code> if {@link #getElementType()} returns type <code>String</code>
	 * Return {@link ITypeBinding} if {@link #getElementType()} returns type <code>Class</code>
	 * Return {@link IVariableBinding} if {@link #getElementType()} returns an enum type.
	 * Return {@link IAnnotationInstance} if {@link #getElementType()} returns an annotation type.
	 * Return an <code>Object</code> array if {@link #getElementType()} returns an array type. 
	 * 	
	 * @return the compile-time constant of this element or null if none exists.
	 *         Return null if bindings are not requested when the DOM/AST is built.
	 */
	public Object getElementValue();
	
}

// should not be public (not API)
public class ElementValuePair implements IElementValuePair

IMethodBinding
	/**
	 * Return the annotations annotating this method/constructor.
	 * The behavior of this API is the same regardless of whether 
	 * this is a parameterized method or not.
	 * 
	 * @return the annotations annotating this method/costructor.
	 */
	public IAnnotationInstance[] getAnnotations();
	
	/**
	 * Return the annotations of a parameter of this method.
	 * The behavior of this API is the same regardless of whether 
	 * this is a parameterized method or not.
	 * 
	 * @param paramIndex the index of the parameter of interest.
	 * @return the annotations of the <code>paramIndex</code>th parameter
	 * @throws ArrayIndexOutOfBoundsException if <code>paramIndex</code> is 
	 * not a valid index. 
	 */
	public IAnnotationInstance[] getParameterAnnotations(int paramIndex);

	/**
	 * Return whether this binding is for an annotation method.
	 * 
	 * @return <code>true</code> iff this is the binding for an annotation method 
	 *         and <code>false</code> otherwise.
	 */
	public boolean isAnnotationMethod();

	/**
	 * Return the default value of an annotation method, iff this method
	 * binding represents an annotation method that has a default value.
	 * Return <code>null</code> otherwise.
	 * 
	 * 
	 * If the type of the value is a primitive type, the result is the boxed equivalent 
	 * (i.e., int returned as an <code>Integer</code>). If the type of the value is
	 * <code>String</code>, the result is the string itself. If the type of the value 
	 * is an enum type, <code>IVariableBinding</code> is returned. If the type of the
	 * value is an annotation type, <code>IAnnotationInstance</code> is returned. 
	 * If the type of the value is an array, then an one-dimensional array will be
	 * returned. If there are not defaulta value, the result is <code>null</code>.
	 * 	
	 * 
	 * @return the default value of an annotation method. Return <code>null</code>
	 * if one does not exist or if this binding is not an annotation method binding.
	 * This will also return <code>null</code> if no binding information is requested
	 * when this DOM/AST is built.
	 * 
	 */
	public Object getDefaultValue();


ITypeBinding
	/**
	 * Return the annotations iff one of {@link #isAnnotation()}, {@link #isEnum},
	 * {@link #isClass} or {@link #isInterface()} returns <code>true</code>.
	 * Return null otherwise.
	 * 
	 * @return the annotations annotating the type if it is a reference type.
	 * Return null otherwise.
	 * @see #isAnnotation()
	 * @see #isEnum()
	 * @see #isClass()
	 * @see #isInterface()
	 * @since 3.1
	 */
	public IAnnotationInstance[] getAnnotations();


IVariableBinding	
	/**
	 * Return the annotations annotating this variable if {@link #isField()} or
	 * {@link #isEnumConstant()} return <code>true</code> or this binding 
	 * is a parameter.
	 * If this is a field, the behavior of this API is the same regardless of whether 
	 * it is parameterized or not.
	 *  
	 * @return the annotations of this variable iff it is a field, an enum constant 
	 * or an parameter. Return <code>null</code> otherwise.
	 * @see #isEnumConstant()
	 * @see #isField()
	 * @since 3.1
	 */
	public IAnnotationInstance[] getAnnotations();

// issue return empty array instead of null



====================================
Theodora, I've reviewed the DOM API portion of the patch. I believe the proposed API additions will
give client the access they need to annotation. I have some suggested renamings and minor improvements. 


public interface IResolvedAnnotation
  ITypeBinding getAnnotationType();
  IResolvedMemberValuePair[] getDeclaredMemberValuePairs();
  IResolvedMemberValuePair[] getAllMemberValuePairs();
- rename from IAnnotationInstance
 to suggest it is resolved info like bindings 

- add getAllMemberValuePairs to return implicit defaulted pairs as well


public interface IResolvedMemberValuePair 
  public String getName();
  public IMethodBinding getMemberBinding();
  public Object getValue();
- rename from IElementValuePair to suggest it is resolved info like bindings 
- rename getElementValue -> getValue for consistency with MemberValuePair.getValue
- rename getMethodBinding -> getMemberBinding
- delete getElementType; unnecessary; client can do getMemberBinding().getResultType()

Annotation
  public IResolvedAnnotation resolveAnnotation();
CompilationUnit
  public ASTNode findDeclaringNode(IResolvedAnnotation resolvedAnnotation) {
- fine as proposed

IBinding
  public IResolvedAnnotation[] getAnnotations();
- pull method up from ITypeBinding, IVariableBinding, IMethodBinding so that package annotations are exposed as well
- change spec to return empty list rather than null, to make it more convenient for clients


IMethodBinding
  public IResolvedAnnotation[] getParameterAnnotations(int paramIndex);
  public boolean isAnnotationMember();
  public Object getDefaultValue();
- rename 
isAnnotationMethod -> isAnnotationMember
 for greater consistency (
the node type is named AnnotationTypeMember)



I'm attaching a patch for the o.e.jdt.core/dom subtree only (APT branch)
 with fleshed out specs for everything. 


Some of the other things I noticed
- all new API must be tagged with @since and have full specs.
I didn't know what Philippe and you have discussed, so I marked all the new
classes and method 
@since 3.2 on the assumption that they will appear only on 3.2.
- since there is new API involved, the test suites will need to be upgraded as well to include
comprehensive tests for the new API elements
- the implementation classes AnnotationInstance and ElementValuePair are public; since these
are not intended to be exposed as API, then should to be package-private
- it would help if the code formatting followed the same conventions used elsewhere in the code

=================

ITypeBinding
IMethodBinding
IVariableBinding
public IAnnotationInstance[] getAnnotations();
- needs to cover package bindings as well, which also carry annotations
- move method up to IBinding
- should never return null; empty list is better


public class AnnotationInstance implements AnnotationInstance 
public class ElementValuePair implements IElementValuePair
- neither of these are intented to be API classes
- should not be public


IMethodBinding
public boolean isAnnotationMethod();
- JLS3 terminology is annotation type member
- rename to isAnnotationTypeMember


IElementValuePair
- structural node is called MemberValuePair

public IMethodBinding getMethodBinding();
- rename to getAnnotationTypeMemberBinding



- new API requires new test suites