Cobble generates documentation from code comments in the XML and makes use of annotations similar to the javadoc tool.
<!-- This function is only defined for demonstration purposes @param foo The argument we have to have @return Something maybe --> <xsl:function name="my:doSomething" as="xs:string?"> <xsl:param name="foo" as="element(bar)"/> </xsl:function>
The generated XML is the same as the source code, except that:
- the body of XSLT templates and function isn't included
- the code comments are replaced by XML following the format below.
<doc> <description> paragraphs <p> and preformatted text <pre> </description> annotations (see below) </doc>
The current formatting options are rather basic but follow markdown-like syntax.
After the annotations are removed, the rules are as follows:
- Consecutive lines of text are interpreted as paragraphs
- Lines starting with '-', '+' or '*' are interpreted as list items
- Lines starting with a number followed by a dot are interpreted as list items in an ordered list
- Lines starting with at least 4 spaces are interpreted as preformatted text
Within paragraphs and list items, Cobble will also recognise:
- Emphases when wrapping text in single '*' or '_' (e.g. *important*)
- Strong emphases when wrapping text in a double '*' or '_' (e.g. __very important__)
- Code when wrapping text in single left quotes '`'
- Links when
- wrapping an address with angle brackets <http://pageseeder.org>
- or the markdown like [PageSeeder Open Source](http://pageseeder.org)
NoteThis will probably be expanded to include basic lists in the future and use smarter rules for detecting code.
Cobble supports the following annotations:
|Used to document XSLT functions and templates, XML output as|
|The code author:|
|To document what an XSLT template or function returns:|
|Same as @return|
|To describe the expected context in a match template in XSLT|
|To describe a template or function as private|
|To describe a template or function as public|
|To provide a reference (if there is no description, the description is the same as the URL)|
Any other annotation is preserved and output as:
<annotation name="[name immediately after @]" text="[text after @name]"/>
Created on , last edited on