Merge pull request #321 from Edirom/ftr/contributing-xqDoc-and-typos

restructure add section on xqDoc fix typos

CONTRIBUTING.md

@@ -2,47 +2,57 @@
 
 # General Guidelines
 
-* do not combine code-linting and contet work in one commit
+* do not combine code-linting and content work in one commit
 
 ## Whitespace handling
 
 1. Use whitespaces, not tabs to indent code
-2. Close file with newline character 
+2. Close file with a newline character
 
 
 # XQuery
 
-## XQuery version
+## xqDoc
+
+We use [xqDoc](https://xqdoc.org) for documenting the XQueries in this repository. Please refer to the section [xqDoc Comments](https://xqdoc.org/xqdoc_comments_doc.html) of the xyDoc-website for details on formatting the documentation comment blocks.
+
+* XQuery modules must have a library module xqDoc comment preceding the module declaration.
+* Function declarations must have a library module xqDoc function comment preceding the function.
+
+## XQuery document structure
+
+### XQuery version
 
 ```xquery
-xquery version 3.1
+xquery version 3.1;
 ```
 
-## Version Statement
+### License Statement
 
 ```xquery
 (:
-For LICENSE-Details please refer to the LICENSE file in the root directory of this repository. 
+For LICENSE-Details please refer to the LICENSE file in the root directory of this repository.
 :)
 ```
 
-## Module imports
-
-1. declare namespaces
-2. import module namespaces of registered modules
-3. import module namespaces of custom modules
+### File Header
 
-* Sort all three alphabetically.
-* Always use relative URIs for `import module namespace` statements that import for modules not registered with eXist-db.
+1. `declare namespace` statements
+   * sort alphabetically by prefix
+2. `import module namespace` statements of registered modules
+   * sort alphabetically by prefix
+3. `import module namespace` statements of custom modules
+   * sort alphabetically by prefix
+   * Always use relative URIs for `import module namespace` statements that import for modules not registered with eXist-db.
 
-## Declare variables
+### Declare variables
 
-* Use declare function statements for all required external parameters
+* Use `declare variable` statements for all required external parameters
 
-## Function declarations
+### Function declarations
 
-* functions have to be preceeded by a XQDoc code-block
+* functions have to be preceded by an xqDoc comment
 
-## Strings
+### XQuery body
 
-* escape with single upper straight quote  
+* Strings: escape with U+00027 APOSTROPHE: `'`