cocoon-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From "Carsten Ziegeler" <cziege...@s-und-n.de>
Subject RE: [RT] Generating docs and entries for sitemap component from JavaDocs
Date Thu, 29 Apr 2004 14:57:41 GMT
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


Mime
View raw message