JDK-4652655 : @link does not link to external -link'd classes unless they are imported
  • Type: Bug
  • Component: tools
  • Sub-Component: javadoc(tool)
  • Affected Version: 1.4.0,1.4.1
  • Priority: P3
  • Status: Resolved
  • Resolution: Fixed
  • OS: generic,other,linux,windows_2000
  • CPU: generic,x86
  • Submitted: 2002-03-14
  • Updated: 2014-05-05
  • Resolved: 2002-09-02
The Version table provides details related to the release that this issue/RFE will be addressed.

Unresolved : Release in which this issue/RFE will be addressed.
Resolved: Release in which this issue/RFE has been resolved.
Fixed : Release in which this issue/RFE has been fixed. The release containing this fix may be available for download as an Early Access Release or a General Availability Release.

To download the current JDK release, click here.
Other
1.4.2 mantisFixed
Related Reports
Duplicate :  
Duplicate :  
Duplicate :  
Duplicate :  
Duplicate :  
Duplicate :  
Relates :  
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
CONVERTED DATA BugTraq+ Release Management Values COMMIT TO FIX: mantis mantis-b02 FIXED IN: mantis mantis-b02 INTEGRATED IN: mantis mantis-b02 mantis-b05
14-06-2004

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
15-02-2003

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