We know how useful are javadocs. Cocoon users are also important XML code producers (*.xmap, *.xsl, *.xsp ...). Problem is, there is not yet a standard way to comment such code. Is a kind of "xmldoc" possible ?

FredericGlorieux <<MailTo(frederic DOT glorieux AT xfolio DOT org)>>

After create and maintain different Cocoon Apps, with different people, I definitely wait for the best solution to document XML code files. Think especially about XSL, where you can find very clever and tricky XPath expression, so that it is quite impossible to understand them 3 months after (Imagine I have in more than one place things like <!-- It works, but can't remember how -->.

Docbook Project have probably the longest experience of a big XSL project to administrate, with so much users that the pack had to be documented in a full book. I spent time to understand their logic, interesting. A namespace in XSL is devoted to documentation. But this can't be a generic solution for all kind of XML code files. Have you ever try to mix contents in *.xmap <map:sitemap xmlns:map="http://apache.org/cocoon/sitemap/1.0"/> ?

The best is then probably to keep it simple, and use what is done for : <!-- the comments -->. So, inside, only text, no tags. By the way, isn't it the kind of syntax of this Wiki ? Instead of the every time licence declaration, the first comment could be a complete Wiki page describing the file ? Perhaps some knows, but Cocoon is also able to parse such things (forrest, chaperon). So it's perhaps possible to begin a simple light XML Code Documentation System. An XSL template could be :

<?xml version="1.0" encoding="UTF-8"?>
<!--

= WHAT =

Little abstract:
This is a cocoon sitemap [http://cocoon.apache.org/2.1/userdocs/concepts/sitemap.html]

= WHO =

Copyright 1999-2004 The Apache Software Foundation
[http://www.apache.org/licenses/LICENSE-2.0 Apache Licence]
 * [[Anchor(SM)]]StefanoMazzocchi [[MailTo(stephano AT apache DOT org)]]

= HOW =

How to use

= WHY =

More on logic

= CHANGES =

 * 2004-07-14:[#SM]  I'm alive

= TODO =

So much...

-->
<map:sitemap xmlns:map="http://apache.org/cocoon/sitemap/1.0"/>

with this effect

WHAT

Little abstract:
This is a cocoon sitemap http://cocoon.apache.org/2.1/userdocs/concepts/sitemap.html

WHO

Copyright 1999-2004 The Apache Software Foundation Apache Licence

  • StefanoMazzocchi <<MailTo(stephano AT apache DOT org)>>

HOW

How to use

WHY

More on logic

CHANGES

  • 2004-07-14:#SM I'm alive

TODO

So much...

References

See Also

about documentation

<<PageList(docs

doco)>>

cited by

with the authors

<<FullSearch>>

<<FullSearch('FredericGlorieux')>>

  • No labels