cocoon-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Bertrand Delacretaz <bdelacre...@apache.org>
Subject refdoc is about high-level docs (was: SLOP Patch - Added Doktor Comments)
Date Wed, 10 Aug 2005 15:01:52 GMT
Hi Robert,

Le 1 août 05, à 06:03, Robert Graham a écrit :

> I have attached the patch for adding in doktor comments to the SLOP
> block...

I've finally found some time to have a closer look, before leaving 
tomorrow.

I haven't applied your changes, because I feel there are too many 
@doktor comments as is. It's not your fault - it's mine, read on.

The main goal, but I probably haven't explained this clearly enough 
before, is not to reinvent javadoc by documenting all the details about 
classes, interfaces, etc. We'll keep javadoc for that, it works fine.

Rather, we want to generate a higher level documentation, which 
explains how to use Cocoon components and which puts together the 
*cocoon-level* information found in various files. It's a bit like the 
new Cocoon stack traces vs. java stack traces.

Taking the slop block as an example again, it has only one component, 
the SlopGenerator, so I'd like refdoc to generate just one document, 
with the following info. In brackets the filenames where the @doktor 
snippets are extracted from:

What is the SlopGenerator (SlopGenerator.java)
What are its configuration and sitemap parameters  (SlopGenerator.java)
How to declare it in a sitemap (samples sitemap.xmap)
Some example pipelines (samples sitemap.xmap)
Example output (dunno how we're going to do this yet, having @doktor 
markers in samples output??)

For configuration and sitemap parameters, the @doktor markers need to 
be next to the lines of code which read them, to remind programmers to 
keep them in sync:

   /** @doktor type:sitemap-parameter name:encoding, description: set 
the encoding to use to read the input file */
   encoding = parameters.getParameter("encoding", null);

Maybe with a shortcut notation, this is a bit heavy. But that's for 
another day.

I think that's it. At this level we don't care about classes, 
interfaces, methods, only Cocoon components and their use.

Adding the necessary markers to the slop code shouldn't take long, and 
this is also a goal: if people need too much work to annotate  existing 
code they won't do it, so we have to stay at a pragmatic level, where 
the gain (a brand new reference document which stays in sync with code 
and examples) is worth the few minutes that it takes to annotate the 
code.

Of course the SlopGenerator is a dead simple component, others might 
need much more documentation, but I hope this shows my idea more 
precisely. Sorry about not communicating this better before.

-Bertrand



Mime
View raw message