JDK-4720974 : @inheritDoc broken 1.4.1 beta - inheriting from abstract superclass's interface
  • Type: Bug
  • Component: tools
  • Sub-Component: javadoc(tool)
  • Affected Version: 1.4.1
  • Priority: P3
  • Status: Resolved
  • Resolution: Fixed
  • OS: linux,windows_2000
  • CPU: x86
  • Submitted: 2002-07-25
  • Updated: 2014-05-05
  • Resolved: 2002-10-25
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
1.4.2 mantisFixed
Related Reports
Duplicate :  
Description

Name: nt126004			Date: 07/25/2002


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

FULL OPERATING SYSTEM VERSION :
Microsoft Windows 2000 [Version 5.00.2195]
SP2

A DESCRIPTION OF THE PROBLEM :
JDK1.4.1 beta 1 attempts to fix the @inheritDoc regression
in 1.4.0 but is not yet functional.  The code samples show
a method defined in an interface, an abstract class that
implements the interface, and a concrete class that extends
the abstract class.

Javadoc complains "warning - @inheritDoc used by bar
(double) does not override or implement any method".

According to my understanding of the rules, Javadoc should
find the original method declaration in the interface
implemented in the abstract class.  If the concrete class
also explicitly implements the interface, the problem goes
away...but it should not be necessary to declare that
implementation.


STEPS TO FOLLOW TO REPRODUCE THE PROBLEM :
1. Run 1.4.1-B1 Javadoc on the provided source.
2.
3.

EXPECTED VERSUS ACTUAL BEHAVIOR :
------ extracted from Javadoc html output ------

bar
public void bar(double param1)This is the Javadoc for X2.bar
().
This is the second paragraph..

This implementation over-rides X2.bar().


Specified by:
bar in interface X2
Parameters:
param1 - A double.


------------

The above is produced if ConcreteX1X2 explicitly implements
X1 and X2.

If ConcreteX1X2 does not implement the interfaces, Javadoc
produces the warning shown previously, and hangs at 100%
busy.  I am using Ant to drive the process; have not tried
Javadoc directly from the command line to see if this makes
a different on hanging the process.

REPRODUCIBILITY :
This bug can be reproduced always.

---------- BEGIN SOURCE ----------
/**
 *      This is the Javadoc for interface X1.
 */

public interface X1
{

/**
 *      This is the Javadoc for X1.foo().
 *
 *      <p>
 *      This is the second paragraph.
 *
 *      @param param1 An integer.
 */

    public void foo(int param1);
}

/**
 *      This is the Javadoc for interface X2.
 */

public interface X2
{

/**
 *      This is the Javadoc for X2.bar().
 *
 *      <p>
 *      This is the second paragraph.
 *
 *      @param param1 A double.
 */

    public void bar(double param1);
}

/**
 *      This is the Javadoc for class AbstractX1X2.
 */

public abstract class AbstractX1X2 implements X1, X2
{

/**
 *      {@inheritDoc}.
 *
 *      <p>This implementation over-rides X1.foo().
 */

    public void foo(int param1)
    {
    }
}

/**
 *      This is the Javadoc for class ConcreteX1X2.
 */

public final class ConcreteX1X2 extends AbstractX1X2 //implements X1, X2
{

/*
 *      {@inheritDoc}.
 *
 *      <p>This implementation over-rides AbstractX1X2.foo().
 *
 *      @param param1 This description takes precedence.
 */

    public void foo(int param1)
    {
    }

/**
 *      {@inheritDoc}.
 *
 *      <p>This implementation over-rides X2.bar().
 */

    public void bar(double param1)
    {
    }
}
---------- END SOURCE ----------
(Review ID: 159796) 
======================================================================

Comments
CONVERTED DATA BugTraq+ Release Management Values COMMIT TO FIX: mantis FIXED IN: mantis INTEGRATED IN: mantis mantis-b05
2004-06-14

EVALUATION Look at for Mantis. ###@###.### 2002-07-25 This bug has been fixed but is pending review. ###@###.### 2002-07-30 ###@###.### wrote: > Suppose class A implements interfaces I1 and I2, and both interfaces > specify an indentical method M. When class A implements M, does it > inherit documentation from I1.M or I2.M. Right now, it only implements > from I1.M. > It would be weird to inherit from both. How do you think we should > handle this? ###@###.### replied: I think this one has an good answer: If I1 extends (perhaps indirectly) I2, use I1's documentation. If I2 extends (perhaps indirectly) I1, use I2's documentation. If I1 and I2 are unrelated, use both (in alphabetical order). You don't have to worry about the fourth possibility, where I1 extends I2 and I2 extends I1, because cyclic inheritence is illegal.
2004-06-11

PUBLIC COMMENTS The line of code to recursivly search for {@inheritDoc} was missing in the method to replace the inline tag with the appropriate documentation. I have added it. Here is an example of where the doclet failed: Suppose class C implements interface I1 which is a subinterface of I2. If I2 has documentation for method m and both C and I1 use {@inheritDoc} to inherit documentation for m, the doclet should be able to recursively find the documentation in I2 for class C (because C implements I1 which extends I2). ###@###.### 2002-07-30
2002-07-30