cocoon-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Bruno Dumon <br...@outerthought.org>
Subject Re: [docs] sitemap component docs initial import done
Date Mon, 20 Mar 2006 10:58:42 GMT
On Mon, 2006-03-20 at 11:20 +0100, hepabolu wrote:
> Bertrand Delacretaz said the following on 18-03-2006 21:24:
> > Le 18 mars 06 à 21:03, Bruno Dumon a écrit :
> > 
> >> ...You can see the result in the "Components" section of the 
> >> documentation,
> >> or browse it using the faceted navigation...
> > 
> > Awesome! (sound of me writing down your name in the 
> > I-owe-these-guys-a-beer list)
> > 
> >> ...There's still a lot of work to do to fill in all the docs, but at 
> >> least
> >> this gives an overview of the available components...
> > 
> > And the work can be done in small steps, one class at a time, cool!
> 
> +1000 here too.
> 
> BTW Just for clarity: if I properly tag a class and add the info that's 
> in the legacy docs for this class, would that be ok? And was that your 
> intention?

The intention is to tag the classes, and to write longer, user-oriented
documentation on it in Daisy. For this the legacy docs, javadoc, wiki
and mailing list archives can be used as inspiration.

If you want to help out, but don't necessarily know much about all these
components, a first and very helpful step would be to add the javadoc
tags.

Here's a description of the supported tags, taken from
whiteboard/sitemaptags2daisy/README.txt

--- begin ---
@cocoon.sitemap.component.name
        default name with which this component is declared in the
        sitemap

@cocoon.sitemap.component.documentation.disabled
        excludes the component from the documentation

@cocoon.sitemap.component.documentation
        A short (one-paragraph) description of the component.
        Can contain HTML markup (preferably only inline tags).

@cocoon.sitemap.component.documentation.caching
        A comment about the caching of this component. The cacheability
        of the component is figured out automatially by its implemented
        interfaces, but this tag allows to provide a short comment on
        the chaching conditions. This is mapped to a field in Daisy,
        thus should not contain HTML markup.
--- end ---

All tags are optional.

For the @c.s.c.documentation tag, you can often just take the first or
first few sentences of the javadoc.

Also take care to add the tags at the end of the javadoc. I mean the
javadoc should be structured like this:

/**
 * Here's the normal javadoc
 *
 * @cocoon.sitemap.component.documentation blah blah
 */

If you look at e.g. I18nTransformer.java, you'll see the tags are at the
top, and the normal javadoc text at the bottom, which breaks the javadoc
generation:
http://cocoon.apache.org/2.1/apidocs/org/apache/cocoon/transformation/I18nTransformer.html
(it thinks the text is all part of the @c.s.c.logger annotation).

Note that I'm running this tool on trunk, so any updates will only have
effect when committed over there.

-- 
Bruno Dumon                             http://outerthought.org/
Outerthought - Open Source, Java & XML Competence Support Center
bruno@outerthought.org                          bruno@apache.org


Mime
View raw message