cocoon-docs mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From David Crossley <cross...@indexgeo.com.au>
Subject Re: Documentation Format...
Date Mon, 18 Nov 2002 09:41:32 GMT
Nicola Ken Barozzi wrote:
> 
> 
> Jeff Turner wrote:
> > Tony Collen wrote:
> > 
> >>Bertrand Delacretaz wrote:
> > 
> > ...
> > 
> >>>This might mean restructuring much of the docs, trying to get obvious URLs

> >>>like
> >>>
> >>>docs/components/generators/FileGenerator.html
> >>>docs/components/serializers/PDFSerializer.html
> >>>
> >>>(and later)
> >>>docs/blocks/pdf/fop/FopPdfBlock.html
> >>>
> >>>
> >>
> >>+1.  The code is organized logically into packages, why shouldn't the 
> >>docs? :)  
> > 
> > ...
> > 
> > How about using a tool like xdoclet or qdox to generate XML from @tags in
> > the Cocoon source?
> > 
> > Lots of work.. Ant has got something like this prototyped in
> > proposal/xdocs.
> 
> It has already be done by someone (sorry! don't remember who) some time 
> ago. We have also had a discussion on it, but somehow the thing didn't 
> finalize.
> 
> If you have time, look in the cocoon-dev archives or in cocoon-related 
> sites, you should find references there.
> 
> IMHO technical documentation should definately be in the source files.

I remembered Bernhard Huber's excellent work on this, so
i went digging through MARC to find the old discussions.
There were various threads, here are some:

 Reference Doc From Java Sources [Was Check Source]
 http://marc.theaimsgroup.com/?l=xml-cocoon-dev&m=101226838012373

 Re: Check Source
 http://marc.theaimsgroup.com/?l=xml-cocoon-dev&m=101207176630450

It would be ideal to generate reference documentation
direct from Java source. As Berni says in these threads.
the big job is going through all the java source to
add the necessary javadoc tags and comments.

This could always start small and gradually expand. We
seem to have more people interested in documentation
now and the cocoon-docs list, so i would like to see
Berni's work resurrected.

I wonder if we can extract some minimal information from
javadoc tags and supplement that with an xml fragment in
an accompanying file, to build a -manpage.xml
--David



Mime
View raw message