United StatesChange Country, Oracle Worldwide Web Sites Communities I am a... I want to...
Bug ID: JDK-4812240 Hangs when @inheritdoc 1) can't inherit or 2) inherits from super-superinterface
JDK-4812240 : Hangs when @inheritdoc 1) can't inherit or 2) inherits from super-superinterface

Details
Type:
Bug
Submit Date:
2003-02-03
Status:
Resolved
Updated Date:
2003-11-11
Project Name:
JDK
Resolved Date:
2003-11-11
Component:
docs
OS:
linux
Sub-Component:
doclet
CPU:
x86
Priority:
P3
Resolution:
Fixed
Affected Versions:
1.4.1
Fixed Versions:
5.0 (b28)

Related Reports

Sub Tasks

Description
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.

======================================================================
CASE 1

FULL PRODUCT 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

ADDITIONAL OPERATING SYSTEMS :
The bug probably is independent of the operating system

A DESCRIPTION OF THE PROBLEM :
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.

STEPS TO FOLLOW TO REPRODUCE THE PROBLEM :
1. Type in source code examples below
2. javadoc *.java

EXPECTED VERSUS ACTUAL BEHAVIOR :
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

ERROR MESSAGES/STACK TRACES THAT OCCUR :
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*

REPRODUCIBILITY :
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 ----------

CUSTOMER WORKAROUND :
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) 

======================================================================
CASE 2

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: 
http://developer.java.sun.com/developer/bugParade/bugs/472
0974.html ).

                                    

Comments
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
                                     
2003-04-01
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
                                     
2003-07-03
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
                                     
2003-10-11
CONVERTED DATA

BugTraq+ Release Management Values

COMMIT TO FIX:
tiger
tiger-beta

FIXED IN:
tiger
tiger-beta

INTEGRATED IN:
tiger-b28
tiger-beta


                                     
2004-06-14



Hardware and Software, Engineered to Work Together