Javadoc quirks -- linking to anchor within package summary?

J

John Ersatznom

It seems to be possible to a) include package-summary javadocs using
Eclipse (in package view, right click, "new file", "package.html"; it
will open a blank page in your browser, so you have to return to eclipse
and drag the "package.html" entry to the document editing area then
enter your html) and b) link to your package summary from other javadocs
(IDE-independent; {@link foo.bar.package.name sometext}). Unfortunately,
javadoc seems to strip the anchor (e.g. @link foo.bar#baz sometext
results in <a href="blahblah/foo/bar/package-summary.html">sometext</a>,
note no #baz on URL) and the package summary text is usually well below
the fold when the link is followed. Being able to link to a particular
part of your summary text would be useful. Any suggestions, short of
putting the <a href> link directly into the javadocs and watching it
break every time your directory structure changes?
 
D

Daniel Dyer

It seems to be possible to a) include package-summary javadocs using
Eclipse (in package view, right click, "new file", "package.html"; it
will open a blank page in your browser, so you have to return to eclipse
and drag the "package.html" entry to the document editing area then
enter your html) and b) link to your package summary from other javadocs
(IDE-independent; {@link foo.bar.package.name sometext}). Unfortunately,
javadoc seems to strip the anchor (e.g. @link foo.bar#baz sometext
results in <a href="blahblah/foo/bar/package-summary.html">sometext</a>,
note no #baz on URL) and the package summary text is usually well below
the fold when the link is followed. Being able to link to a particular
part of your summary text would be useful. Any suggestions, short of
putting the <a href> link directly into the javadocs and watching it
break every time your directory structure changes?

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.

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.

Dan.
 
J

John Ersatznom

Daniel said:
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...
 
D

Daniel Pitts

John said:
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...

As far as I know, all java-doc links are relative, and therefor should
be safe to put where ever.

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.

Its perfectly suitible for hosting Javadocs, forum software (forums
virtualinfinity.net), TWiki (projects coloraura.com), random applets
(coloraura.com/artwork/), home made wiki software (wiki
virtualinfinity.net), php scripts (www virtualinfinity.net), a few
databases, etc...

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).

Hope this helps, and good luck.
- Daniel.
 
J

John Ersatznom

Daniel said:
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?
 
L

Lew

John said:
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.

Actually, serving them takes less bandwidth because less is available for most
customers. The upload rates on just about all residential cable-Internet
accounts are slower than the download rates. On my residential cable
connection I get about 6 Mbit/s download and about 300Kbit/s upload.

- Lew
 
J

John Ersatznom

Lew said:
Actually, serving them takes less bandwidth because less is available
for most customers. The upload rates on just about all residential
cable-Internet accounts are slower than the download rates. On my
residential cable connection I get about 6 Mbit/s download and about
300Kbit/s upload.

Yeah, but bit for bit it's the same, i.e. sending a 30K file or
retrieving a 30K file uses the same bandwidth. Of course if the ISP
itself has a slower uplink than a downlink to its upstream, it might
reasonably bother the ISP more, but I think the grades of connections
ISPs hook up with are by-and-large symmetrical. In that case, serving a
30K file should bother it the same, or even less since there's less user
contention for the up-pipe with the lower per-user uplink throttle than
there is user contention for the down-pipe, so your 30K upload impacts
the other users less than a 30K download.
 
L

Lew

John said:
Yeah, but bit for bit it's the same, i.e. sending a 30K file or
retrieving a 30K file uses the same bandwidth.

Bandwidth means bits per second, not total bits.

- Lew
 
J

John Ersatznom

Lew said:
Bandwidth means bits per second, not total bits.

I'm using it in the colloquial "total traffic" sense. Should be OK,
particularly as when multiplied by the frequency with which the user
transfers 30K files on average it becomes a "bits per second" compatible
quantity anyway.
 
L

Lew

John said:
I'm using it in the colloquial "total traffic" sense. Should be OK,
particularly as when multiplied by the frequency with which the user
transfers 30K files on average it becomes a "bits per second" compatible
quantity anyway.

'But "glory" doesn't mean "a nice knock-down argument,"' Alice
objected.

'When _I_ use a word,' Humpty Dumpty said in rather a scornful
tone, 'it means just what I choose it to mean--neither more nor
less.'

'The question is,' said Alice, 'whether you CAN make words mean
so many different things.'

'The question is,' said Humpty Dumpty, 'which is to be master--
that's all.'

Alice was too much puzzled to say anything...

- _Through the Looking Glass_, Lewis Carroll

- Lew
 

Ask a Question

Want to reply to this thread or ask your own question?

You'll need to choose a username for the site, which only take a couple of moments. After that, you can post your question and our members will help you out.

Ask a Question

Members online

No members online now.

Forum statistics

Threads
473,744
Messages
2,569,483
Members
44,903
Latest member
orderPeak8CBDGummies

Latest Threads

Top