RFR: 4987375: (reflect) Class.get{Declared}Method{s} does not return clone() for array type

[Alex Buckley]

On 9/4/2013 8:30 AM, Peter Levart wrote:
> At getDeclaredMethods() the 2nd paragraph says:
>
> "If this Class object represents a type that has multiple declared
> methods with the same name and parameter types, but different return
> types, then the returned array has a Method object for each such method."
>
> I know that reflection operates on runtime class file format not on Java
> source, but for an average Java programmer this statement is confusing.
> (S)He might wonder how it is even possible to declare two methods with
> same name and parameter types, but with different return type. Of
> course, reflection also returns synthetic bridge methods that are not
> declared in source but generated by javac. How to describe that fact in
> javadoc if it only refers to JLS which doesn't know about these terms
> (or barely mentions them not describing them in full)?

Bridge methods are not widely known by Java programmers and to present 
them in this javadoc would bring confusion rather than clarity.

The declarations in a class file exposed through Core Reflection 
occasionally diverge from the declarations in source, e.g. values() and 
valueOf() methods magically in a class file for an enum type. The right 
way to deal with this - if it is to be dealt with at all - is to specify 
the divergence centrally, such as in Class's top level javadoc. 
Sprinkling "(including ...)" and "(except for ...)" clauses throughout 
the individual method specs is a recipe for inconsistency and confusion. 
I am not actually proposing anything like this be done at this time.

Alex