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

[Alex Buckley]

spelling: AnnoatedElement

Consider mentioning only the 'length' of an array, never its 'size' (or 
at least use the same term within a single @implSpec).

There's a {@code getAnnotationsByType} which is missing its (Class).

Alex

On 10/28/2013 6:22 PM, Joe Darcy wrote:
> Hi Alex,
>
> On 10/28/2013 10:19 AM, Alex Buckley wrote:
>> 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."
>
> Changed to:
>
> +     * @implSpec The default implementation first calls {@link
> +     * #getDeclaredAnnotationsByType(Class)} passing {@code
> +     * annotationClass} as the argument. 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 type,
> +     * and the superclass of this {@code AnnoatedElement} is non-null,
> +     * then the returned result is the result of calling {@code
> +     * getAnnotationsByType} on the superclass with {@code
> +     * annotationClass} as the argument. Otherwise, a zero-length
> +     * array 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.
>>
>>
>
> Changed to:
>
> +     * @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 annotations of
> +     * the annotation type {@code annotationClass} are found to be both
> +     * directly and indirectly present, then {@link
> +     * #getDeclaredAnnotations()} will get called to determine the
> +     * order of the elements in the returned array.
> +     *
> +     * <p>Alternatively, the default implementation may call {@link
> +     * #getDeclaredAnnotations()} 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 {@link #getDeclaredAnnotation(Class)}.
> +     *
>
> Thanks,
>
> -Joe