How can a method's Javadoc be copied into other method's Javadoc?

Question

I know that there is @inheritDoc, but it's only for methods which override others.

I have several classes with many delegate methods (which do not override others).

Can their Javadoc be "inherited" (more exactly: copied)?

/** here I need the copy of wrappedMethod's Javadoc */
public void delegateMethod(Object param){
  innerSomething.wrappedMethod(param);
}

Chiropractor

Closely related but specifically for overloaded methods: #2559195 – Fetishism

Answer 1

A @link or @see tag would be appropriate here. If you're wrapping the method, it must provide distinctive behavior which makes it unsuitable for overloading or otherwise.

Athanor

Yes, but @link or @see are sadly not useful when the wrapped method is protected :( – Chiropractor

@seanizer Oh, I didn't know that it is possible, thank you! – Chiropractor

This doesn't work for methods that have a lower visibility than what is generated for. For library writers, it is not an option to produce JavaDoc with private members for example. I would love to know a way to reuse private documentation in public API. – Delegation

@BennyBottema, you are expressing my thoughts, thank you! I am also in a situation where I am documenting a private method parsing an option string with a rather extensive Javadoc. This is where the description belongs, but several constructors pass on the option string and would need the same text too. If now I copy the text from the private method which spans more than a full screen already to one or even each of the constructors, this will just be a redundant mess and a maintenance nightmare. I don't want to increase method visibility for something only to be called by constructors. – Odontalgia

Answer 2

Sometimes it's actually a good thing to cut and paste documentation. 'Linking' documentation in some way, especially when there isn't in inheritance relationship, runs the risk that one of the methods will have it's behaviour changed somehow, making the linked documentation no longer valid.

However in the case of delegates I've had the same problem a number of times. Usually you have a public method on a main class delegating to a package-private delegate, which has exactly the same behaviour as the main method. Here the solution is simple - document the main class, and put the @link or @see on the delegate class. Everybody can see the main class' documentation. You will probably need to have more detailed documentation, such as implementation details, on the delegate class too.

Ceolaceorl