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
