You are viewing a plain text version of this content. The canonical link for it is here.
Posted to general@jakarta.apache.org by Henri Yandell <ba...@generationjava.com> on 2005/08/20 09:12:54 UTC
Multidoc-jnr - opinions?
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?
---------- Forwarded message ----------
Date: Sat, 20 Aug 2005 03:07:46 -0400 (EDT)
From: Henri Yandell <ba...@generationjava.com>
Reply-To: osjava-users@lists.osjava.org
To: osjava-users@lists.osjava.org
Subject: [Osjava-users] Multidoc-jnr - opinions?
Multidoc was an idea I had to generate a project-wide documentation site
based on links to parts of each individual project (javadoc, xref,
jcoverage etc). http://multidoc.osjava.org/. It works, but has complexity
(has to scrape the parts of the projects to build its front pages).
Multidoc-jnr is a simpler idea, with a much simpler implementation
(http://svn.osjava.org/svn/osjava/trunk/multidoc-jnr/) that does much the
same thing for released javadoc.
Take a look: http://dist.osjava.org/releases/multidoc-jnr/
Hen
---------------------------------------------------------------------
To unsubscribe, e-mail: general-unsubscribe@jakarta.apache.org
For additional commands, e-mail: general-help@jakarta.apache.org
Re: Multidoc-jnr - opinions?
Posted by Phil Steitz <ph...@steitz.com>.
Sorry, should be
http://people.apache.org/~psteitz/apidocs/maven.xml
-Phil
---------------------------------------------------------------------
To unsubscribe, e-mail: general-unsubscribe@jakarta.apache.org
For additional commands, e-mail: general-help@jakarta.apache.org
Re: Multidoc-jnr - opinions?
Posted by Henri Yandell <ba...@generationjava.com>.
On Wed, 24 Aug 2005, Phil Steitz wrote:
> Henri Yandell wrote:
>>
>>
>> Nicest would be to do this in maven.xml; have it automatically know the
>> structure of the local javadoc tree and link the dependencies in. Easiest
>> is to just hack each one into the project.properties.
>
> I got the "single big javadoc" thing to work using maven without having to
> reference any of the projects directly (other than attributes, which has its
> sources in a non-standard place). The packages come out sorted in "reactor
> order", though and due to general lack of enthusiasm for this approach, I did
> not spend any time trying to get jelly's util:sort to work to fix this. The
> maven.xml linked below contains some things that may be useful for the
> aggregation approach - collecting dependencies and javadoc links from the
> subprojects.
>
> http://people.apache.org/~psteitz/apidocs/maven.xml
Definitely easier than listing each one out etc :) I understand the lack
of enthusiasm to fixing the sort though.
I spent a couple of hours this evening playing with multidoc-jnr again:
http://dist.osjava.org/releases/multidoc-jnr/index.html
Latest version shows when you go into a project, and clirr is used to
generate diff reports between versions. Clirr wants to use the classpath
(uses BCEL underneath) so there are some exceptions in some of the reports
where the API contains code from a different library.
Given that unzip and javap can be used on the command line to do much the
same thing, I'm 50/50 currently on whether to just try and create a better
version of an old javadiff alias.
Hen
---------------------------------------------------------------------
To unsubscribe, e-mail: general-unsubscribe@jakarta.apache.org
For additional commands, e-mail: general-help@jakarta.apache.org
Re: Multidoc-jnr - opinions?
Posted by Phil Steitz <ph...@steitz.com>.
Henri Yandell wrote:
>
>
> On Wed, 24 Aug 2005, Henning Schmiedehausen wrote:
>
>> 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
>
>
> Once the versions are in official locations, each project can set their
> linking (least at osjava that's my plan). So links will work, but it
> won't all be in one big centrally built javadoc.
>
> Nicest would be to do this in maven.xml; have it automatically know the
> structure of the local javadoc tree and link the dependencies in.
> Easiest is to just hack each one into the project.properties.
>
> More on this when I get put another burst of energy into it. Also as the
> jar files are there, I think I can do something very cool with clirr :)
>
I got the "single big javadoc" thing to work using maven without having
to reference any of the projects directly (other than attributes, which
has its sources in a non-standard place). The packages come out sorted
in "reactor order", though and due to general lack of enthusiasm for
this approach, I did not spend any time trying to get jelly's util:sort
to work to fix this. The maven.xml linked below contains some things
that may be useful for the aggregation approach - collecting
dependencies and javadoc links from the subprojects.
http://people.apache.org/psteitz/apidocs/maven.xml
---------------------------------------------------------------------
To unsubscribe, e-mail: general-unsubscribe@jakarta.apache.org
For additional commands, e-mail: general-help@jakarta.apache.org
Re: Multidoc-jnr - opinions?
Posted by Henri Yandell <ba...@generationjava.com>.
On Wed, 24 Aug 2005, Henning Schmiedehausen wrote:
> 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
Once the versions are in official locations, each project can set their
linking (least at osjava that's my plan). So links will work, but it won't
all be in one big centrally built javadoc.
Nicest would be to do this in maven.xml; have it automatically know the
structure of the local javadoc tree and link the dependencies in. Easiest
is to just hack each one into the project.properties.
More on this when I get put another burst of energy into it. Also as the
jar files are there, I think I can do something very cool with clirr :)
Hen
---------------------------------------------------------------------
To unsubscribe, e-mail: general-unsubscribe@jakarta.apache.org
For additional commands, e-mail: general-help@jakarta.apache.org
Re: Multidoc-jnr - opinions?
Posted by Henning Schmiedehausen <hp...@intermeta.de>.
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: general-unsubscribe@jakarta.apache.org
> For additional commands, e-mail: general-help@jakarta.apache.org
>
--
Dipl.-Inf. (Univ.) Henning P. Schmiedehausen INTERMETA GmbH
hps@intermeta.de +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: general-unsubscribe@jakarta.apache.org
For additional commands, e-mail: general-help@jakarta.apache.org
Re: Multidoc-jnr - opinions?
Posted by Henri Yandell <ba...@generationjava.com>.
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: general-unsubscribe@jakarta.apache.org
For additional commands, e-mail: general-help@jakarta.apache.org
Re: Multidoc-jnr - opinions?
Posted by Phil Steitz <ph...@steitz.com>.
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.
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 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
Maybe its just me, but I like being able to browse all of the packages
in one place.
Phil
> ---------- Forwarded message ----------
> Date: Sat, 20 Aug 2005 03:07:46 -0400 (EDT)
> From: Henri Yandell <ba...@generationjava.com>
> Reply-To: osjava-users@lists.osjava.org
> To: osjava-users@lists.osjava.org
> Subject: [Osjava-users] Multidoc-jnr - opinions?
>
>
> Multidoc was an idea I had to generate a project-wide documentation site
> based on links to parts of each individual project (javadoc, xref,
> jcoverage etc). http://multidoc.osjava.org/. It works, but has complexity
> (has to scrape the parts of the projects to build its front pages).
>
> Multidoc-jnr is a simpler idea, with a much simpler implementation
> (http://svn.osjava.org/svn/osjava/trunk/multidoc-jnr/) that does much the
> same thing for released javadoc.
>
> Take a look: http://dist.osjava.org/releases/multidoc-jnr/
>
> Hen
>
> ---------------------------------------------------------------------
> To unsubscribe, e-mail: general-unsubscribe@jakarta.apache.org
> For additional commands, e-mail: general-help@jakarta.apache.org
>
---------------------------------------------------------------------
To unsubscribe, e-mail: general-unsubscribe@jakarta.apache.org
For additional commands, e-mail: general-help@jakarta.apache.org