me, too
I am *strongly* in favor of using special javadoc tags for the Cocoon Components, and I want to make this a standard part in the new Alexandria code documentation process.
Instead of xdoclet it can be very fast to use qdox: http://qdox.sourceforge.net/
The relevant Ant classes: http://qdox.sourceforge.net/xref/com/thoughtworks/qdox/ant/index.html
okay, why do you favour qdox over xdoclet?
This won't happen overnight, but if the system is in place I'm quite sure that people will start moving the documentation in the sources.
see the suggetion of cocoon javadoc tags at the end
just at the weekend, but first finalize the javadoc tags
Do you have time to give qdox a try for Cocoon?
When we have it working, I'll make it part of the Alexandria stuff, so that the documentation will be done by running Alexandria to generate all code docs (xml javadocs, qdox docs, javasrc, xsldoc, etc), and then Forrest for the final rendering and the site.
okay
regards bernhard
*** Motivation
Keeping java code, and documentation about java code together to deliver up-to date reference documentation. Using java doc tags will help generating reference documentation of Cocoon sitemap components.
This document describes using well known javadoc tags for reference documentation. A bunch of new javadoc tags describes Cocoon specific reference documentation requirements.
The processing modell described here uses javadoc tags at class-level, and method-level.
Cocoon specific javadoc tags introduced are always prefixed by cocoon:. For example the cocoon javadoc tag describing the cocoon name of the FileGenerator defines its name as @cocoon:name file.
*** Class Javadoc Tags The following javadoc tags used at class level.
*** Supported Class Javadoc Tags Following well known javadoc tags are supported
@version {version-info} -
VersionControl information pasted to the generated document.
@deprecated {deprecated-info} -
Information why this Cocoon sitemap object is deprecated, additionally what kind of object to use.
@since {Cocoon-Release-Version} -
Information since which Cocoon version this Cocoon sitemap object is available.
Cocoon Class Javadoc Tags
Cocoon class level javadoc tags describes the Cocoon sitemap component attributes.
@cocoon:name {name} -
The default sitemap name of this Cocoon Sitemap component, eg @cocoon:name i18n, @cocoon:name xslt
@cocoon:status [default|core|optional|scratchpad] -
The status of the sitemap component for TraxTransformer @cocoon:status default, for I18N Transformer @cocoon:status core. This information should help sitemap designer to understand if it is "safe" to use this Cocoon sitemap component.
Method Javadoc Tags
The javadoc tags described now are applied on method level, overriding class level javadoc tags. . The naming of the tags are derived from the component interfaces which may, or must be implemented by a Cocoon sitemap component.
*** Configurational Tags
The following tags should be used for Cocoon sitemap components implementing Configurable, Parameterizable, or Contextualizable.
@cocoon:config element="{name}" [parent="{name}"] type="{type-descriptor}" description="{text}" required="yes|no" [default="{default-value}], @cocoon:config attribute="{name}" element="{name}" type="{type-descriptor}" description="{text}" required="yes|no" [default="{default-value}] -
Each @cocoon:config tag describes a single configuration element. e.g.: For I18N Transformer @cocoon:config element="catalogue-name" parent="none" type="string" description="basename of the message catalog" required="yes"
@cocoon:parameter name="{name}" type="{type-descriptor}" description="{text}" required="yes|no" [default="{default-value}] -
Each @cocoon:parameter describes a single parameter entry of a parameter element
@cocoon:context name="{name}" type="{type-descriptor}" description="{text}" required="yes|no" [default="{default-value}] -
Eache @cocoon:context describes a context entry of which the Cocoon sitemap components depends on.
Setup Tags
The following tags should be used for Cocoon sitemap components at the setup method.
@cocoon:setup-src description="{text}" required="yes|no" [default="{default-value}"] -
The javadoc tag @cocoon:setup-src describes the setup parameter src.
@cocoon:setup-parameter name="{name}" type="{type-descriptor}" description="{text}" required="yes|no" [default="{default-value}"] -
The javadoc tag @cocoon:setup-parameter describes the setup parameter Parameters.
@cocoon:request-parameter name="{name}" type="{type-descriptor}" description="{text}" required="yes|no" [default="{default-value}"] -
The javadoc tag @cocoon:request-parameter describes the request parameters of the setup parameter objectModel, retrieved via ObjectModelHelper.getRequest(objectModel).getParameter(name).
@cocoon:request-attribute name="{name}" type="{type-descriptor}" description="{text}" required="yes|no" [default="{default-value}"] -
The javadoc tag @cocoon:request-attribute describes the request attributes of the setup parameter objectModel, retrieved via ObjectModelHelper.getRequest(objectModel).getAttribute(name).
@cocoon:session-attribute name="{name}" type="{type-descriptor}" description="{text}" required="yes|no" [default="{default-value}"] -
The javadoc tag @cocoon:session-attribute describes the session attributes of the setup parameter objectModel, retrieved via ObjectModelHelper.getRequest(objectModel).getSession(false).
*** Samples
The following section gives you some usage scenarios of the javadoc tags described above. It should help you to use the javadoc tags in the java sources, and should verify the useability, and completness of the javadoc tags.
FileGenerator The FileGenerator shall define following javadoc tags
/**
* ....
* @since Cocoon2.0
* @cocoon:name file
* @cocoon:status default
*/
public class FileGenerator ...
...
/**
* Setup the file generator.
*
* @cocoon:setup-src
* description="Specify the URI filename"
* required="yes"
* default-value="none"
*
*/
public void setup(SourceResolver resolver, Map objectModel, String src, Parameters par)
throws ProcessingException, SAXException, IOException {
....
}
...
SessionAttributeGenerator The SessionAttributeGenerator shall define javadoc tags
/**
* ...
* @since Cocoon2.0
* @cocoon:name session-attr
* @cocoon:status core
*/
public class SessionAttributeGenerator ...
/**
* Setup the session-attr generator
*
* @cocoon:setup-src
* description="May specify the session attribute name"
* required="no"
* default-value="none"
* @cocoon:setup-parameter name="attr-name" type="String"
* description="the session attribute name"
* required="no"
* default-value="generator src attribute value"
* @cocoon:setup-parameter name="root-element" type="String"
* description="The root element name of the generated XML"
* required="no"
* default-value="Root element name of session attribute value, if it
* is a DOM object, or XMLizable.
*/
public void setup(SourceResolver resolver, Map objectModel, String src, Parameters par)
throws ProcessingException, SAXException, IOException {
....
}
...
}
WildcardURIMatcher The WildcardURIMatcher shall define following javadoc tags
/**
* ...
* @since Cocoon2.0
* @cocoon:name wildcard
* @cocoon:status default
*
* @cocoon:match-pattern type="Wildcard"
* required="yes"
* description="A wildcard pattern supporting '*' matching any character exception '/',
* and '**' matching any character including '/'"
* default-value="none"
*
* @cocoon:match-string type="String"
* required="no"
* description="The sitemap URI of the current request"
* default-value="sitemap URI"
*/
public class WildcardURIMatcher ...
...
}
DateSelector The DateSelector shall define following javadoc tags
/**
* ...
* @since Cocoon2.1
* @cocoon:name date
* @cocoon:status scratchpad
*/
public class DateSelector ...
...
/**
* Configure the DateSelector
*
* @cocoon:config element="before"
* type="empty"
* parent="map:selector"
* description="Specifies a before selector"
* required="no"
* default="none"
* @cocoon:config attribute="name"
* type="String"
* element="before"
* description="A symbolic name of this selector"
* @cocoon:config attribute="date"
* type="String"
* element="before"
* description="A date value which should be matched by the dateformat attribute value"
* required="yes"
* default="none"
* @cocoon:config attribute="dateformat"
* type="Datepattern String"
* element="before"
* description="A datepattern matching date attribtue value"
* required="no"
* default="HH:mm:ss"
* ...
*/
public void configure(Configuration config) throws ConfigurationException {
...
}
