Name: gm110360 Date: 09/22/2004


FULL PRODUCT VERSION :
Java(TM) 2 Runtime Environment, Standard Edition (build 1.5.0-rc-b63)
Java HotSpot(TM) Client VM (build 1.5.0-rc-b63, mixed mode, sharing)

ADDITIONAL OS VERSION INFORMATION :
Microsoft Windows XP [Version 5.1.2600]

A DESCRIPTION OF THE PROBLEM :
Feature does not work as described in tool documentation:
"The source file for the inherited method need only be on the path specified by -sourcepath for the doc comment to actually be available to copy. Neither the class nor its package needs to be passed in on the command line. This contrasts with 1.3.x and earlier releases, where the class had to be a documented class"

I am implementing collection interfaces from the java.util package and I wish to inherit documentation from those interfaces. Documentation from classes that are being documented are inherited correctly, but documentation from classes in java.util are not being inherited. According to the tool documentation, I put src.zip in the source path, but the documentation from java.util classes will not be inherited unless I request that they are documented also.

This is a regression back to 1.3.x

STEPS TO FOLLOW TO REPRODUCE THE PROBLEM :
1. Create a class that implements java.util.Iterator.
2. Implement the next, remove, and hasNext methods without providing doc comments.
3. Run javadoc on the file, specifying the path to the custom iterator source and the path to src.zip in the -sourcepath argument.
4. Browse the generated documentation for the custom iterator class.

EXPECTED VERSUS ACTUAL BEHAVIOR :
EXPECTED -
I expected the generated documentation to contain inherited doc comments from the Iterator interface.
ACTUAL -
The generated documentation contained no inherited doc comments from the Iterator interface.

REPRODUCIBILITY :
This bug can be reproduced always.

---------- BEGIN SOURCE ----------
/*
 * Below is the source code for two class files Ex01.java and Ex02.java.
 * The class Ex02 extends Ex01 and implements the Iterator interface.
 *
 * Use the following command to document them:
 * javadoc -d dist\javadoc -sourcepath src;%JAVA_HOME%\src.zip example
 *
 * The API documentation for Ex02 will correctly inherit documentation
 * from Ex01 since that class is being documented, but documentation
 * for the methods implemented from java.util.Iterator will not be inherited.
 * This is a bug.
 */

/*
 * Ex01.java
 */
package example;

public class Ex01
{
/**
* Does absolutely nothing.
*
* @param x A value passed in.
*
* @return A value returned.
*/
public int doIt(int x) { return 0; }
}


/*
 * Ex02.java
 */
package example;

import java.util.Iterator;

public class Ex02<E>
extends Ex01
implements Iterator<E>
{
/**
* Does something.
*/
public int doIt(int x) { return x*x; }

public boolean hasNext() { return false; }

public E next() { return null; }

public void remove() {}
}

---------- END SOURCE ----------
(Incident Review ID: 310990)
======================================================================