Re: Javadoc quirks -- linking to anchor within package summary?
Daniel Dyer wrote:
The '#' character is reserved for referring to class members (see
<http://java.sun.com/j2se/1.5.0/docs/tooldocs/windows/javadoc.html#{@link}>).
I don't think you will be able to refer to your own anchors within the
@link tag.
Well, that's just silly, since the # usage just translates into an
anchor anyway.
There is a Javadoc-generated anchor already called
"package-description" that is used to insert a link at the top of the
package summary to the actual descriptive text. But to use this you'd
probably have to use an explicit anchor tag anyway, so it's probably no
better than your other option.
And it won't work, because the file's physical location on the
filesystem can't be assumed to be constant. Same if the documentation
ends up on the web -- the link would have to be hand-edited every time,
unless there's a relative URL that will stably refer to "this package's
package-summary.html file" from every class, interface, or whatever page
within that package. And if there is such a URL, it's either
undocumented or "documented" in being purely implied by the file layout
produced by Javadoc, and probably subject to change without notice in
either case, so any URL that works now may break with a different
version of javadoc, or even changes to the project for all I know.
Apparently it didn't occur to the genuises at Sun that people might want
to access a custom named anchor in inter-documentation linking, rather
than just either a method/field/whatever anchor or a named anchor in an
external file.
I want my documentation to be self-contained and independent of any
external file, precisely to avoid links breaking when things are moved
about (including if the filesystem layout javadoc generates changes). I
don't see any clean way to use external files other than to host them on
the Web at a stable never-changing URL, I'm afraid, and stable
never-changing Web URLs are expensive, because you have to a) get your
own domain, b) get real hosting, c) pay yearly or even monthly for
both...no free web space providers can be trusted to preserve your URLs
(or even themselves) and I don't even know of a tinyurl-like redirector
that lets you forward a URL to your own page and update it when your
page moves, either. (And that would still suffer from the link's
stability depending on the redirector.) ISP webspace is obviously right
out, too. In fact, now that I think about it, the impossibility of
having a permanent online link to anything without paying through the
nose for the rest of your life (assumes by "permanent" you really mean
permanent) is itself a massive problem, though not a Java problem...