JDK-4812240 : Hangs when @inheritdoc 1) can't inherit or 2) inherits from super-superinterface
  • Type: Bug
  • Component: tools
  • Sub-Component: javadoc(tool)
  • Affected Version: 1.4.1
  • Priority: P3
  • Status: Resolved
  • Resolution: Fixed
  • OS: linux
  • CPU: x86
  • Submitted: 2003-02-03
  • Updated: 2020-08-31
  • Resolved: 2003-11-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.
5.0 b28Fixed
Javadoc will hang under two different conditions:

1)  When @inheritDoc inherits from a method that uses @inheritDoc
    to inherit from a class whose comments are not accessible
    This can be thought of as a user-error in trying to 
    inherit from inaccessible comments, but is just as serious nonetheless.
    This is detailed as case 1 below.

2)  When @inheritDoc inherits from one interface that inherits
    comments from another interface.  This is not a user error
    (all comments are accessible).
    This is detailed as case 2 below.


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)

$ rpm --query glibc
$ uname -a
Linux jupiter 2.4.19-4GB #1 Fri Sep 13 13:19:15 UTC 2002
i686 unknown

The bug probably is independent of the operating system

In the scenario there are two classes, a super class and a
sub class.
The super class contains a method that uses {@inheritDoc}
though it does not inherit any documentation because it does
not override or implement some other method.
The sub class extends the superclass, overrides / implements
that method and also uses {@inheritDoc} in its javadoc comment.
Javadoc then hangs when trying to generate the documentation.

The problem also occurs when the method in the super class
already overrides or implements another method where the
documentation is not available because it is part of a
different framework.

1. Type in source code examples below
2. javadoc *.java

Expected result:
- An error or warning message for the superclass that it
can't inherit documentation
- a warning message for the subclass that it maybe contains
incomplete documentation because of the inheritdoc error in
the superclass

Actual result:
javadoc hangs

javadoc hangs without error message

% javadoc -verbose *.java
Loading source file SubClass.java...
[parsing started SubClass.java]
[parsing completed 239ms]
Loading source file SuperClass.java...
[parsing started SuperClass.java]
[parsing completed 1ms]
Constructing Javadoc information...
Standard Doclet version 1.4.1

[loading /net/koori.sfbay/a/v11/jdk/1.4.1/fcs/binaries/solaris-sparc/jre/lib/rt.jar(java/lang/Object.class)]
Generating constant-values.html...
Building tree for all the packages and classes...
Building index for all the packages and classes...
Generating overview-tree.html...
Generating index-all.html...
*hangs here*

This bug can be reproduced always.

---------- BEGIN SOURCE ----------
Constructed source code to reproduce problem:

public abstract class SuperClass {

    /** {@inheritDoc} */
    public abstract void someMethod();

public class SubClass extends SuperClass {

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

Snippets of source code where problem first was detected:

package com.itcqis.junit;

import junit.framework.TestCase;

public abstract class AbstractPrintStreamTestCase extends TestCase {
    /** {@inheritDoc}
     * <strong>subclasses must invoke <code>super.setUp()</code> when overriding
this method.</strong>
    public abstract void setUp();

package com.itcqis.junit;

import java.io.ByteArrayOutputStream;
import java.io.PrintStream;

public abstract class PrintStreamTestCase extends AbstractPrintStreamTestCase {
    /** {@inheritDoc} */
    public void setUp() {
        byteOut = new ByteArrayOutputStream();
        printOut = new PrintStream(byteOut);
---------- END SOURCE ----------

Strictly limit the use of {@inheritDoc} for inheriting
documentation within the project.
Know the reason why javadoc hangs and copy documentation
using copy paste by hand.
(Review ID: 180350) 


Given the following interfaces and classes, a variation of this 
bug can be reproduced that has valid commenting practice 
and is not due to user error.  The files are as follows:

-- SuperInterface.java

public interface SuperInterface {
        /** Some docs. */
        public void someMethod();

-- SubInterface.java

public interface SubInterface {
        /** Some other docs. */
        public void someOtherMethod();

-- SuperClass.java

public class SuperClass implements SubInterface {
        /** {@inheritDoc} */
        public void someMethod() { return; }

        /** {@inheritDoc} */
        public void someOtherMethod() { return; }

-- SubClass.java

public class SubClass extends SuperClass {
        /** {@inheritDoc} */
        public void someMethod() { return; }

        /** {@inheritDoc} */
        public void someOtherMethod() { return; }

---- End Files ----

If you then execute "javadoc -d docs *Class.java", the task 
will hang, or more accurately it will max out your CPU in what 
is presumably an infinite loop until the task is forcibly halted.  
I get absolutely no error message indicating that there is a 
problem or where the problem might be, although the order of 
file processing may cause this to differ (?).  Either way, the 
behavior is unacceptable and would easily be a nightmare to 
track down given a large set of source files.  The workaround 
is also highly undesirable.

This problem or a variation of it has apparently been around 
for a long time (ref: 
0974.html ).

CONVERTED DATA BugTraq+ Release Management Values COMMIT TO FIX: tiger tiger-beta FIXED IN: tiger tiger-beta INTEGRATED IN: tiger-b28 tiger-beta

PUBLIC COMMENTS This bug is no longer reproducible. The fix did not require any source changes. This fix was just adding a test to prove that the bug report is wrong. There are other test cases that can hang the doclet, but that specific case mentioned in the bug report is not one of them. ###@###.### 2003-10-11

WORK AROUND If you have @inheritDoc tags in your source code that you cannot change, your only choice is to disable the @inheritDoc tag, which you can do by adding this tag: -tag inheritDoc:X ###@###.### 2003-07-03

EVALUATION Can put off the fix for the first bug until Tiger. Although this is a hang with no helpful message, it is due to user error (actually poor commenting practice) and is not all that likely to happen. We can document it for 1.4.2. ###@###.### 2003-02-28 The second case has just been made apparent. This is important to fix ASAP, but now it's too late for 1.4.2. Changed synopsis from: javadoc hangs when inheritdoc inherits from inheritdoc that can't inherit to: Hangs when @inheritdoc 1) can't inherit or 2) inherits from super-superinterfaces ###@###.### 2003-04-01 Bug is not reproducable. Checking in a regression test to prove this. ###@###.### 2003-10-11