Proposal to make new-in-Java-SE-8 methods on AnnotatedElement default methods

[Alex Buckley]

Semantics look good; some wording concerns below.

On 10/25/2013 1:35 AM, Joe Darcy wrote:
> Second iteration for the default method aspects of getAnnotationsByType:
>
> +     * @implSpec The default implementation first calls {@link
> +     * #getDeclaredAnnotationsByType(Class)} on the argument type. If
> +     * the returned array has size greater than zero, the array is
> +     * returned. If the returned array has size zero and this {@code
> +     * AnnotatedElement} is a class and the argument type is an
> +     * inheritable annotation, and the superclass of this {@code
> +     * AnnoatedElement} is non-null, then the result of {@code
> +     * getAnnotationsByType(annotationClass)} on the superclass is
> +     * returned. Otherwise, a zero-length array is returned.

"calls getDeclaredAnnotationsByType(Class) on the argument type" can be 
read as "executes annotationClass.getDeclaredAnnotationsByType(Class)" - 
that's how you use "on" in the penultimate sentence. Generally "argument 
type" is problematic - the type Class<T> is not especially interesting 
here. Try "calls getDeclaredAnnotationsByType(Class) passing the 
annotationClass argument."

"and annotationClass represents an inheritable annotation _type_, and ..."

"then the result of calling getAnnotationsByType(Class) on the 
superclass, _once again passing annotationClass,_ is returned."

> Second iteration for the default method aspects of
> getDeclaredAnnotationsByType:
>
> +     * @implSpec The default implementation may call {@link
> +     * #getDeclaredAnnotation(Class)} one or more times to find a
> +     * directly present annotation and, if the annotation type is
> +     * repeatable, to find a container annotation. If the annotation
> +     * type is both directly and indirectly present, {@link
> +     * getDeclaredAnnotations()} will get called to determine the
> +     * order of the elements in the returned array. Alternatively,
> +     * {@link getDeclaredAnnotations()} may be called a single time
> +     * and the returned array examined for both directly and
> +     * indirectly present annotations. The results of calling {@link
> +     * getDeclaredAnnotations()} are assumed to be consistent with the
> +     * results of calling {@code #getDeclaredAnnotation}

"If the annotation type is both directly and indirectly present" - 
annotations, not their types, are directly/indirectly present. Try "If 
annotations of type annotationClass are determined to be directly 
present and indirectly present, then getDeclaredAnnotations() is called 
to determine the order ..."

I think the middle part should read "Alternatively, the default 
implementation may call ..." because otherwise the remainder of the 
@implSpec is too easily read as a sub-clause of of determining the order 
of elements in the returned array.

Need a (Class) in the final @code.

Alex