Re: Javadoc quirks -- linking to anchor within package summary?
Daniel Pitts wrote:
As far as I know, all java-doc links are relative, and therefor should
be safe to put where ever.
Yes, but they may move. If I put a file in the doc bundle, a) the
relative URL from class X may not be the same as that from class Y's
javadoc, and b) these might change with changes to javadoc or just to
the project and the javadoc command line...
As for the expense of hosting?
I have four domains, and host them myself. It costs me $35/yr each
(thats < $3/mo), plus the cost of my cable internet (which I would have
anyway), and the cost of running a server (I admit, electricity isn't
free, but its cheap enough). The server itself is an old AMD k6, 256MB
ram, 40GB harddrive, running NetBSD. Parts I had just laying around.
Unfortunately, either you're paying through the nose for a "business"
internet account or you're violating your "consumer" internet account's
TOS. ISPs pretty much universally say "no server running unless you pay
us extra". Blatant greed, of course, since serving bits uses the same
amount of bandwidth as retrieving them for a given number of bits.
If you really want self-contained documentation, distribute it in an
archive file (such as ZIP, tar.gz, JAR, rar, or any other form of
archive).
The idea is to just run off a quick "javadoc various commandline
arguments", zip the results up, have it just work -- and have this
remain true if I add classes, link to the file from elsewhere using the
same URL, or use a different version of Sun's tools.
Are there places documentation files can go that have a fixed relative
URL from everywhere in your javadocs that Sun guarantees? Guaranteed
stable relative URLs to "this class's package's package-summary" etc.?
Or only ones that are subject to future change without notice? Until now
I've had @link and @see take care of actually linking to the proper
files for me, assumed the links end up relative (except to external
docs, for which I use the web site, e.g. sun's online copy of the core
Java API docs), and not worried (or even cared) what the actual output
file tree looks like. Now it seems I need to concern myself with the
filesystem layout of the documentation (and how stable it is under
future changes to javadoc, changes to my own classes and packages, and
so forth) in order to do some types of linking. I guess including
resources like images, and having the links not ever need manual
updating, will be a *real* barrel of fun. Maybe Eclipse can be made to
manage this as part of a project? It works for getResource resources
(e.g. stick an image file in your project, access it with
"getResource")...is there a javadoc equivalent?