clarification on docs of Class#getInterfaces() and Class#getGenericInterfaces() needed?

[Jochen Theodorou]

Hi,


hoping I will not annoy anyway asking this here I was wondering about 
how to interpret the javadoc of these methods correctly.

You basically find this sentence for Class#getInterfaces() and 
Class#getGenericInterfaces() "If this object represents a class, the 
return value is an array containing objects representing all interfaces 
implemented by the class."

The problem is that wording of "all". When I look at for example 
AbstractList, then all means to me more than just List (which is what is 
returned for AbstractList.class.getInterfaces()).

Furthermore, since the wording is so equal you would assume that 
getInterfaces() and getGenericInterfaces() will always return the same 
interfaces, in the same order, same length, only one generified, the 
other not. But this is only true for classes produced by the java 
compiler. getInterfaces seems to read what is produced from "implements 
part" in bytecode, while getGenericinterfaces uses the signature. There 
seems to be nothing forbidding a different order or even a different 
number.

The example, that did bring me to this is 
scala.runtime.AbstractPartialFunction from Scala 2.10.2 (other versions 
I did not check). While the implements part says only PartialFunction, 
the generics signature contains Function1 as well. Since PartialFunction 
implements Function1 there should be no real problem with that, unless 
you wrote code like me, that did depend on the two methods returning 
more or less the same.

While much shorter the javadoc used in Android is for me much more 
clear: 
http://developer.android.com/reference/java/lang/Class.html#getInterfaces%28%29
"""
Returns an array of Class objects that match the interfaces in the 
implements declaration of the class represented by this Class. The order 
of the elements in the array is identical to the order in the original 
class declaration. If the class does not implement any interfaces, an 
empty array is returned.
"""

I won't say this will prevent the mistake I made, but at least it will 
prevent the assumption *all* interfaces are to be shown here.

All in all I find it quite difficult to phrase this to not awake 
assumptions like that, without especially mentioning it. But anyway... 
should the javadoc be changed?

bye Jochen