Links from tests to production classes
Our source tree has two top-level branches: one for test and the other for production classes. The package (subdirectory) structure is identical in both branches. This is, I believe a fairly common arrangement. However, it creates a problem with Javadoc that I haven't been able to solve. I want to build documentation collections separately for the two branches, so that the test and production classes aren't commingled. If I do this, I get warnings about @link references not being found wherever the documentation of a test class links to the documentation of a production class, even though they are in the same package. I've tried various solutions: "-link"*** to the production documentation, including both branches of the source tree in the source path and naming the test classes (rather than the packages) on the command line, etc. Nothing gives me the results I want.
Given how common (I believe) this organization is--to the extent that it's supported by some IDEs--I'm surprised I can't get Javadoc to do what I want. Am I missing something, or is this really not possible?
[1106 byte] By [
mbesosaa] at [2007-10-3 1:01:10]
I'm not quite sure if I get your sefup. Are you running javadoc twice -- once for each branch?
I assume you have only links from the test branch to the production branch and not the other way?
Could you run javadoc on the production branch, then run it separately on the test branch using -linkoffline to link to the already-generated HTML pages for the production branch?
> I've tried that. It doesn't work.
I assume you have the sources for one package split across two source locations. Have just tried this under Windows with jdk 1.5.0_06 and 1.4.2_10 and they both seem to allow this.
Created this class file in src1\p1\Reg.java
package p1;
public class Reg {
/**
* Does something
*/
public void doit(){
System.println("done it");
}
}
And created this class file in src2\p1\Reg2.java
package p1;
public class Reg2 extends Reg {
/**
* The main
*/
public static void main(String[] args){
new Reg2().doit();
}
}
And then ran the command:
javadoc -sourcepath "./src1;./src2" p1
I get one set of documentation that includes both classes with links between them, but no errors.
Whoops. Perhaps I should read the posts a little more carefully.
What I have given above will let you build a set of javadoc to cover both sets of classes. I would solve the original problem by building two sets of javadoc. One that covers just the production classes, and one to cover both the production and test classes.
Personally I like to keep my test classes in a separate sub-package (called test), which would just happen to allow me to generate separate javadocs if I want it.
We actually used to have our test cases in different packages. The main reason we decided to switch is that, with the test and production classes in the same packages, there is less need to violate encapsulation to allow test cases access to elements of the production classes that shouldn't otherwise be public.
Unfortunately, I guess this is one use case Javadoc just doesn't support. I could, of course, do as you suggest and generate the second documentation set with the tests AND the production classes. I was hoping to keep the clutter in both documentation sets to a minimum (not to mention the generation time).
You say -linkoffline doesn't work. Please describe what about it doesn't work. Do you not get links?
Using -linkoffline, you would end up with links from either doc to the other, without co-mingling.
Pardon, but to persist with my questioning, are you running javadoc twice, once for each branch?
Do you have only links from the test branch to the production branch and not the other way?
-Doug
