View source for EXist-db coding styleguide

== Copyright statement ==

Due to legal stuff, every module and script  '''must''' start with  copyright info. Put this directly below the starting descriptive comment.

 (: 
  Copyright © ART-DECOR Expert Group and ART-DECOR Open Tools
  See https://art-decor.org/mediawiki/index.php?title=Copyright
   
  This program is free software; you can redistribute it and/or modify it under the terms of the
  GNU Lesser General Public License as published by the Free Software Foundation; either version
  2.1 of the License, or (at your option) any later version.
  
  This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY;
  without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
  See the GNU Lesser General Public License for more details.
  
  The full text of the license is available at http://www.gnu.org/copyleft/lesser.html
 :)

== Documenting XQuery Modules with xqDoc ==

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]). 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.
* You're allowed to use < and > within the comments, so you can write element names with angle brackets
* 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:
 xquery version "3.0";
 (:~
  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 function 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.