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

[elena votchennikova]

Hi Alex,

On 18.07.2013 20:38, Alex Buckley wrote:
> 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.
I've not proposed rearrange the documentation, I'm sorry if it looks so.
I've asked you about the reasons why getDeclaredXXX methods were placed 
in j.l.r.AnnotatedElement and not in j.l.Class, for better 
understanding. And if I understand your previous letter correct - this 
is because of historical reasons. Ok.


Thanks a lot for your answer,
Elena

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