cocoon sitemap reference pages

[Bernhard Huber <be...@a1.net>]

Hi,

The last day I was trying to auto-generate sitemap reference documentation.

I was implementing a java1.3 doclet extension. This doclet extension uses
Velocity to generate apache document pages for
* Generator
* Transformer
* Serializer
classes.

Each of this classes generates following document elements:
<s2 title="{FQN classname}">
  {first sentence of class javadoc}
  Name {optional @cocoon:name javadoc tag}
  Class {FQN classname}
  Cacheable {true if class implements Cacheable}
  AllInterfaces {list of all implementing interfaces}
  AllSuperclasses {list of all superclasses}

  <s3 title="Sitemap Definition">
    <source>
       ... <map:generator name="{@cocoon:name}" src="{FQN classname}"/> ...
    </source>
  </s3>
  <s3 title="Sitemap Usage">
    ... <map:generate name="{@cocoon:name}"/>...
  </s3>
</s2>

As of today some javadocs has html tags in the javadoc which makes troubles
in the "build docs" document generation.

This effort might help to have uptodate documentation, as it is 
generated directly from the
java source code.
This effort does not replace writting documentation, but it might help.

Currently only the javadoc tag @cocoon:name is respected.
Maybe defining more tags might enrich the reference documents further.

The reference documentation step should happen before launching "build 
docs".
The files generators-ref.xml, transformers-ref.xml, and 
serializers-ref.xml are generated
by the reference documetation step.

Any ideas?

bye bernhard



---------------------------------------------------------------------
To unsubscribe, e-mail: cocoon-dev-unsubscribe@xml.apache.org
For additional commands, email: cocoon-dev-help@xml.apache.org

Re: cocoon sitemap reference pages

[David Crossley <cr...@indexgeo.com.au>]

Bernhard Huber wrote:
>The last day I was trying to auto-generate sitemap reference documentation.

This is an excellent idea Bernhard. I, for one, would encourage
you to continue with it.

>I was implementing a java1.3 doclet extension. This doclet extension uses
>Velocity to generate apache document pages for
>* Generator
>* Transformer
>* Serializer
>classes.
>
>Each of this classes generates following document elements:
><s2 title="{FQN classname}">
>  {first sentence of class javadoc}
>  Name {optional @cocoon:name javadoc tag}
>  Class {FQN classname}
>  Cacheable {true if class implements Cacheable}
>  AllInterfaces {list of all implementing interfaces}
>  AllSuperclasses {list of all superclasses}
>
>  <s3 title="Sitemap Definition">
>    <source>
>       ... <map:generator name="{@cocoon:name}" src="{FQN classname}"/> ...
>    </source>
>  </s3>
>  <s3 title="Sitemap Usage">
>    ... <map:generate name="{@cocoon:name}"/>...
>  </s3>
></s2>
>
>As of today some javadocs has html tags in the javadoc
>which makes troubles in the "build docs" document generation.

Are you seeing this as a hurdle, or simply as something
that needs to be amended before your application can
proceed?

I do not understand why such elements cause trouble.
Can you provide an example? If they are not valid elements
according to the document-v10.dtd then surely we can
simply tweak the javadoc comments inside each *.java

In your example above, do you intend to have <p> wrappers
around each information line following the <s2 title="...
so as to provide the layout that you have shown? If so,
then i can see how that may cause troubles with embedded
elements. We could simply define a coding convention for
the "{first sentence of class javadoc}".
--David

>This effort might help to have uptodate documentation, as it is 
>generated directly from the java source code.
>This effort does not replace writting documentation, but it might help.
>
>Currently only the javadoc tag @cocoon:name is respected.
>Maybe defining more tags might enrich the reference documents further.
>
>The reference documentation step should happen before launching
>"build docs". The files generators-ref.xml, transformers-ref.xml, and 
>serializers-ref.xml are generated by the reference documetation step.
>
>Any ideas?
>
>bye bernhard


---------------------------------------------------------------------
To unsubscribe, e-mail: cocoon-dev-unsubscribe@xml.apache.org
For additional commands, email: cocoon-dev-help@xml.apache.org