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

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

  xxxxx@xxxxx   2003-07-03

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.
  xxxxx@xxxxx   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

  Hangs when @inheritdoc 1) can't inherit or 2) inherits from super-superinterfaces

  xxxxx@xxxxx   2003-04-01

Bug is not reproducable.  Checking in a regression test to prove this.
  xxxxx@xxxxx   2003-10-11

What about this, exactly, is "poor commenting practice"?  I 
write javadoc much more carefully than most developers, and 
using inherited documentation is not poor practice in most 
cases, but instead keeps large projects' documentation in 
sync.  Should the javadoc be changed on every 
implementation when the javadoc for the interface changes?  
That doesn't seem realistic or even good.  What's the point 
of @inheritDoc if not to allow this sort of thing?

I strongly disagree with every point in the evaluation.

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

I believe that a re-evaluation is in order.  Hopefully one as 
hasty but less dismissive.

Thanks for following up on it, Doug!  Your efforts on resolving 
this are certainly appreciated.

One idea...Shouldn't an {@inheritDoc} of a non-existent 
comment simply act like a typical non-existent comment 
would in JavaDoc?  That is, shouldn't it be possible to inherit 
a lack of comment?

Without knowing exactly how it's implemented, it would seem 
that the fix would be as simple as a (comment != null) ? 
comment : "" line in the doclet.

Just an idea.  Might be faster to fix it than to write up the 
workaround documentation.  :)

Didn't mean to sound "dismissive".  The bug reported was:
"javadoc hangs when inheritdoc inherits from inheritdoc that
can't inherit".  ccerberus, the reference to "poor
commenting practice" was the use of
@inheritDoc to inherit from comments that cannot be inherited.
The workaround seems reasonable until we can get this bug fixed.

On the other hand, the new example of javadoc hanging when
using @inheritDoc properly is a cause of great concern, as 
there is no good workaround.

I will extend the synopsis to include the case of the
infinite loop.

-Doug Kramer
Javadoc team

>.Shouldn't an {@inheritDoc} of a non-existent comment simply
> act like a typical non-existent comment would in JavaDoc?  

Yes.  This would be an easy and important fix.  The
constraint is 
that Java 1.4.2 code was frozen when this bug was submitted
(1.4.2 
was released April 3).  The original bug had a workaround
and was 
deemed not a showstopper -- that is, not important enough to
slip 
the release of 1.4.2, thus the comment "can put off fix
until Tiger"
(1.5.0).  Unfortunately, Tiger is many months away.

-Doug Kramer
Javadoc team

another thought, is there a way to get an unofficial patch
out to people who are hitting this problem?  We just
finished a massive documentation effort and now our nightly
javadocs builds hang.  Going through 10's of thousand of
lines of comments and removing all {@inheritDoc} is a really
bad option.

This really is a showstoper.  Can we get this scheduled into
1.4.2 or 1.4.2_01 or 1.4.1_03 or something?

Ugh, this will also happen if an abstract class implements an 
interface. For example:

interface a
{
   /** Blah */
   void foo();
}

public abstract class b implmements a
{
    /** {@iheritDoc} */
    public void foo()
    {
    }

    abstract void bar();
}

public class c extends b
{
    /** {@inheritDoc} */
    public void foo()
    {
    }

    public void bar()
    {
    }
}


This will also hang. Ugh. Ugh. Ugh.