Cobble

  1. Home
  2. projects
  3. cobble
  4. format
 

Format

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)"/>
</xsl:function>

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

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 <http://pageseeder.org>
    • or the markdown like [PageSeeder Open Source](http://pageseeder.org)

Note

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

Annotations

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