cocoon-docs mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Bernhard Huber <berni_hu...@a1.net>
Subject Re: Documentation Format...
Date Sun, 17 Nov 2002 15:11:26 GMT

> 
> 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
> 
> 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