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 [EMAIL PROTECTED]
- verba volant, scripta manent -
(discussions get forgotten, just code remains)
---------------------------------------------------------------------