cocoon-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From David Crossley <cross...@indexgeo.com.au>
Subject Re: cocoon sitemap reference pages
Date Tue, 15 Jan 2002 06:28:24 GMT
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


Mime
View raw message