EXist-db coding styleguide

Documenting XQuery Modules

For documenting XQuery modules (function libraries), eXist supports a subset of the xqDoc standard (see the xqDoc site, especially xqDoc comments). Modules documented this way automagically show up in the eXist Function Documentation app.

Basic rules and limitations

• An xqDoc comment starts with a (:~ and ends with a :)
• You can start a line inside the xqDoc comment with a colon : but its probably easier without and that works just as well.
• Never us a @ inside a comment (probably the eXist parser thinks its the start of a keyword even when its not the first word of a line). This unfortunately makes it impossible to add XPath expressions with attribute references.
• Not all keywords are recognized (especially @see is an unfortunate omission). Best to limit the keyword usage to:
  • @param for function parameters
  • @return for return values
• @version and @author are also supported but have the tendency to get outdated very soon because people forget to update them. Since this information is automatically maintained by the version control system anyway, advice is not to use them.

Header comments

• An xqDoc header comment must be the first comment block in an XQuery module (underneath the XQuery declaration xquery version "...";).
• Describe what the module is for, explain key concepts, etc. Try to write something that a developer with a basic knowledge of art-decor can understand.
• A module header comment supports paragraphs of text. To start a new paragraph add an empty line.
• Do not add @version and @author information, leave this to the version copntrol system.