cocoon-docs mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From "Andy Lewis" <...@ascii27.net>
Subject Re: Documentation Format...
Date Tue, 19 Nov 2002 17:12:28 GMT

>
>
> Jeff Turner wrote:
>> On Fri, Nov 15, 2002 at 12:48:40PM -0600, 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 cocoom-dev archives or in cocoon-related  sites, you should
find
> references there.
>
> IMHO technical documentation should definately be in the source files.
>

I agree that DEVELOPER documentation should be in the source files. But not user documentation.
What I suggested was for users. Javadocs for developers, with every bit of useful extension
and
enhancement that can be viably added, but having user docs in the code I disagree with.
> --
> Nicola Ken Barozzi                   nicolaken@apache.org
>             - verba volant, scripta manent -
>    (discussions get forgotten, just code remains)
> ---------------------------------------------------------------------


-- 
"The heights of genius are only measurable by the depths of stupidity."



Mime
View raw message