You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@cocoon.apache.org by Bruno Dumon <br...@outerthought.org> on 2006/03/18 21:03:10 UTC
[docs] sitemap component docs initial import done
Hi,
I just wanted to let you know:
* that the new tool to sync the information about sitemap components
from the Java sources to Daisy documents, about which I wrote in a
previous mail, is now in the whiteboard.
* that I've done an initial run of it (during which I disabled the email
notifications to avoid 190 similar mails on the docs list). It uses the
trunk-sources so for now not all blocks are included.
You can see the result in the "Components" section of the documentation,
or browse it using the faceted navigation.
http://cocoon.zones.apache.org/daisy/documentation/
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.
I'll see to add some documentation on how to contribute to this.
--
Bruno Dumon http://outerthought.org/
Outerthought - Open Source, Java & XML Competence Support Center
bruno@outerthought.org bruno@apache.org
Re: [docs] sitemap component docs initial import done
Posted by Bruno Dumon <br...@outerthought.org>.
On Mon, 2006-03-20 at 14:09 +0100, hepabolu wrote:
> Bruno Dumon said the following on 20-03-2006 11:58:
>
> > 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.
> >
> > 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).
>
> So after this is done, each component ends up with:
> - a javadoc file
> - a summary (using this tool) in Daisy
> - a Daisy page with user oriented info
>
> Is this correct?
The last two items are in the same Daisy document, just different parts
in it. So they will be dispayed on the same page.
As for every Java class, there will of course be a javadoc-generated
page. However, since sitemap components are not used using their Java
API, and their target audience is not only Java developers, it is IMO
more meaningful and easier to maintain their docs in Daisy.
So with time we might remove the longer user-oriented descriptions from
the javadoc and only use Daisy for them, but let's first see how this
evolves before removing anything.
>
> > Note that I'm running this tool on trunk, so any updates will only have
> > effect when committed over there.
>
> Good to know. ;-)
>
> Bye, Helma
>
--
Bruno Dumon http://outerthought.org/
Outerthought - Open Source, Java & XML Competence Support Center
bruno@outerthought.org bruno@apache.org
Re: [docs] sitemap component docs initial import done
Posted by hepabolu <he...@gmail.com>.
Bruno Dumon said the following on 20-03-2006 11:58:
> 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.
>
> 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).
So after this is done, each component ends up with:
- a javadoc file
- a summary (using this tool) in Daisy
- a Daisy page with user oriented info
Is this correct?
> Note that I'm running this tool on trunk, so any updates will only have
> effect when committed over there.
Good to know. ;-)
Bye, Helma
Re: [docs] sitemap component docs initial import done
Posted by Bruno Dumon <br...@outerthought.org>.
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
Re: [docs] sitemap component docs initial import done
Posted by hepabolu <he...@gmail.com>.
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?
Bye, Helma
Re: [docs] sitemap component docs initial import done
Posted by Bertrand Delacretaz <bd...@apache.org>.
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!
-Bertrand