cocoon-docs mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From David Crossley <cross...@indexgeo.com.au>
Subject Re: Documentation Format...
Date Tue, 19 Nov 2002 07:49:51 GMT
Bernhard Huber wrote:
> Nicola Ken Barrozzi wrote:
> > Bernhard Huber wrote:
> > <snip/>
> > 
> > > Probably it's a lot of work change all sitemap component sources,
> > > and describe a coding standard for submitting only
> > > components sticking to the cocoon java doc tags.
> >
> > 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.
>
> me, too
>
> > 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
> 
> > Do you have time to give qdox a try for Cocoon?
>
> just at the weekend, but first finalize the javadoc tags

I think that this is the place where we got stuck the last
time this was proposed ... defining the set of javadoc attributes
to use. Berni did propose something, but the discussion did not
go far.

This time will be different. Berni has them defined down below.
Would it be possible to just get started using that set, limit
our work to just a couple of components, describe those well,
generate their reference documentation only, get the
infrastructure in place, review those docs and finalise the
set of javadoc tags. Then start to gradually add content to
the other components.

This was an idea in another cocoon-dev thread where we are
developing the RELAX NG grammar for the sitemap. I suggested
that we discuss each component in turn on the list to finalise
its parameters and usage. This way we all learn about the guts
of Cocoon, the whole thing gets polished, and we get good
reference docs at the end.

> > 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 {
>      ...
>    }
> 
> 
> 



Mime
View raw message