Re: Multidoc-jnr - opinions?
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
Re: Multidoc-jnr - opinions?
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: [EMAIL PROTECTED] For additional commands, e-mail: [EMAIL PROTECTED]
Re: Multidoc-jnr - opinions?
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: [EMAIL PROTECTED] For additional commands, e-mail: [EMAIL PROTECTED]
Re: Multidoc-jnr - opinions?
Sorry, should be http://people.apache.org/~psteitz/apidocs/maven.xml -Phil - To unsubscribe, e-mail: [EMAIL PROTECTED] For additional commands, e-mail: [EMAIL PROTECTED]
Re: Multidoc-jnr - opinions?
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: [EMAIL PROTECTED] For additional commands, e-mail: [EMAIL PROTECTED]
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 [EMAIL PROTECTED] Reply-To: [EMAIL PROTECTED] To: [EMAIL PROTECTED] 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: [EMAIL PROTECTED] For additional commands, e-mail: [EMAIL PROTECTED]
Re: Multidoc-jnr - opinions?
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 [EMAIL PROTECTED] Reply-To: [EMAIL PROTECTED] To: [EMAIL PROTECTED] 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: [EMAIL PROTECTED] For additional commands, e-mail: [EMAIL PROTECTED] - To unsubscribe, e-mail: [EMAIL PROTECTED] For additional commands, e-mail: [EMAIL PROTECTED]
Re: Multidoc-jnr - opinions?
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]
