Java Documentation: What is meaning of 'methods inherited from interface X

Question

I must be missing some basic Java terminology here:

Classes can be extended, therefore their methods can be inherited by their sub-classes.

Inte

Answer 1

I guess you are referring to the statements like this from the generated JavaDoc HTML:

Methods inherited from interface java.util.Set ...

Inheritance in this sense means that the signature of the methods in question is inherited, but not necessarily the implementation. The reason for that is simple: In Java you usually do not look into the implementations of third party code, but only into the interfaces with their signatures and JavaDoc.

So, basically, the signatures of those methods are inherited from interface Set and implemented in the HashSet or AbstractSet. Hence, actually it is implementing the interface Set.

---

Sidenote: In Java 8, you can have Interfaces implementing methods, but that's a different story.

Answer 2

I think this has more to do with the javadoc than with the language. In Java, all the methods in the interface have to be implemented. So from a language standpoint, there's no real difference betwen add and addAll. Both are declared in Set; HashSet is a concrete class; therefore it must provide an implementation for both.

The difference really just has to do with whether the author had anything to add to the javadoc in the interface. For add, it's necessary to add javadoc to HashSet, because Set defines add as an optional operation (it could be implemented by throwing an exception), therefore HashSet needs to specify that add actually does something useful. For addAll, however, there's no need to add any documentation in HashSet that wasn't already in Set's javadoc.

So I think that the javadoc page is slightly inaccurate; it really should say that the "javadoc" is inherited from Set, not the methods. (Technically, the methods aren't inherited, because an abstract method from an interface isn't inherited if there's another method with the same signature--see JLS 8.4.8. That applies equally to all methods declared in the interface, whether or not the javadoc says they're "inherited".) However, saying "Documentation inherited from class java.util.Set" might look a little odd to readers. So I'm OK with a slight technical inaccuracy here if it conveys the message adequately. Most readers wouldn't notice the inaccuracy, and it really doesn't matter. In fact, I didn't notice this little flaw in the javadoc until you posted this question--and I'm someone who used to work on a compiler for a different language and spent many hours reading the language standard and delving into the exact definitions of the terms so that I could find out exactly what the standard required.