Puzzling problem with Javadoc {@link}s

[jhsachs]

I’m writing Javadoc in Eclipse with JDE 1.5. I’ve encountered a puzzling problem with {@link}s.

Reducing the problem to its essentials: classes X, Y, and Z are all in the same package. Javadoc comments in classes X and Y contain {@link} tags that refer to class Z, for example:

{@link Z Z}

In class Y, these Javadoc tags trigger the error “Tag @link: reference not found: Z Z”. In class X, they compile without errors but generate text without a link. I don't see any differences between X and Y that could account for this.

If I fully qualify the reference to class name…

{@link com.xyz.several.path.components.Z Z}

…class Y compiles without errors, but still doesn’t generate a link.

In every case -- even when Javadoc says “reference not found” -- Eclipse resolves the reference correctly; for example, displaying the Javadoc comment when I float the mouse over the class name.

Any ideas what is happening?

[jhsachs]

I found the source of this problem: because I was building Javadoc one class at a time, the compiler considered all the other classes "external," even though they are in the same package. To solve this problem all I have to do is compile all of the inter-referenced classes together.

However, I'm having a problem with Eclipse which makes that very hard to do. I described it in an earlier post, but the fool forum won't let me link to it, so I'll reproduce the contents here:

Build Javadoc: remembering a selected set of source files

I'm using Eclipse 3.2.2 to add Javadoc comments to some of the source files in a fairly large package. Because many of the source files contain fragmentary or invalid comments, I want to compile Javadoc only for the ones I am working on or have finished.

The first page of the Build Javadoc wizard lets me do this by selecting the package in the left pane under "Select types for which Javadoc will be generated," then checking the source files I want to compile in the right pane.

My problem is that I can't find a way to make the wizard remember which source files I've checked. The next time I run the wizard I find just one source file checked (I think it's the last one I've edited), and I have to select the other source files all over again.

Is there a way around this?