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

[Alex Buckley]

Elena, getAnnotationXXX methods have been visible in Package and AccessibleObject for years. It is not a problem in practice, and it is not a meaningful conformance issue. At this point in JDK8, we need to be fixing real bugs, not rearranging documentation.

Alex

----- Original Message -----
From: elena.votchennikova at oracle.com
To: joe.darcy at oracle.com
Cc: alex.buckley at oracle.com, enhanced-metadata-spec-discuss at openjdk.java.net
Sent: Thursday, July 18, 2013 6:33:21 AM GMT -08:00 US/Canada Pacific
Subject: Re: Review request for present, directly present, etc. in core reflection javadoc

Hello Joe,

please look at my new question bellow.

On 11.07.2013 21:58, Joe Darcy wrote:
> 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.

Ok, thank you for explanation.

But maybe 'getDeclared*' methods should be placed directly in j.l.Class? 
Why these methods were placed in j.l.r.AnnotatedElement?


Thanks a lot,
Elena
(member of the JCK team)

>
> 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
>>>
>>
>