Cobble generates documentation from code comments in the XML and makes use of annotations similar to the javadoc tool.

For example:

  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)"/>

XML format

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.
   paragraphs <p> and preformatted text <pre> 
 annotations (see below)

Comment formatting

The current formatting options are rather basic but follow markdown-like syntax.

After the annotations are removed, the rules are as follows:

  1. Consecutive lines of text are interpreted as paragraphs
  2. Lines starting with '-', '+' or '*' are interpreted as list items
  3. Lines starting with a number followed by a dot are interpreted as list items in an ordered list
  4. 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 <>
    • or the markdown like [PageSeeder Open Source](


This will probably be expanded to include basic lists in the future and use smarter rules for detecting code.


Cobble supports the following annotations:

@param [name] [description]Used to document XSLT functions and templates, XML output as
<parameter name="" description=""/>
@author [name]The code author:
<author name=""/>
@return [description]To document what an XSLT template or function returns:
<return description=""/> 
@returns [description]Same as @return
@context [xpath] [description?]To describe the expected context in a match template in XSLT
<context select="" description=""/>
@privateTo describe a template or function as private
<visibility is="private"/>
@publicTo describe a template or function as public
<visibility is="public"/>
@see [url] [description?]To provide a reference (if there is no description, the description is the same as the URL)
<see href="" description=""/>

Any other annotation is preserved and output as:

<annotation name="[name immediately after @]" text="[text after @name]"/>

Created on , last edited on