forrest-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Jeff Turner <je...@apache.org>
Subject Re: The Mythical Javadoc generator (Re: Conflict resolution)
Date Fri, 13 Dec 2002 16:09:34 GMT
On Fri, Dec 13, 2002 at 04:07:53PM +0100, Nicola Ken Barozzi wrote:
> 
> 
> Jeff Turner wrote:
> >On Thu, Dec 12, 2002 at 05:49:03PM +0100, Nicola Ken Barozzi wrote:
> >...
> >
> >>>>Everything must be underneath Cocoon, or we have a hybrid we cannot 
> >>>>easily control. What can't Cocoon do?
> >>>
> >>>Cocoon can't generate Javadocs, which is inherently a batch-processing
> >>>job.  
> >>
> >>It can, it just needs a javadoc Generator.
> >>Give it a start dir, and it will generate a listing with the dir 
> >>Generator, generate all javadocs there, and get on by crawling the 
> >>directory links.
> >
> >
> >That is impossible.  Generating Javadocs is, as I said, "inherently a
> >batch-processing job".  Javadoc pages are highly hyperlinked, and the
> >Javadoc tool needs to have _everything_ loaded into memory, so it can
> >work out whether to write out, say, 'org.apache.foo.MyClass' or '<a
> >href="MyClass.html">MyClass</a>'.
> 
> It just needs to have the compiled jars in the classpath, and this is 
> what qdox does.

qdox works with bytecode. Javadoc works with Java source.

> I'm talking about a javadoc-like tool, not necessarily javadoc.

Well I'm talking about Javadoc ;P  Which is the primary use-case.

> >Besides which, how long do you think it would take for Cocoon to invoke
> >Javadoc once for every single source file?
> 
> It would invoke its own Generator, not the javadoc tool. Besides, the 
> Generator can always preload all the files if it wants to,

For every single file, preload all the OTHER files, then spit out just
one HTML file?  Javadoc isn't crazy enough to let you do this.

Guess I'll stop shooting the fish in the barrel now.

> there is no real technical problem.
>
> >Cocoon is a doc generating tool.  Javadoc is a doc generating tool.  One
> >renders XML, the other renders Java files.  
> 
> Errr, one renders *through* XML, it can get it from anything. Javadoc 
> gets only Java files.

Yes.  One renders XML, the other renders Java files.  Fundamentally
different types of data.

But I see your point.. Cocoon and Javadoc are not equivalent, because
Cocoon isn't just an XML processing tool.  Cocoon has got this sitemap,
trying to own the _whole_ URI space.. even the bits which don't require
XML processing!  Argh.. and this can't even be prevented, because web.xml
allows only one url-pattern per servlet.  So Cocoon gets mapped to '/*',
and that's it: no other servlets, no cgi-bins, not even a directory of
Javadoc HTML can escape.

> >Trying to invoke one from the other is... how do I put it politely...
> >um, I'd better not even try :)
> 
> No need to invoke javadoc, it would just need to have the docs in the 
> classpath and generate. On cocoon-docs they seem to be working on a 
> Generator that does this, we'll see.
> 
> Anyway, the point is not if Cocoon should *generate* these docs, as it 
> doesn't generate the sources of the docs too. But IMO it should serve 
> them all, be they handwritten or pregenerated. In Centipede we generate 
> documentv11 docs out of junit, checkstyle, and other tests, and pass 
> them to Forrest. Of course I don't want Cocoon to *generate* them, but 
> to publish them, yes.

What do you mean by "publish"?  Running Cocoon in a live webapp, serving
Javadocs through Cocoon makes sense, if only because web.xml has such
coarse-grained uri-to-servlet mapping.  But how about for CLI generation?
Do we try to mimick the Cocoon Über Alles approach of the live webapp?
The javadocs are _already_ generated, and <javadoc> has already put them
in build/site/apidocs/.  Now how is Cocoon (via the CLI) going to
"publish" them?


--Jeff

Mime
View raw message