Difference between revisions of "EXist-db coding styleguide"

(Function comments)
(Function comments)
Line 40: Line 40:
 
Example:
 
Example:
 
  (:~
 
  (:~
   Return zero or more templates as-is wrapped in a <return> element, and subsequently inside one or more <template> elements for
+
   Return zero or more templates as-is wrapped in a <return> element, and subsequently  
   server local repositories that aren't private and either refer to or define the requested template(s).  
+
  inside one or more <template> elements for
 +
   server local repositories that aren't private and either refer to or define the requested  
 +
  template(s).  
 
      
 
      
 
   @param $id Identifier of the template to retrieve
 
   @param $id Identifier of the template to retrieve

Revision as of 08:27, 15 October 2018

Documenting XQuery Modules with xqDoc

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 inbetween.
  • Do not add @version and @author information, leave this to the version control system.

Example:

(:~
 Module for handling templates in ART-DECOR.
 
 A template is a ... that ... and ... etc.
:)

Function comments

  • xqDoc function comments must be placed directly before the function itself (before the declare function ...)
  • Describe what the function is for in general terms.
  • Describe all the function's parameters with @param keywords.
  • Describe the function's return value with a @return keyword.
  • If the function needs more extensive documentation (e.g. details with lots of XPath expressions or whatever), add this as a normal comment to the function's body. The xqDoc part will be visible in the function documentation browser and its best to keep things short and concise there. People that are in need of more details usually can and will look into the code anyway.
  • A module header comment does not supports paragraphs of text. The function documentation browser will show all as a single paragraph, no matter how many empty lines you add.
  • Do not add @version and @author information, leave this to the version control system.

Example:

(:~
 Return zero or more templates as-is wrapped in a <return> element, and subsequently 
 inside one or more <template> elements for
 server local repositories that aren't private and either refer to or define the requested 
 template(s). 
    
 @param $id Identifier of the template to retrieve
 @param $flexibility () gets all versions, yyyy-mm-ddThh:mm:ss gets this specific version, ...
 @return Matching templates in <return> element
:)
declare function templ:getTemplateById (
  $id as xs:string, 
  $flexibility as xs:string?
) as element(return) 
{
   ...
};

Documenting XQuery Scripts

Big parts of art-decor's functionality are implemented as XQuery scripts (although these are, confusingly, often in collections called modules). Unfortunately there is nothing like xqDoc for this.

Nonetheless the advice is to add at least a descriptive comment at the start of the script that describes:

  • Describes what the script is for, explain key concepts, etc. Try to write something that a developer with a basic knowledge of art-decor can understand.
  • What its (request) parameters are (if any)
  • Other important dependencies (like session parameters, etc.)
  • Do not add version and author information, leave this to the version control system.