Javadoc a class implementing an external interface that isn't one you wrote the source for?

Question

If my class implements a well documented external interface from an external library(one which I haven't written), for example AttributeConverter from javax.persistence, I am wondering the proper way to document my overriding methods. Do I use @inheritDoc or a non-javadoc comment block, or simply not document at all since documentation can be found easily, what is the right way?

Answer 1

It depends on what you are trying to do. The first question you have to ask yourself is: Do I have something to add to the parents Javadoc?

If the answer is "no", this is kind of opinion based. If you just leave it out, the parents Javadoc will be used as long as you use @Override. The non-javadoc comment becomes unessecary regarding the result. It still serves it's purpose in the source code. See Should I use a "non-Javadoc" comment?

@inheritDoc is not that usefull in this case, since it only copies the element it is used on. From documentation:

Insert the inline tag {@inheritDoc} in a method main description or @return, @param or @throws tag comment -- the corresponding inherited main description or tag comment is copied into that spot.

It comes into play if you like to add something to the parents documentation. Use it to insert the parents documentation at some point in your own comment.