#26 Use -link for javadoc generation

[Steve Magoun]

Javadoc should be run with the -link flag so that our docs
can take advantage of the {@link} tag across projects.

As far as I can tell, there needs to be one -link tag for each
upstream project, so we may need a task to generate an
appropriate string of -link tags for each project.

The end result is that this:

* <A HREF="../../../../../../../../apps/basics/docs/javadoc/
org/sandev/basics/util/UIFormOwner.html">
* UIFormOwner</A>.

becomes this:

* {@link UIFormOwner}

which is far cleaner, easier to maintain, etc.

[Eric Parker]

Logged In: YES
user_id=452458

From what I recall, adding the link tags actually
causes javadoc to traverse those projects, making
it even slower to build. I'm also a little
nervous about letting javadoc walk around too
much, having seen some ugly dependencies happen in
the past.

Another possible approach would be to create our
own tag that works something like this:

{@sand.link apps/basics
org.sandev.basics.util.UIFormOwner}

which is verbose, but fairly clear. That would
avoid javadoc traversal.

We could probably even figure out how to do:

{@sand.link UIFormOwner}

by looking things up in the .jars and then finding
the corresponding doc off SAND_HOME, but you don't
have much context in a taglet. Pretty much you
just get the tag text. One way to make this work
would be to maintain our own lookup table
(accessible from SandBuildRoot) as we go through.

In terms of maintenance, most of the references
don't move around too much, but having the javadoc
warning on a link breakage is a good thing.
Definitely this would be nice to have.

[Eric Parker]

Logged In: YES
user_id=452458

Another reason this is nice to have is it shortens
up the javadoc class and method signatures, making
things more navigable. Probably the first step is
to try this out manually in the TaskHeapDemo
deployment by hacking mainbuild.xml or whatever.
That way we can:

1. make sure the linkage works as expected
2. see what kind of time impact this has

It's possible a large portion of the javadoc time
is spent setting up the doc structures for
processing, in which case this may not have much
build time effect. First person to get this info
post a follow up message here.