United StatesChange Country, Oracle Worldwide Web Sites Communities I am a... I want to...
JDK-4652655 : @link does not link to external -link'd classes unless they are imported

Details
Type:
Bug
Submit Date:
2002-03-14
Status:
Resolved
Updated Date:
2003-04-12
Project Name:
JDK
Resolved Date:
2002-09-02
Component:
docs
OS:
other,linux,generic,windows_2000
Sub-Component:
doclet
CPU:
x86,generic
Priority:
P3
Resolution:
Fixed
Affected Versions:
1.4.0,1.4.1
Fixed Versions:
1.4.2 (mantis)

Related Reports
Duplicate:
Duplicate:
Duplicate:
Duplicate:
Duplicate:
Duplicate:
Relates:

Sub Tasks

Description
javadoc @links to other -linked packages but still not to 
(all) contained classes (or further down methods and fields);
see below. 

If you javadoc the example already known

------------- start ------------------------
package DE.a_weinert.math;
import  DE.a_weinert.math.DecDigsIntf;

/** <b>Dezimalzahl, ziffernweise</b>. <br />
 *  <br />
 *  Objekte dieser Klasse stellen eine Dezimalzahl 
 *  blah blah ......................
 *  @author   Albrecht Weinert
 *  @version  V00.02 (11.03.2002 09:17)
 *  @see DE.a_weinert.math
 *  @see DE.a_weinert.math.Complex
 *  @see DE.a_weinert.math.CFun
 *  @see DE.a_weinert.math.SFun
 *  @see DE.a_weinert.math.DecDigsIntf
 *  @see DE.a_weinert.math.DecFormat
 */
 // bisher    V00.00 (27.10.2000 10:35) : Anfang
 //           V00.01 (03.11.2000 18:36) : Parsen nach DecDigsP
 //           V00.02 (11.03.2002 08:57) : /**
 //  
public class DecDigs implements DecDigsIntf {

//....  much code 

/** Setzen mit double. <br />
 *  <br />
 *  Diese Methode ist schneller aber etwas ungenauer (etwa auf 16
Stellen) als
 *  entsprechende Methoden beziehungsweise Konstruktoren von 
 *  {@link java.lang.Double} beziehungsweise 
 *  {@link java.math.BigDecimal}.
 *  Entsprechend schlie??t sie einen Aufruf von 
 *  {@link #roundTo roundTo}(16) 
 *  oder f??r gro??e negative Exponenten von 
 *  {@link #roundTo roundTo}(15) ein.
 */
   public void set(double d) {
// ...... and the rest

------------- End ------------------------

and all the packages with the commands  

------------- start ------------------------ 

if not exist C:\Programme\jdk\docs\aWeinertBib\nul 
     md C:\Programme\jdk\docs\aWeinertBib

PushD C:\Programme\jdk\docs\aWeinertBib

C:\Programme\jdk\docs\aWeinertBib>  if exist 
       ..\api\org\w3c\dom\Document.html goto :m1-1.4
REM Seit 1.4.x haben wir endlich XML.

C:\Programme\jdk\docs\aWeinertBib>  Javadoc -author -version 
  -protected -use -J-mx 32m -J-ms32m -link ../api -link ../jDOM   
-sourcepath D:\Weinert\javaFactory  @D:\Weinert\javaFactory\DEawDoc.list

Loading source file D:\Weinert\javaFactory\FS.java...
Loading source file D:\Weinert\javaFactory\FuR.java...
Loading source file D:\Weinert\javaFactory\KnopfGen.java...

------------- End ------------------------

you get one warning :

----------  start-----------------------------
Generating DE\a_weinert\math\DecDigs.html...
D:\Weinert\javaFactory\DE\a_weinert\math\DecDigs.java:409: warning - Tag
@link:
reference not found: java.math.BigDecimal
-----------------  end -------------------------

and the .html

----------  start-----------------------------
 <A HREF="../../../../api/java/lang/Double.html"><CODE>Double</CODE></A>
beziehungsweise 
  <CODE>java.math.BigDecimal</CODE>.
-----------------  end -------------------------

Now:

If you change

 *  {@link java.lang.Double} beziehungsweise 
 *  {@link java.math.BigDecimal}.

to the mystirious }} 

 *  {@link java.lang.Double} beziehungsweise 
 *  {@link java.math}.BigDecimal}.

