Append new JavaDoc to existing from super method

Question

I have generated an Interface which is very well documented. Every method does have his own JavaDoc. The clases which implement this Interface can have little differents in their logic.

How can i add JavaDoc to the existing JavaDoc from the super class. The key word

/**
 * {@inheritDoc}
 */

only set the javaDoc of the super class to the current method. But when i try to add some words, the JavaDoc of the super method is gone, like

/**
 * {@inheritDoc}
 * These value depends on...
 */

Does anybody have a idea how i can update the JavaDoc of a super method, without deleting.

EDIT:

Regarding to Brian Agnew answer, which is good but not a real answer ;)

You also can have the same problem when you want to overwrite an existing method, like paint() in Swing, and want to describ how to initialize or handle the draw behaviour from outside. This is not only for interface description.

Answer 1

Here's a question. Should you want different Javadoc ?

That is to say, if the Javadoc is documenting the API then the interface should operate in the same fashion regardless of the type I actually insert. Should I (as the caller, or client) really worry if the implementation changes ? (The actual class documentation should perhaps have the implementation details).

See the Liskov Substitution principle (a little academic, but it says basically that you should be able to substitute different subtypes of a type without a change in the caller's perception of what's going on)

Answer 2

I don't know any direct JavaDoc idiom that does that. However Eclipse and IntelliJ will let you grab the super JDoc and insert it... it's far from perfect, as if you change the supr JDoc you will have to reedit all the overrides, but it's better than copy-paste by hand...

Answer 3

I guess that when you need to add something to javadoc, you changed something. So maybe it will be correct to write javadoc in exactly same way.

/**
 * Enahnced swing paint for my cool component
 * @see JButton.paint();
 */
public void paint(){
 super.paint(){
 //my stuff
}