Why is inheritedDoc not defined on constructors?

Question

I was wondering if there is any valid reason why javadoc does not support inheritedDoc on constructors. Suppose I have

class A
{
/**
 * Constructor of A
 */
A(){}   

/**
 * Does something
 */
public void method(){}
}

class B extends A
{
/**
 * {@inheritDoc}
 */
B(){ super();}

/**
 * {@inheritDoc}
 */
public void method(){}
}

For the method method, I could inherit the javadoc, but why the same cannot be applied for constructors? The javadoc does not get inherited unless I use the inheritDoc tag, which means I am well aware that I would want to reuse the documentation. What should prevent me from doing so for the constructors?

A "what to do instead" version: http://stackoverflow.com/questions/14402275/javadoc-inheriting-parent-constructors-documentation — Ciro Santilli OurBigBook.com, Feb 09 '15 at 13:38
Likely the same reason why constructors are not inherited: http://stackoverflow.com/questions/1644317/java-constructor-inheritance — Ciro Santilli OurBigBook.com, Feb 12 '15 at 15:49

score 16 · Accepted Answer · answered Feb 13 '13 at 08:11

What should prevent me from doing so for the constructors?

Presumably the fact that constructors aren't inherited. While they often end up having the same parameters (with the same meaning) as the constructors in the superclass, it's not nearly such a clear relationship as it is with methods.

I can see the practical value, but equally I can see why something that isn't actually inherited shouldn't have @inheritDoc available. It would be nice if you could specifically inherit bits of documentation - for example, if you're going to pass a parameter value directly to the superclass constructor, it would be nice to be able to effectively link to that documentation...

score 11 · Answer 2 · answered Mar 10 '14 at 15:44

I like to use the following notation to address this issue:

public class TestReflectionHelper extends TestReflectionHelperCommon {

    /**
     * @see TestReflectionHelperCommon#TestReflectionHelperCommon()
     */
    public TestReflectionHelper() {
        super();
    }

    /**
     * @see TestReflectionHelperCommon#TestReflectionHelperCommon(Class, String,
     *      Class...)
     */
    public TestReflectionHelper(final Class<?> targetClass,
            final String targetMethod, final Class<?>... parameterTypes) {
        super(targetClass, targetMethod, parameterTypes);
    }

    ...
}

score 7 · Answer 3 · answered Feb 13 '13 at 08:11

Well, it's not a great reason, but this is my understanding:

If you implement an interface or override a method, you are effectively implementing something that was described elsewhere (in the interface or superclass) and there's a good chance you don't have anything to add to the previous description, so you get the @inheritDoc tool that let's you just reuse that text (and still add to it if you want).

A constructor, on the other hand, is a different animal: if it's creating an implementation of an interface, there must be a reason that that implementation is different from another one. If you are creating an inheriting class, there must be something you are adding to the parent class.

Oh, by the way, there's a feature request from 2003 on this ;)

On the same grounds, if I am overriding a method, there must be something that I am adding(or modifying) to the parent class method's behavior. But then I still got `@inheritedDoc` available for the overridden method. — Shiva Kumar, Feb 13 '13 at 08:25
@ShivaKumar I started saying it wasn't a very good reason ;) JonSkeet makes a more white and black distinction: constructors are not inherited, end of story — Miquel, Feb 13 '13 at 08:28

score 5 · Answer 4 · edited May 23 '17 at 11:46

This is just a limitation of JavaDoc. Like Miquel pointed out, there is a feature request for it, but in 10 years nobody has bothered to implement it. Pure lazyness, I say.

Because constructors aren't inherited in Java you are forced into duplicating the constructor in subclass. That's quite enough of duplication already, but now because of JavaDoc you are also forced to duplicate the documentation.

A good documentation tool should help you in eliminating duplication, just like a good programming language.

Why is inheritedDoc not defined on constructors?

4 Answers4