you get no warnings at all 
and the .html

----------  start-----------------------------
  <A
HREF="../../../../api/java/lang/Double.html"><CODE>Double</CODE></A>
beziehungsweise 
  <A
HREF="../../../../api/java/math/package-summary.html">java.math</A>.BigDecimal}.
-----------------  end -------------------------


So, from all the stuff below, the javadoc bug that survived bta to 
final is:

javadoc can @link to -linked standard packages but not to 
(all ?!?) classes (or further down methods and fields) in them. 

That is much to my (our?) surprise as the javadoc description
promises to look only in the package lists and generate the links 
to inside blindly. So the link to BigDecimal should have been
generated (even if BigDecimal wouldn't exist, which, of course, it
does) like the link to Double.

As we see, the link to Double is done now. The beta javadoc 
failed there as well.

So, now, thats your turn.



                                    

Comments
PUBLIC COMMENTS

This bug has been fixed in Mantis (1.4.2)
###@###.### 2002-06-01
                                     
2002-06-01
EVALUATION

Need to look more closely at just what the problem is.
###@###.### 2002-03-13

Doug wrote the submitter:
> I have a few questions about the example you submitted.
> 
> Is java.math.BigDecimal referenced anywhere in an import
> statement or declaration?

No, it is not.
 
> Is java.math.BigDecimal referenced anywhere in the body
> of your methods?

No, it is not.     

The doc reference is made for the sake of the user of the package
as a hint to / comparison with other relevant classes.

I think it is polite to the user to give him a click to ALL 
mentioned and inherited classes. (Which, BTW, is lacking in many
SUN docs: Comm-Extension (very bad doc 1.0), JavaMail and so on. **) )
  
> My guess is that you do have an import or declaration
> reference to java.lang.Double somewhere (not just the primitive
> "double"), which enables this link to work.

Well, well, I know that that is the workaround (sometimes), requiring
also not to use   import blah.blah.*;   but dozens of single imports
for every class, interface, exception etc.

But 1) The referenced  packages in my example ARE in package list of the 
       externally linked doc. So it SHOULD work.
    2) It is less readable, and sometimes not translatable, if 
       you spoil your code with imports, that the COMPILER doesn't
       need.

So, I'm sorry to say, workaround or not, to my opinion,
this IS a javadoc bug. Nevertheless, javadoc is one of the finest
products in JDK and of the best features of Java.

> 
> -Doug
>  Javadoc team


PS **): This is, of course, no criticism on javadoc, but on it's 
use for extra packages by your colleagues.
I WOULD REALLY like to see something like
"If you unpack the ....doc.zip of Comm-Extensions, JavaMail or
whatever to an directory ....jdk/docs/Whatever, you get working
relative links to all other packages."

================================

I actually fixed this bug for hopper (1.4.1) but we did not have time to throughly review and test the code, so did not make it in.  Will try to have 
fix included with mantis (1.4.2) release.

###@###.### 2002-04-22

This bug has been fixed for mantis.  The doclet did not handle external class links properly because it assumed that the classdoc representing the external class would not be null.  Previous versions of Javadoc did return a non-null classdoc representing an external class, but the current version of Javadoc does return null.  The doclet now handles this.
###@###.### 2002-06-01

The documentation must now state that any class that is not imported or included
in a declaration must be fully qualified.  (We could remove this requirement
by expanding package-list to include classes.)
###@###.### 2003-01-30

Removing "REGRESSION" from the synopsis, as this fix was never released
prior to 1.4.2.  Also changed the rest of the synopsis from:
  @link does not link to external -link'd classes
to:
  @link does not link to external -link'd classes unless they are imported

###@###.### 2003-02-15
                                     
2003-02-15
CONVERTED DATA

BugTraq+ Release Management Values

COMMIT TO FIX:
mantis
mantis-b02

FIXED IN:
mantis
mantis-b02

INTEGRATED IN:
mantis
mantis-b02
mantis-b05


                                     
2004-06-14



Hardware and Software, Engineered to Work Together