Difference between revisions of "EXist-db coding styleguide"

(Documenting XQuery Modules)
Line 1: Line 1:
== Documenting XQuery Modules ==
+
=== Documenting XQuery Modules ===
  
 
For documenting XQuery ''modules'' (function libraries), eXist supports a subset of the ''xqDoc'' standard (see the
 
For documenting XQuery ''modules'' (function libraries), eXist supports a subset of the ''xqDoc'' standard (see the
[http://xqdoc.org/index.html xqDoc site], especially [http://xqdoc.org/xqdoc_comments_doc.html xqDoc comments]).
+
[http://xqdoc.org/index.html xqDoc site], especially [http://xqdoc.org/xqdoc_comments_doc.html xqDoc comments]). Modules documented this way automagically show up in the eXist Function Documentation app.
  
=== Basic rules and limitations ===
+
==== Basic rules and limitations ====
  
* An xqDoc comment starts with a
+
* 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.

Revision as of 08:02, 15 October 2018

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.