cocoon-docs mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Nicola Ken Barozzi <nicola...@apache.org>
Subject Re: Documentation Format...
Date Tue, 19 Nov 2002 18:10:40 GMT

Andy Lewis wrote:
>>
>>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.

Why?
When a developer writes a class, he has to be fully aware of how it will 
be used, and what the contract is. In usual Java classes it's quite 
easy, since the user of a class is a developer. In our case, the user 
can also not be a Java developer, but a webapp assembler.

But who decides the parameters of the Component?  Who gives it the 
functionality? It's the person that makes the Java code, no?
So IMHO it's not about user VS developer, but technical VS more descriptive.


Do this then: take a Cocoon Component, and write the documentation in 
the file and out of the file, as you think is best, and post it here.
So we can discuss on a real example, make changes to it, and get a 
better picture. :-)

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


Mime
View raw message