EXist-db coding styleguide

2018-10-15T08:12:44Z

ESiegel: /* Documenting XQuery Modules */

== Documenting XQuery Modules ==

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.
* 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.

=== 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
* 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.

EXist-db coding styleguide

2018-10-15T08:02:39Z

ESiegel: /* Documenting XQuery Modules */

=== Documenting XQuery Modules ===

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.
* 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.

2018-10-01T06:44:23Z

ESiegel: /* Introduction */

=Introduction=

This is a testscenario for ART-DECOR information standards. During the test an ART-DECOR project is reacreated, based on the demo5 project from ART-DECOR examples (see see [[https://art-decor.org/art-decor/decor-project--demo5-]] or [[https://sourceforge.net/p/artdecor/code-0/HEAD/tree/branches/stable/decor/data/examples/demo5/demo5-decor.xml]]).

To execute the scenario, you need at least two user accounts:
# A DBA user for creating the project
# A Project administrator for populating the project

=Steps to perform for this scenario=
==Start with clean setup==
Delete the project if it already exists.
==Create a project test==
See: [[ART_maintenance_manual#Creating_a_project]]

Name: Test: Vital Signs CDA Document

id: 2.16.840.1.113883.2.4.3.11.60.906

prefix: test-

language: en-US

Experimental: yes

Description: Test: Vital Signs Report Summary CDA Document

dataset name: Test dataset

==Project==
General:
Add description

Add building block repositories with prefixes 'ad1bbr-' & 'ad2bbr-' by clicking on the + next to 'Repository references'

==Copyright==
Add a Contributer by clicking the +.
Enter name and contact information.
Add a logo from your computer by clicking on add and then browse.
Enter the correct Copyright years.

==Authors==
Add an author by clicking on the +.
Fill in an name and email-address.

==Ids==
Add external Ids by clicking on the +.
Fill in the Id, Display name and Designation.
For more information check the [[ART_Project_Editor|Project editor manual]].

==Governance==
Make the project member of a governance group: see
For more information check: [[Dealing_with_Governance_Groups|Dealing with governance groups]].

==Dataset==
Add a version label.
Fill in a dataset description, save.
Add concepts by clicking on the + next to Concepts.
Recreate the concept person and underlying concepts from the demo5 project dataset, see [[https://art-decor.org/art-decor/decor-project--demo5-]] or [[https://sourceforge.net/p/artdecor/code-0/HEAD/tree/branches/stable/decor/data/examples/demo5/demo5-decor.xml]]

For the first concept, enter Description, Source, Rationale, Operationalization, Comment.

For each concept:
* Select the right kind of type (group or item)
* Add a name for the concept.
* At 'Value' select the type
To add a new Property click on the + next to the word 'Properties'.
For more information check the [[ART_Dataset_Editor|Dataset editor manual]]

Change the dataset status to final, deprecated.

==Scenarios==
Add a scenario by clicking the + next to Scenarios.
Fill in a name and description and then click save.
Add a transaction group by clicking on the just made scenario. Then click on the first + next to Scenarios.
Fill in a name, label and description for one or both transactions.
Add templates in the concepts section by clicking on the pencil next to the word Template in Concepts.
Select a template and then choose 'Select dynamic' or 'Select static'.
You can add Concepts to the added template by clicking on the pencil next to the word 'Concepts'. This pencil is only visible when the Transaction is not in edit mode, so make sure you save the transaction before trying to add concepts.
To add concepts in the transaction click on the + next to the concepts you want to add.
Click save and then close the window to go back to the transaction.

You can always edit a transaction or transaction group by clicking on it in Scenarios. Then click on the pencil next to the word 'Transaction' to edit.
For more information check the [[ART_Scenario_Editor|Scenario Editor manual]]

==Value Sets in Terminology==
Create a reference to the 'AdministrativeGender' valueset from the bbr.

Create a new valueset.

To add a value set click on the + next to the word 'Value sets'.
A new window opens in which you can fill in the Version label, Display Name (mandatory) and Name (mandatory). The display name may hold spaces but the Name has to be one word.
In Source you have to select and/or add sources. Select ATC, select the correct source from the list and then click Select to activate it.
In Values you can add by clicking on the + on the right.
Fill in a Level en select a Type (L, A, S, D). Also fill in a code (mandatory) and a Display name.
You can add more values by clicking on the little + next to the just added value. You can also delete a value by clicking on the 'x' next to it.
Click on save to save the value set. When the save button is not clickable you probably did not fill in one of the mandatory fields. Also check if the 'Name' really is only one word and if the Code only contains numbers and dots.

You can always edit a value set by clicking on it in Value Sets. Then click on the pencil next to the name of the value set to edit.
For more information check [[ART_Value_Set_Editor|Value Set Editor manual]]

==Templates==
To add a template click on the + next to the word 'Templates'.
A new window opens in which you can select a prototype. For Heart rate choose the CDA Observation template and then click Select.
Now you can fill in a Version label, Display Name and Name.
The display name may hold spaces but the Name has to be one word.
Fill in a description.
Add an Example by clicking on the little + next to the word.
Then add or delete xml attributes by clicking the little + or 'x' next to the attributes.
Click on 'Create template' when you're done. The window will close and you'll be send back to the 'Templates'

You can always edit a template by clicking on it in Templates. Then click on the pencil next to the name of the template to edit.

For more information check the [[ART_Template_Editor|Template editor manual]]

==Issues==
Add an issue: click on the flag on the right.
Select the correct type (incident, change request, for future consideration, request for information/education) and then fill in a title. Also select the desired priority (Lowest, Low, Normal, High, Highest).
Lastly you can fill in a description and assign the issue to an author.
Click on 'Save Issue' to save it.

Search the just created issue: select the correct status, type and priority and then fill in a search term. There will be searched automatically.

For more information check the [[ART_Issues|Issue manual]].