Name: boT120536 Date: 08/29/2001


java version "1.3.1"
Java(TM) 2 Runtime Environment, Standard Edition (build 1.3.1-b24)
Java HotSpot(TM) Client VM (build 1.3.1-b24, mixed-mode)

Suppose you wish to link to generated Javadoc from a site that forces you to
type in index.htm or index.html for the main page of it's Javadoc (i.e. it
doesn't let you just type the URL without the filename index.htm or index.html
at the end of the URL). Javadoc assumes index.htm is a directory and makes all
links underneath that directory. Both -link and -linkoffline will not work
correctly.

The -link option will fail to find the package-list file because it exists at
the same directory level as index.htm (and not inside a directory called
index.htm).

The -linkoffline option will run, but all the generated links will point to
pages underneath a directory index.htm. All the data put into the generated
Javadoc is correct (such as class, method, and attribute names), but the links
to the code are incorrect because Javadoc assumes the URL in -link or
-linkoffline does not end in a filename.

Suppose you wish to link to the JUnit Javadoc in your own code. JUnit's javadoc
code exists at:
http://www.junit.org/junit/javadoc/3.7/index.htm
You CANNOT type in the URL:
http://www.junit.org/junit/javadoc/3.7
and get the data to display because of how their site was set up. If you could,
this site would work correctly with Javadoc.

So suppose you wish to generate your Javadoc with the command:
javadoc -link http://www.junit.org/junit/javadoc/3.7/index.htm @packages

This will fail because it will be unable to locate JUnit's package-list file
which is at:
http://www.junit.org/junit/javadoc/3.7/package-list

Javadoc is trying to look for package-list at:
http://www.junit.org/junit/javadoc/3.7/index.htm/package-list



Next you try to type the command as follows:
javadoc -link http://www.junit.org/junit/javadoc/3.7 @packages

This will also fail because JUnit's Web site will not resolve that URL without
the explicit index.htm filename. So Javadoc can't find index.htm. That is not a
Javadoc flaw. I am just showing that is not an available option right now.



Next you try to work around this by trying -linkoffline.
javadoc -linkoffline http://www.junit.org/junit/javadoc/3.7/index.htm
http://www.junit.org/junit/3.7/package-list @packages

This command actually runs and generates Javadoc. But the problem is that all
the links to JUnit documentation within the Javadoc generated files are
incorrect. For instance, a link to junit.framework.Assert should be:
http://www.junit.org/junit/3.7/junit/framework/Assert.html

But is incorrectly generated as:
http://www.junit.org/junit/3.7/index.htm/junit/framework/Assert.html


So none of the JUnit links in the generated files will actually point to the
correct URL's. What needs to be done with Javadoc, is for it to look to see if
the URL in a -link or -linkoffline command is actually a file like index.htm or
index.html. If it is, it should be able to find package-list at the same
directory level in the -link command. It should also generate correct links
without the index.htm in them (except for any links to the main page, which
SHOULD retain that filename. i.e. use the filename if pointing to a filename
such as that main page which DOES require index.htm, but don't use the filename
if we are talking about the directory the files exist within.).

I have sent in a request to the site hosting JUnit's documentation, so it is
possible this situation will change. But for now at least, this is a good
example to look at as JUnit is quite a common tool to Java testing. I would
assume other sites that people may want to link their Javadoc to would also have
this situation.
(Review ID: 130694)
======================================================================