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