forrest-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Nicola Ken Barozzi <nicola...@apache.org>
Subject Re: The Mythical Javadoc generator (Re: Conflict resolution)
Date Fri, 13 Dec 2002 15:07:53 GMT


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. I'm talking about a javadoc-like tool, not necessarily 
javadoc.

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

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

-- 
Nicola Ken Barozzi                   nicolaken@apache.org
             - verba volant, scripta manent -
    (discussions get forgotten, just code remains)
---------------------------------------------------------------------


Mime
View raw message