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
smime.p7s
Description: S/MIME cryptographic signature
