cocoon-docs mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Apache Wiki <wikidi...@apache.org>
Subject [Cocoon Wiki] Update of "CocoonRefDocProject" by BertrandDelacretaz
Date Tue, 07 Jun 2005 10:03:12 GMT
Dear Wiki user,

You have subscribed to a wiki page or wiki category on "Cocoon Wiki" for change notification.

The following page has been changed by BertrandDelacretaz:
http://wiki.apache.org/cocoon/CocoonRefDocProject

------------------------------------------------------------------------------
  
  The main goal is to generate reference documentation for Cocoon itself, in XML form which
will be converted to HTML for web publication, either using Forrest, Daisy or a specific mechanism.
  
- = Current situation =
+ = Current situation and goals =
  Although there are quite a lot of documents, the Cocoon documentation is not well organized
and information is hard to find.
  
  Realizing that the many existing examples are often the best source of precise information,
this project aims to extract the reference information directly from the source code, by annotating
the code and extracting snippets of information from the various files (java code, sitemaps,
configuration files, XML input files, XSLT stylesheets, etc) which compose a Cocoon example
or application.
@@ -21, +21 @@

  = Use-cases =
  
  == Annotating XML code ==
+ Here's an example of annotating a sitemap.
+ 
+ Markers in XML comments are used to mark sections of code, and to give them "doktor attributes"
which are used to organize and sort the code snippets (doktor is the current codename for
the DOKumentation extracTOR, the component which will extract and organize the snippets).
+ 
+ {{{
+       <!-- @doktor-start type:pipeline key:FirstExample -->
+       <map:match pattern="dummy-sitemap">
+           <map:read src="index.html"/>
+       </map:match>
+ 
+       <map:match pattern="*/dummy/**">
+         <map:mount check-reload="yes" src="{1}/" uri-prefix="{1}"/>
+       </map:match>
+       <!-- @doktor-end -->
+ }}}
+ In that case, the snippet includes the next two <map:match> elements, and will be
attached to the FirstExample document that the system will generate by aggregating all snippets
having the same key.
+ {{{
+       <!-- @doktor-element type:pipeline -->
+       <map:match pattern="snippets/**">
+         ...
+       </map:match>
+ }}}
+ With the '@doktor-element' marker selects the following element only as a snippet.
+ 
+ By default, the 'key:' property is the last one declared in the same document, so this snippet
would also be attached to the FirstExample document.
  
  == Annotating java code ==
+ Here's an example of annotated java code:
+ {{{
+ /** This class shows example of doktor annotations, which the
+  *  doktor extractor uses to generate documentation snippets.
+  *
+  *  key: sets the current snippet key
+  *  @doktor key:firstExample
+  *
+  *  @doktor-start
+  *      Everything between -start and -end annotations is collected
+  *      as part of the snippet content.
+  *  @doktor-end
+  *
+  *  @doktor-start type:warning
+  *      Here a name-value pair after doktor-start is used to set the
+  *      type of the annotation. This will be published as a warning
+  *  @doktor-end
+   */
+ public class AnnotatedClass {
+ 
+     /** @doktor-start type:code
+      *  To include code in a doktor annotation, surround it with
+      *  -start and -end doktor tags
+      * */
+     public void someFunction() {
+         for(int i=0; i < 10; i++) {
+             final int nothingUseful = i;
+         }
+     }
+     /** @doktor-end */
+ }
+ }}}
+ In the first version, the snippet extractor won't know about the java syntax, as it is not
meant to replace javadoc, but more to provide an overview of the application and data flow.
  
  == Annotating other source code ==
+ Other text source files (.txt, .properties, etc.) are annotated as in the java code example,
and the same parser is used to extract them.
  
  == Extracting and indexing documentation snippets ==
  
+ 
  == Accessing a single document ==
+ 
  
  == Publishing the generated docs ==
  

Mime
View raw message