[docs] @cocoon.sitemap tags and Daisy

[Bruno Dumon <br...@outerthought.org>]

Hi,

This weekend I wrote a little tool to sync the @cocoon.sitemap.**
annotations in the source code to Daisy documents. This proved to be
quite simple, since a lot of work was already done: the tags were
already defined, there are sources files using them, and the SitemapTask
class showed how to use QDox to extract them.

More precisely, for each sitemap component source file, the tool will
check if there is already a document for it in Daisy (based on a field
JavaClass containing the fully qualified name of the class). If it does
not exist, it will create it, or otherwise update the existing document
(only if needed, so that documents are not updated unnecessarily).

The following annotations are mapped to fields in Daisy documents:

@cocoon.sitemap.component.name
@cocoon.sitemap.component.documentation.caching

The value of the following annotation is mapped to a part (to support
markup and somewhat longer content) in the Daisy document:

@cocoon.sitemap.component.documentation

The following tag is honored to exclude the class from the
documentation:

@cocoon.sitemap.component.documentation.disabled

Also, some fields are automatically assigned:
- java class name
- component type (matcher, generator, ...)
- block name
- deprecated

There are some other tags (for label, logger, pooling.max and
configuration) that it currently ignores, as I thought these are not
that useful.


The goal of all this would be that the basic facts about each component
are taken from the source code, and longer (user-oriented) documentation
could then be added in Daisy (in a document part that is left alone by
this tool).

I'll finish it up next weekend (if time permits) and commit it to the
whiteboard. I would then also like to give it a run (based on trunk), if
nobody sees a problem in that (the documents can always be deleted
afterwards, if needed).

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

Re: [docs] @cocoon.sitemap tags and Daisy

[Reinhard Poetz <re...@apache.org>]

Ross Gardler wrote:
> Bruno Dumon wrote:
> 
>> The goal of all this would be that the basic facts about each component
>> are taken from the source code, and longer (user-oriented) documentation
>> could then be added in Daisy (in a document part that is left alone by
>> this tool).
> 
> 
> Super cool!

yes, indeed!

-- 
Reinhard Pötz           Independent Consultant, Trainer & (IT)-Coach 

{Software Engineering, Open Source, Web Applications, Apache Cocoon}

                                        web(log): http://www.poetz.cc
--------------------------------------------------------------------

	
		
___________________________________________________________ 
Telefonate ohne weitere Kosten vom PC zum PC: http://messenger.yahoo.de

Re: [docs] @cocoon.sitemap tags and Daisy

[Ross Gardler <rg...@apache.org>]

Bruno Dumon wrote:
> The goal of all this would be that the basic facts about each component
> are taken from the source code, and longer (user-oriented) documentation
> could then be added in Daisy (in a document part that is left alone by
> this tool).

Super cool!

Ross