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