You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@cocoon.apache.org by Bernhard Huber <be...@a1.net> on 2002/04/02 00:23:10 UTC
userdoc xdoc templates
Hi
i have generated xdocs templates for all sitemap components.
If you want to start documentening...
you find the xdoc templates in the zip at
http://members.a1.net/berni_huber/doclet-scratchpad.tar.gz
the userdoc xdoc templates are in generated-reference/userdoc.
Each sitemap component has its own xdoc template, moreover
a *-ref.xml (actions-ref.xml, generator-ref.xml,...)
lists all sitemap components of an category.
Beside generated-testcase has testcase of all real classes of the cocoon
project.
Once again, these are javadoc generated files, so don't expect too much...
bye bernhard
---------------------------------------------------------------------
To unsubscribe, e-mail: cocoon-dev-unsubscribe@xml.apache.org
For additional commands, email: cocoon-dev-help@xml.apache.org
Re: userdoc xdoc templates
Posted by Bernhard Huber <be...@a1.net>.
Hi,
<snip/>
>
>Cool stuff! What do we need to make these generated docs better? Where
>it gets sitemap definition and sitemap usage snippets? Every particular
>component can have many configuration parameters which should be
>documented.
>
i see two possibilities to enhance the docu
see also (http://marc.theaimsgroup.com/?t=101226845700001&r=1&w=2)
1. include some external xml-snippet, but this way docu and java source
will go separate ways more easily as today
2. enhance the java source code with some specific java doc tags
A first try was SearchGenerator.java defining "@cocoon:name search".
Let's introduce for every behaviourale apect of an sitemap component. As
I'm not a sitemap component guru so i'm quite sure i miss some aspects.
The Players:
Action
Generator
Selector
Matcher
Transformer
Serializer
Readers
The Tags
General javadoc-tags
@cocoon:name {name} the default sitemap name of the sitemap component,
eg @cocoon:name i18n, @cocoon:name xslt
@cocoon:status [default|core|optional|scratchpad] status of the sitemap
component, for TraxTransformer @cocoon:status default, for I18N
Transformer @cocoon:status core
From the Avalon-Context
Javadoc-tags For Sitemap Components being Configurable
@cocoon:config element="{name}"
[parent="{name}"]
type="{type-descriptor}"
description="{text}"
required="yes|no" [default="{default-value}]
e.g.: For I18N Transformer @cocoon:config element="catalogue-name"
parent="none" type="string"
description="basename of the message catalog"
required="yes",
Javadoc-tags For Sitemap Components being Parameterizable
@cocoon:parameter name="{name}"
type="{type-descriptor}"
description="{text}"
required="yes|no" [default="{default-value}]
Javadoc-tags For Sitemap Components using Context
@cocoon:context name="{name}"
type="{type-descriptor}"
description="{text}"
required="yes|no" [default="{default-value}]
From the Servlet-Context
Javadoc-tags For Sitemap Components using http request-parameter
@cocoon:http-request parameter name="{name}"
type="{type-descriptor}"
description="{text}"
required="yes|no" [default="{default-value}"]
for SearchGenerator: @cocoon:config element="analyzer" type="FQN"
description="This element defines the analyzer to use for searching.
Take care to use a compatible analyzer as used when generating the
index. " required="no"
default="org.apache.lucene.analysis.standard.StandardAnalyzer"
Javadoc-tags For Sitemap Components using http request-attributes
@cocoon:http-request-attribute name="{name}"
type="{type-descriptor}"
description="{text}"
required="yes|no" [default="{default-value}"]
Javadoc-tags For Sitemap Components using http session attributes
@cocoon:http-session-attribute name="{name}"
type="{type-descriptor}"
description="{text}"
required="yes|no" [default="{default-value}"]
From the Sitemap-Context
Javadoc-tags For Sitemap Components using Sitemap Parameters
I think its quite a major task to realize that kind of docu, on the
other hand cacheability can be
deduced from the the class descriptor directly if checking for Cacheable
interface.
Moreover if the tags are defined while generating the reference docu we
might check if
Contextualize is implemented that there are @cococoon:context tagsm and
vice a versa.
Any comments are welcome.
bye bernhard
>
>Btw, I found a typo in generators-ref.xml: "Sitmap Definition".
>
uhhpss,,
>
bye bernhard
---------------------------------------------------------------------
To unsubscribe, e-mail: cocoon-dev-unsubscribe@xml.apache.org
For additional commands, email: cocoon-dev-help@xml.apache.org
RE: userdoc xdoc templates
Posted by Vadim Gritsenko <va...@verizon.net>.
> From: Bernhard Huber [mailto:berni_huber@a1.net]
>
> Hi
>
> i have generated xdocs templates for all sitemap components.
> If you want to start documentening...
> you find the xdoc templates in the zip at
> http://members.a1.net/berni_huber/doclet-scratchpad.tar.gz
> the userdoc xdoc templates are in generated-reference/userdoc.
> Each sitemap component has its own xdoc template, moreover
> a *-ref.xml (actions-ref.xml, generator-ref.xml,...)
> lists all sitemap components of an category.
>
> Beside generated-testcase has testcase of all real classes of the
cocoon
> project.
>
> Once again, these are javadoc generated files, so don't expect too
much...
Cool stuff! What do we need to make these generated docs better? Where
it gets sitemap definition and sitemap usage snippets? Every particular
component can have many configuration parameters which should be
documented.
Btw, I found a typo in generators-ref.xml: "Sitmap Definition".
Vadim
> bye bernhard
---------------------------------------------------------------------
To unsubscribe, e-mail: cocoon-dev-unsubscribe@xml.apache.org
For additional commands, email: cocoon-dev-help@xml.apache.org