Review request for present, directly present, etc. in core reflection javadoc

[Joe Darcy]

Hello Elena,

On 07/11/2013 04:13 AM, elena votchennikova wrote:
> Hi Joe,
>
> specifications for methods getDeclaredAnnotation(Class), 
> getDeclaredAnnotations(), getDeclaredAnnotationsByType(Class) is valid 
> and there are no contradiction (formally).
> But the following classes
> - j.l.Package
> - j.l.r.AccessibleObject
>   (re: j.l.r.Field, j.l.r.Executable, j.l.r.Method, j.l.r.Constructor)
> - j.l.r.Parameter
> can have only directly present annotation. So, I think this is strange 
> to describe in the specification cases for inherited annotations for 
> these classes, because it could mislead readers.

When managing javadoc along different points in an type hierarchy, there 
is a trade-off between making statements that are universally true in 
the parent type (listing all the special cases) so that there is only 
one copy of a method's specification and creating specialized copies of 
the specification at each location. (This is more pronounced in 
interface-only hierarchies where a method from a supertype method 
doesn't get an explicit inclusion unless it is overridden. When a class 
implements an interface, the implementation will get its own javadoc 
entry even if it is just inherited from the interface.)

The former approach offers benefits in maintainability at the risk of 
giving the user some irrelevant information for overridden methods.

For this work, the version of the specification in AnnotatedElement 
needs to have all the special cases laid out. To follow your guidance, 
there would in addition need to be

* A specialized version of the specification for j.l.Class covering 
inheritance
* Three *independently maintained* copies specialized to ignore inheritance:
     * AccessibleObject (covers Field, Method, Constructor)
     * j.l.Package
     * j.l.r.Parameter

So I don't think it is a good trade-off to go from managing 1 copy of 
the javadoc in question to managing 5 copies.

Cheers,

-Joe

>
>
> Elena
>
>
> On 10.07.2013 23:11, Joe Darcy wrote:
>> On 07/10/2013 11:29 AM, Alex Buckley wrote:
>>> Elena Votchennikova pointed out in a comment of JDK-8010679 that 
>>> classes which implement AnnotatedElement contain method 
>>> specifications copied from AnnotatedElement. I believe the following 
>>> classes need to have their method specifications updated:
>>>
>>> - j.l.Class
>>> - j.l.Package
>>> - j.l.r.AccessibleObject
>>>   (re: j.l.r.Field, j.l.r.Executable, j.l.r.Method, j.l.r.Constructor)
>>> - j.l.r.Parameter
>>
>> The specifications on the implementation classes should generally 
>> just be @inheritdoc'ed (meaning no explicit update should be needed 
>> in those files), but I'll double check.
>>
>> -Joe
>>
>