Need to look more closely at just what the problem is.
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
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.
> 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.
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.
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.)
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
@link does not link to external -link'd classes unless they are imported