JDK-4652836 : REGRESSION: Javadoc links to our classes being displayed as text
  • Type: Bug
  • Component: tools
  • Sub-Component: javadoc(tool)
  • Affected Version: 1.4.0
  • Priority: P3
  • Status: Closed
  • Resolution: Duplicate
  • OS: linux
  • CPU: x86
  • Submitted: 2002-03-14
  • Updated: 2014-05-05
  • Resolved: 2002-03-30
Related Reports
Duplicate :  
Description

Name: nt126004			Date: 03/14/2002


FULL PRODUCT VERSION :
java version "1.4.0"
Java(TM) 2 Runtime Environment, Standard Edition (build 1.4.0-b92)
Java HotSpot(TM) Client VM (build 1.4.0-b92, mixed mode)

FULL OPERATING SYSTEM VERSION :

glibc-2.2.4-19.3

Linux comet 2.4.9-21 #1 Thu Jan 17 14:16:30 EST 2002 i686
unknown

redhat-release

ADDITIONAL OPERATING SYSTEMS :

-

A DESCRIPTION OF THE PROBLEM :
When we run the javadoc utility released with the Java2 SDK
version 1.4, the links to our classes are being shown as
text entries instead of a link to another Javadoc document
which contains information on the class, e.g.

Return type                  | Method name                      

com.aepona.pcp.HeartBeatBean | enableHeartBeat(int duration)    
                                  This method ....
com.aepona.pcp.HeartBeatBean | getHeartBeatBean()
                                  This method ....
com.aepona.pcp.HeartBeatMgr  | getHeartBeatMgmtBean()
                                  This method
....                 String  | toString()
                                  Returns a string rep ....

Javadocs for com.aepona.pcp.HeartBeatBean and
com.aepona.pcp.HeartBeatMgr were generated during the run of
the Javadoc utility, but links to them were not present.

The files with the missing links are included in both the
-sourcepath and the -classpath so it is not a matter that
the tool can not find them.  Also, this only seemed to start
to occur when we switched to Java version 1.4.  We used to
use Java version "1.3.1_01" and the javadoc utility did not
exhibit this problem.

REGRESSION.  Last worked in version 1.3.1

STEPS TO FOLLOW TO REPRODUCE THE PROBLEM :
The javadoc command we ran was as follows:

javadocCreate:
        $(JAVADOC1.4)         -sourcepath $(TEMP_PCP_SOURCE_DIR)         -classpath $(CORBA_CLASSPATH_STUFF)         -public -version -use -d $(PCP_EXTERNAL_HTML)         -link http://java.sun.com/j2se/1.3/docs/api         -windowtitle "AePONA Javadoc for Causeway"         -doctitle "<h1>AePONA  Javadoc for Causeway</h1>         $(JAVADOC_GROUPS_AND_PACKAGES)         `cat $(TEMP_PCP_SOURCE_DIR)/workfile2`

$(TEMP_PCP_SOURCE_DIR) is the location were our source code
was located and contained source code including javadoc
comments for both com.aepona.pcp.HeartBeatBean and
com.aepona.pcp.HeartBeatMgr.

$(CORBA_CLASSPATH_STUFF) contained all the required
classpaths for our project.

$(JAVADOC_GROUPS_AND_PACKAGES) contained a list of packages
we wanted to javadoc.

$(TEMP_PCP_SOURCE_DIR)/workfile2 contained a list of our
source files we wanted to javadoc.

EXPECTED VERSUS ACTUAL BEHAVIOR :
What we got was:

com.aepona.pcp.HeartBeatBean | enableHeartBeat(int duration)
                                 This method ....
com.aepona.pcp.HeartBeatBean | getHeartBeatBean()
                                 This method ....
com.aepona.pcp.HeartBeatMgr  | getHeartBeatMgmtBean()
                                 This method
.... 
                     String  | toString()
                                  Returns a string rep ....

What we expected was:
               HeartBeatBean | enableHeartBeat(int duration)
                                 This method ....
               HeartBeatBean | getHeartBeatBean()
                                 This method ....
               HeartBeatMgr  | getHeartBeatMgmtBean()
                                 This method
.... 
                     String  | toString()
                                 Returns a string rep ....

Where HeartBeatBean and HeartBeatMgr were links to other
javadoc documentation representing these classes instead of
text describing in which package they were located.

This bug can be reproduced always.

---------- BEGIN SOURCE ----------
This is just an example of the source code for the above problem.  Everything in
out project compiles successfully.

    /**
     *  This method is invoked by the client application to request the
     *  Framework to begin heartbeat supervision of the client.
     *
     *@param  duration                   The duration in milliseconds between
     *      the heartbeats.
     *@exception  PcpTpGeneralException  If the Framework provider throws a
     *      TpGeneralException.
     *@exception  PcpTpFWException       If the Framework provider throws a
     *      TpFWException.
     *@exception  PcpInternalException   If an exception occurs within the PCP
     *      internals.
     *@exception  PlatformException      If a communication error occurs.
     */
    public HeartBeatBean enableHeartBeat(int duration) throws
	    PcpTpGeneralException,
            PcpTpFWException,
            PlatformException,
            PcpInternalException {
            
        ....
        ....
	return m_heartBeatBean;
    }
---------- END SOURCE ----------

Release Regression From : 1.3.1
The above release value was the last known release where this 
bug was known to work. Since then there has been a regression.

(Review ID: 139827) 
======================================================================

Comments
EVALUATION Doug Kramer wrote to the submitter: > Thank you for submitting this bug. We need some more information. > > Are the classes HeartBeatBean and HeartBeatMgr (that are missing links) > being passed into the javadoc command? That is, are they included > in the JAVADOC_GROUPS_AND_PACKAGES environment variable? Reply: Yes, they are being passed into the javadoc command, although not via JAVADOC_GROUPS_AND_PACKAGES. They are being passed into the javadoc command in the file $(TEMP_PCP_SOURCE_DIR)/workfile2. This file contains a list of files that I wish to javadoc in addition to those listed in JAVADOC_GROUPS_AND_PACKAGES. One point to note is that javadoc is creating javadoc documentation for HeartBeatBean and HeartBeatMgr. The only problem is that the links are being displayed as text. Yes, the classes HeartBeatBean and HeartBeatMgr are being passed into the javadoc command. They are included in the TEMP_PCP_SOURCE_DIR environment variable... I also tried including the path to the source via the -classpath entry, although this did not work either i.e. I included TEMP_PCP_SOURCE_DIR in the -classpath entry. > If not passed in, are they referenced in any import or > declaration statements? Yes, they are being imported and used within the other classes. > Are these two classes referenced in the body of any methods? The methods used in my example should be returning objects of type HeartBeatBean or HeartBeatMgr. I only used these two classes as examples. The same problem is occurring for many other classes. > Are the paths to those classes contained in -classpath or -sourcepath? Any other questions, let me know. Thanks, Simon. ###@###.### ======================= In my opinnion, this bug is a duplicate of 4628281. This regression bug was introduced in merlin: When you document a source file instead of a package (such as c:\foo\Bar.java), the classdoc that represents Bar will return false when method "isIncluded()" is called. This is why the user reports that links are missing from the output. I think this might be a bug in the javadoc tool. I have found a way to fix this in the standard doclet (using the new ClassDocCatalog), but this might not be the right solution. I will investigate this futher by doing some testing with the javadoc tool. ###@###.### 2002-03-30
30-03-2002

PUBLIC COMMENTS This bug is a duplicate of 4628281. It will be fixed for the 1.4.1 release. ###@###.### 2002-03-30
30-03-2002