Tony Collen wrote: > > Carsten Ziegeler wrote: > > > I think we discussed this and I think to remember that the general > > opinion has been pro the following. > > > > I think we should start generating the user docs for sitemap > > components from the java docs. Currently these are separate things > > which leads to > > Hmm... I'm not sure if I like the idea of having the userdocs > embedded in the source code. > > > - user doc is not updated when the component changes > > Are the Javadocs even updated then the component changes? > > > - component is only documented in java docs > > If we embed the user docs, this only becomes worse, IMO, > since the single source of the docs would be the from the > comment tags. I see how the other docs would be generated > from the source, but it's just not sitting right with me. > > Unless we use this purely as a component technical reference, > where there would be some sparse information (i.e. what > parameters we can pass to it), then I would feel a better > towards this idea. > > > - duplicate comments > > Where? > > > In addition I would like to generate the entries for the > sitemap from > > the javadocs as well. Currently we have the core components > already in > > the main sitemap and add the optional components (from > > blocks) by using the xpatch utility. So again, this is an addition > > configuration file. > > > > The general idea is to use some javadoc tags, like > @cocoon.something > > to specify sitemap components (their name, perhaps the > logger category > > etc.) and generate the sitemap entries from this. > > In addition the JavaDoc for the class will be converted > into the XML > > doc file for that component (and added to the index etc.) > > I'm generally +1 on this. > > > I'm currently in "do mood" and played a little bit with a > qdox based > > ant task and would like to get a first version finished in the next > > days. The first version will be used for those components that > > currently don't have docs, so (nothing) will break and we can play > > around with it. > > > > WDYT? > > As I said, I'm leery of embedding a bunch of user-guide type > material into the Javadocs, but I would be more comfortable > if it was used as more of a technical reference than > anything. Maybe a quick one or two-paragraph description of > how the component works or what it does, and a description of > any parameters that it might take. Beyond that, I think we > should still use the external documentation format. > > Possible tags: > @cocoon.component.loglevel (one) > @cocoon.component.sitemapname (one) > @cocoon.component.description (one) > @cocoon.component.parameter (multiple) > > That isn't to say, however, that we couldn't generate a large > technical reference doc from these, and include them with the > "regular" docs. > Basically I mostly agree with you. It's not that good to have user docs in the Java Source, but it's better to have the JavaDocs as a documentation than nothing :) (which is today the case - sometimes at least). In general, if you have two places to document a single thing than there are always problems with updating both places. Either one is lazy or simple forgets about it etc. The JavaDoc for a sitemap component usually contains a general description and the configuration possibilities, so this can go into the user docs.
The first step would be a task that does: FileGenerator.java -> userdocs/generators/file.xml (based on the info in the class) So basically we generate a reference for sitemap components with the task. The Cocoon user docs of course still contain much more info than the reference provides, so it's just an additional information. As a second step I'm thinking of merging two sources, which means you write a nice user docs in the xml format and the build system adds all the infos from the JavaSource, like configuration etc. But I think, let's do simple steps :) Carsten
