Hi,
I toyed with similar ideas for a long time (I even had once an intern
whip something up), however, there are a number of drawbacks:
- different versions. The osjava variant tries to get this right by
allowing the user to choose the versions.
- inter-project links. Phils' variant builds everything in one big
javadoc (don't do that. IMHO). So links beween projects are resolved
correctly. You might even toss in links to Suns' official API docs
for java.* and sun.* packages
- project-version-clashes. This is the hard one.
Suggest we have project "T"
T Version 1 relies on "CL1.0"
T Version 2 relies on "CL1.1"
T Version 3 relies on "CL2.0"
(T and CL are real life projects, anonymized to protect the
innocent... ;-)
=> We need information which CL version should be linked when
building the docs for "T". For maven builds. that is not that
hard, the information is inside the POM.
Alternatively you could just link to "latest release of CL".
Unfortunately, T 2 relies on some methods in CL 1.0 which are
deprecated in CL 1.1 and removed in CL 2.0. Linking to the "latest
version" would mean that the docs either point to outdated or missing
information.
The best thing that I could come up with was some sort of dependency
database where you could pop in a source tree (or an URL to pull from.
or a CVS to pull from) and then add annotations that hint a doc builder
which projects are related and should be linked together.
This all gets worse if you have two equally "good" versions of a
package. Think "JDK 1.4.2" and "JDK 5.0"....
The easiest solution is just to toss the "inter-project" links. However,
then you just get a centralized collection of Javadocs, which is nice
but not really as useful as a well-linked collection.
Food for thought...
Regards
Henning
(Gee, "anonymize" is not an English word? )
On Sat, 2005-08-20 at 21:20 -0400, Henri Yandell wrote:
>
> On Sat, 20 Aug 2005, Phil Steitz wrote:
>
> > Henri Yandell wrote:
> >>
> >> Prototype of what I want to do javadoc-wise for Jakarta :)
> >>
> >> http://dist.osjava.org/releases/multidoc-jnr/
> >>
> >> (click on something as long as it's not Payload 0.3 or 0.4; seems my
> >> distributions are lacking javadoc there).
> >>
> >> Any opinions?
> >
> > I like the idea of doing this and being able to easily find javadoc for all
> > release versions. It might be more convenient and maybe less confusing to
> > have the release versions on the front page, though, so you could click on
> > the release you are looking for.
>
> It's a toss up I think. I'd like to do Jakarta and then later the entire
> ASF java codebase with something like this, so frontpage space isn't going
> to be too cheap.
>
> Also, I think it'd be sweet if javadiff or something could be modified to
> find differences between the two javadoc versions (no source available)
> and there could be a viewcvs-like [changes from previous version] icon
> link next to each release.
>
> > I have been playing with something similar for commons using ant. Here is
> > an
> > example built from current svn trunks:
> >
> > http://people.apache.org/~psteitz/apidocs/
>
> I like this a lot, for Commons anyway. Your link above is a tighter
> focused version of my original multidoc, and I imagine that it has the
> advantage of having cross-links between the particular projects working.
>
> Be interesting to see how you handle versions :) I assume that Commons
> does not necessarily contain just a single version of each API in its
> dependency graph, but that there are multiple Collections versions that
> would have to be linked in.
>
> > I was thinking we could add a link on the commons site to "current"
> > combined
> > api docs and also "latest release" with the titles changed to include the
> > release nunmbers. To keep the "current" content up to date, we could in
> > theory add the generating ant script to the nightly build. This could be a
> > slight pain to maintain, however, and because javadoc likes to do
> > everything
> > in memory, it is a pig to run. The script is here:
> > http://people.apache.org/~psteitz/apidocs/build.xml
>
> Looks simple enough :) I like the 'current' and 'latest release' ideas.
> Only downside is how specific you've had to be, would be nice to get the
> title and packages from the project.xml and find a way to supply a small
> number of wildcards, aka:
>
> svn.apache.org/repos/asf/jakarta/commons/trunks-proper/*/project.xml
> svn.apache.org/repos/asf/jakarta/commons/trunks-proper/*/src/(java|share)/
>
> or whatever.
>
> > Maybe its just me, but I like being able to browse all of the packages in
> > one
> > place.
>
> My main itch was that I like to download the jars from ibiblio and use the
> online javadoc, but that we're pretty weak in maintaining older versions
> of the javadoc.
>
> My next step, now I have a simple script that can at least attempt to suck
> javadoc out of maven distributions, is to start building a filesystem of
> released javadocs.
>
> Hen
>
> ---------------------------------------------------------------------
> To unsubscribe, e-mail: [EMAIL PROTECTED]
> For additional commands, e-mail: [EMAIL PROTECTED]
>
--
Dipl.-Inf. (Univ.) Henning P. Schmiedehausen INTERMETA GmbH
[EMAIL PROTECTED] +49 9131 50 654 0 http://www.intermeta.de/
RedHat Certified Engineer -- Jakarta Turbine Development
Linux, Java, perl, Solaris -- Consulting, Training, Engineering
4 - 8 - 15 - 16 - 23 - 42
---------------------------------------------------------------------
To unsubscribe, e-mail: [EMAIL PROTECTED]
For additional commands, e-mail: [EMAIL PROTECTED]
