EXist-db coding styleguide - Revision history

ESiegel: /* Function comments */

2018-10-29T07:42:37Z

‎Function comments

2018-10-15T08:32:22Z

‎Header comments

2018-10-15T08:31:39Z

‎Copyright statement

2018-10-15T08:30:32Z

‎Documenting XQuery Modules with xqDoc

2018-10-15T08:28:59Z

‎Basic rules and limitations

2018-10-15T08:28:28Z

‎Basic rules and limitations

2018-10-15T08:27:52Z

‎Function comments

2018-10-15T08:27:11Z

‎Function comments

2018-10-15T08:24:54Z

‎Header comments

2018-10-15T08:21:43Z

‎Documenting XQuery Modules

@@ Line 56: / Line 56: @@
 * 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.
+* 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.

@@ Line 42: / Line 42: @@
 Example:
   (:~
    Module for handling templates in ART-DECOR.

@@ Line 1: / Line 1: @@
 == Copyright statement ==
-Due to legal stuff, every module and script  '''must''' start with  copyright info. Put this directly below the descriptive comment.
+Due to legal stuff, every module and script  '''must''' start with  copyright info. Put this directly below the starting descriptive comment.
   (:

← Older revision		Revision as of 08:30, 15 October 2018
Line 1:		Line 1:
		+	== Copyright statement ==
		+
		+	Due to legal stuff, every module and script '''must''' start with copyright info. Put this directly below the 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 ==		== Documenting XQuery Modules with xqDoc ==

@@ Line 8: / Line 8: @@
 * 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 > with the comments
+* 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:

@@ Line 40: / Line 40: @@
 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
    @param $id Identifier of the template to retrieve

@@ Line 20: / Line 20: @@
 * 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 ===

← Older revision		Revision as of 08:21, 15 October 2018
Line 1:		Line 1:
−	== Documenting XQuery Modules ==	+	== Documenting XQuery Modules with xqDoc ==

	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