JDK-4810216 : Allow {@inheritDoc name} for constructors
  • Type: Enhancement
  • Component: tools
  • Sub-Component: javadoc(tool)
  • Affected Version: 1.4.0,1.4.1
  • Priority: P4
  • Status: Closed
  • Resolution: Duplicate
  • OS: linux,windows_nt
  • CPU: x86
  • Submitted: 2003-01-29
  • Updated: 2020-08-31
  • Resolved: 2018-04-11
The Version table provides details related to the release that this issue/RFE will be addressed.

Unresolved : Release in which this issue/RFE will be addressed.
Resolved: Release in which this issue/RFE has been resolved.
Fixed : Release in which this issue/RFE has been fixed. The release containing this fix may be available for download as an Early Access Release or a General Availability Release.

To download the current JDK release, click here.
Other
tbd_majorResolved
Related Reports
Duplicate :  
Duplicate :  
Relates :  
Description

Name: nt126004			Date: 01/29/2003


FULL PRODUCT VERSION :
> java -version
java version "1.4.1_01"
Java(TM) 2 Runtime Environment, Standard Edition (build 1.4.1_01-b01)
Java HotSpot(TM) Client VM (build 1.4.1_01-b01, mixed mode)


FULL OPERATING SYSTEM VERSION :
> rpm --query glibc
glibc-2.2.5-164
> uname -a
Linux jupiter 2.4.19-4GB #1 Fri Sep 13 13:19:15 UTC 2002
i686 unknown

A DESCRIPTION OF THE PROBLEM :
{@inheritDoc} currently does not work on constructors. This is, of course, because constructors are not inherited. It is a feature of the Java language not to inherit constructors (as it is a feature of Perl to in fact inherit
constructors).

But sometimes, constructors are pseudo-inherited
constructors like this:

public class X {
    /** documentation */
    public X() {
    }
    /** documentation
     * @param a some parameter
     * @param b some other parameter
     */
    public X(int a, int b) {
    }
}

public class Y extends X implements Z {
    /** {@inheritDoc} */
    public X() {
        super();
    }
    /** {@inheritDoc} */
    public X(int a, int b) {
        super(a, b);
    }
}

REPRODUCIBILITY :
This bug can be reproduced always.

---------- BEGIN SOURCE ----------
public class X {
    /** documentation */
    public X() {
    }
    /** documentation
     * @param a some parameter
     * @param b some other parameter
     */
    public X(int a, int b) {
    }
}

public class Y extends X implements Z {
    /** {@inheritDoc} */
    public X() {
        super();
    }
    /** {@inheritDoc} */
    public X(int a, int b) {
        super(a, b);
    }
}
---------- END SOURCE ----------
(Review ID: 180360) 
======================================================================

Duplicate bug 4743385 has a different justification for this feature:

Sometimes one wants to imherit documentation in
constructors, especially for Exceptions (they can be many in
the system and they often have several constructors).

Could we have a tag similar to inheritDoc (or could we make
inheritDoc work with constructors (even if the name is not
adapted).

Comments
CONVERTED DATA BugTraq+ Release Management Values COMMIT TO FIX: dragon
15-08-2004

EVALUATION Doug and I have to think about this one. I don't think this is right since constructors are not inherited. If we are going to allow this inheritence, I propose that we implement a more generic solution and allow the @inheritDoc tag to accept a parameter. You can either pass no parameter and use our algorithm to inherit documentation or you can specify a place in the documentation to inherit from. So @inheritDoc would be like @link except that the parameter is optional. For example: public class X { /** documentation */ public X() { } /** documentation * @param a some parameter * @param b some other parameter */ public X(int a, int b) { } } public class Y extends X implements Z { /** {@inheritDoc X#X()} */ public X() { super(); } /** {@inheritDoc X#X(int,int)} */ public X(int a, int b) { super(a, b); } } ###@###.### 2003-01-30 Brilliant idea. Need to go to CCC on this request. Could we use "super" as a shortcut for constructors, since that is a well-defined language construct: /** {@inheritDoc super} */ How this might generalize to work with @see, or other tags? See: 4738591: Allow {@inheritDoc} to work with more tags ###@###.### 2003-09-24
24-09-2003