<html><head><meta http-equiv="Content-Type" content="text/html; charset=utf-8"></head><body style="word-wrap: break-word; -webkit-nbsp-mode: space; line-break: after-white-space;" class=""><br class=""><div><span style="font-size: medium;" class="">Announcing an updated xqDoc (</span><a href="http://xqdoc.org/" class="">http://xqdoc.org</a><span style="font-size: medium;" class="">) XQuery code documentation generator!</span><br class=""><div class=""><div style="word-wrap: break-word; -webkit-nbsp-mode: space; line-break: after-white-space;" class=""><div class=""><font size="3" class=""><br class=""></font></div><div class=""><font size="3" class="">Thank you to Darin McBeath and Curt Kohler from Elsevier that originally developed xqDoc.<br class=""></font><div class=""><font size="3" class=""><br class=""></font></div><div class=""><font size="3" class="">The previous version had not been updated to deal with the recent additions to the XQuery grammar. It was also developed using Antlr 2 and Antlr 4 is the current release. Antlr 4 allows for the separation of the parsing of the grammar and the visiting of the parsed grammar. This allows for the grammar file to be utilized for other parsing reasons by writing a new visitor class.<br class=""></font><div class=""><font size="3" class=""><br class=""></font></div><div class=""><font size="3" class="">The source is available at: <a href="https://github.com/lcahlander/xqdoc" class="">https://github.com/lcahlander/xqdoc</a> and the jar file is available through the maven repository <a href="https://mvnrepository.com/artifact/org.xqdoc/xqdoc" class="">https://mvnrepository.com/artifact/org.xqdoc/xqdoc</a></font></div><div class=""><br class=""></div><div style="font-size: 25px;" class="">1.0 Additions</div><div class=""><font size="3" class=""><br class=""></font></div><div class=""><span style="font-size: inherit;" class="">The parsing of the content of a function signature was in the specification, but not in the available codebase.</span></div><div class=""><font size="3" class="">The following XQuery function now generates parameter, return type and annotation tags within the function xqDoc tag.</font></div><div class=""><font size="3" class=""><br class=""></font></div><div class=""><div class=""><span style="font-size: 22px;" class="">1.1 Function Signature</span></div><div class=""><span style="font-size: 22px;" class=""><br class=""></span></div><div style="margin: 0px; font-stretch: normal; line-height: normal; color: rgb(0, 100, 0);" class=""><font size="3" class=""><span style="color: #0000e6" class=""><b class="">declare</b></span><span style="" class=""><br class="">
</span>%rest:GET<span style="" class=""><br class="">
</span>%rest:path("/test2")<span style="" class=""><br class="">
</span>%rest:query-param("hello", "{$hello}", "")<span style="" class=""><br class="">
</span><span style="color: #0000e6" class=""><b class="">function</b></span><span style="" class=""> </span><span style="color: #004000" class=""><i class="">test:hello2</i></span><span style="" class="">(</span><span style="color: #963296" class=""><b class="">$hello</b></span><span style="" class=""> </span><span style="color: #0096c8" class=""><b class="">as</b></span><span style="" class=""> </span><span style="color: #0000e6" class=""><b class="">xs:string</b></span><span style="color: #787800" class="">*</span><span style="" class="">) <br class="">
</span><span style="color: #0096c8" class=""><b class="">as</b></span><span style="" class=""> </span><span style="color: #004000" class=""><i class="">node</i></span><span style="" class="">() <br class="">
{<br class="">
</span><span style="color: #0000e6" class=""><hello></span><span style="" class="">{</span><span style="color: #963296" class=""><b class="">$hello</b></span><span style="" class="">}</span><span style="color: #0000e6" class=""></hello></span><span style="" class=""><br class="">
}</span><span style="color: #787800" class="">;</span><span style="" class=""><br class="">
</span></font></div></div><div class=""><span style="color: #787800" class=""><br class=""></span></div><div class=""><font size="3" class=""><br class=""></font></div><div class=""><span style="font-size: 19px;" class="">1.1.1 Parameters</span></div><div class=""><span style="font-size: 22px;" class=""><br class=""></span></div><div class=""><div style="margin: 0px; font-stretch: normal; line-height: normal; color: rgb(0, 0, 150);" class=""><font size="3" class=""><span style="" class=""> </span><xqdoc:parameters><span style="" class=""><br class="">
</span><xqdoc:parameter><span style="" class=""><br class="">
</span><xqdoc:name><span style="" class="">hello</span></xqdoc:name><span style="" class=""><br class="">
</span><xqdoc:type<span style="color: #f5844c" class=""> occurrence</span><span style="color: #ff8040" class="">=</span><span style="color: #993300" class="">"*"</span>><span style="" class="">xs:string</span></xqdoc:type><span style="" class=""><br class="">
</span></xqdoc:parameter><span style="" class=""><br class="">
</span></xqdoc:parameters><span style="" class=""><br class="">
</span></font></div></div><div class=""><br class=""></div><div class=""><span style="font-size: 19px;" class="">1.1.2 Return Types</span></div><div class=""><br class=""></div><div class=""><br class=""></div><div class=""><div style="margin: 0px; font-stretch: normal; line-height: normal; font-size: 16px;" class="">
<span style="color: #000096" class=""><xqdoc:return></span><br class="">
<span style="color: #000096" class=""><xqdoc:type</span><span style="color: #f5844c" class=""> occurrence</span><span style="color: #ff8040" class="">=</span><span style="color: #993300" class="">"*"</span><span style="color: #000096" class="">></span>node()<span style="color: #000096" class=""></xqdoc:type></span><br class="">
<span style="color: #000096" class=""></xqdoc:return></span><br class="">
</div></div><div class=""><span style="color: #000096" class=""><br class=""></span></div><div class=""><br class=""></div><div class=""><div class=""><span style="font-size: 19px;" class="">1.1.3 Annotations</span></div><div class=""><br class=""></div><div class=""><div style="margin: 0px; font-stretch: normal; line-height: normal; color: rgb(0, 0, 150);" class=""><font size="3" class=""><span style="" class=""> </span><xqdoc:annotations><span style="" class=""><br class="">
</span><xqdoc:annotation<span style="color: #f5844c" class=""> name</span><span style="color: #ff8040" class="">=</span><span style="color: #993300" class="">"rest:GET"</span>/><span style="" class=""><br class="">
</span><xqdoc:annotation<span style="color: #f5844c" class=""> name</span><span style="color: #ff8040" class="">=</span><span style="color: #993300" class="">"rest:path"</span>><span style="" class=""><br class="">
</span><xqdoc:literal><span style="" class="">"/test2"</span></xqdoc:literal><span style="" class=""><br class="">
</span></xqdoc:annotation><span style="" class=""><br class="">
</span><xqdoc:annotation<span style="color: #f5844c" class=""> name</span><span style="color: #ff8040" class="">=</span><span style="color: #993300" class="">"rest:query-param"</span>><span style="" class=""><br class="">
</span><xqdoc:literal><span style="" class="">"hello"</span></xqdoc:literal><span style="" class=""><br class="">
</span><xqdoc:literal><span style="" class="">"{$hello}"</span></xqdoc:literal><span style="" class=""><br class="">
</span><xqdoc:literal><span style="" class="">""</span></xqdoc:literal><span style="" class=""><br class="">
</span></xqdoc:annotation><span style="" class=""><br class="">
</span></xqdoc:annotations><span style="" class=""><br class="">
</span></font></div></div><div class=""><br class=""></div><div class=""><div class=""><span style="font-size: 22px;" class="">1.2 Custom Comment Tag</span></div></div><div class=""><span style="color: rgb(36, 41, 46); font-family: -apple-system, system-ui, "Segoe UI", Helvetica, Arial, sans-serif, "Apple Color Emoji", "Segoe UI Emoji", "Segoe UI Symbol"; font-size: 16px; font-variant-ligatures: normal; orphans: 2; widows: 2; background-color: rgb(255, 255, 255);" class=""><br class=""></span></div><div class=""><span style="background-color: rgba(255, 255, 255, 0);" class=""><font size="3" class=""><span style="font-variant-ligatures: normal; orphans: 2; widows: 2;" class="">The @custom tag identifies a tag for any other purpose. If the @custom is followed immediately by a colon, then that value is in the tag attribute of the custom tag. e.g. </span><code style="box-sizing: border-box; border-top-left-radius: 3px; border-top-right-radius: 3px; border-bottom-right-radius: 3px; border-bottom-left-radius: 3px; margin: 0px; padding: 0.2em 0.4em; font-variant-ligatures: normal; orphans: 2; widows: 2;" class=""><font face="Helvetica" class=""><b class="">@custom:openapi</b></font></code><span style="font-variant-ligatures: normal; orphans: 2; widows: 2;" class=""> creates the tag </span></font></span><font size="3" class=""><span style="color: rgb(0, 0, 150);" class=""><xqdoc:custom</span><span style="color: rgb(245, 132, 76);" class=""> tag</span><span style="color: rgb(255, 128, 64);" class="">=</span><span style="color: rgb(153, 51, 0);" class="">"openapi”></span><span style="color: rgb(0, 0, 150);" class=""></xqdoc:custom></span></font></div><div class=""><span style="color: rgb(0, 0, 150);" class=""><br class=""></span></div><div class=""><code style="box-sizing: border-box; border-top-left-radius: 3px; border-top-right-radius: 3px; border-bottom-right-radius: 3px; border-bottom-left-radius: 3px; margin: 0px; padding: 0.2em 0.4em; font-variant-ligatures: normal; orphans: 2; widows: 2; background-color: rgba(255, 255, 255, 0);" class=""><font face="Helvetica" size="4" class="">I am working on an XQuery script that will take information from the generated xqDoc from the src/main/ml-modules/services/*.xqy files and generate OpenAPI and RAML documentation.</font></code></div><div class=""><code style="box-sizing: border-box; border-top-left-radius: 3px; border-top-right-radius: 3px; border-bottom-right-radius: 3px; border-bottom-left-radius: 3px; margin: 0px; padding: 0.2em 0.4em; font-variant-ligatures: normal; orphans: 2; widows: 2; background-color: rgba(255, 255, 255, 0);" class=""><font face="Helvetica" size="4" class=""><br class=""></font></code></div><div class=""><code style="box-sizing: border-box; border-top-left-radius: 3px; border-top-right-radius: 3px; border-bottom-right-radius: 3px; border-bottom-left-radius: 3px; margin: 0px; padding: 0.2em 0.4em; font-variant-ligatures: normal; orphans: 2; widows: 2; background-color: rgba(255, 255, 255, 0);" class=""><font face="Helvetica" size="4" class="">NOTE: All comment tags allow for multiple lines of text.</font></code></div><div class=""><br class=""></div><div class=""><br class=""></div><div class=""><span style="font-size: 25px;" class="">2.0 MarkLogic ML Gradle additions to a build.gradle</span></div><div class=""><br class=""></div><div class=""><font size="3" class="">The following is a sample build.gradle file. If you add the contents of <a href="https://github.com/lcahlander/marklogic-xqdoc-display" class="">https://github.com/lcahlander/marklogic-xqdoc-display</a> into <span style="font-size: 19px;" class="">src/main/ml-modules/root/xqDoc</span>, then you will be able to view the xqDoc documentation of your XQuery code (</font><a href="http://localhost:8011/xqDoc" class="">http://localhost:8011/xqDoc</a><span style="font-size: inherit;" class="">). A sample of the display i</span><font size="3" class="">s at: <a href="http://xqdoc.org/enhanced/default.html" class="">http://xqdoc.org/enhanced/default.html</a></font></div><div class=""><br class=""></div><div class=""><div class="">gradle generateXQDocs</div></div><div class=""><div class="">gradle importXQDoc</div></div><div class=""><br class=""></div><div class=""><br class=""></div><div class=""><pre style="background-color: rgb(255, 255, 255); font-family: Menlo;" class=""><b class=""><font size="3" class=""><span style="color: rgb(0, 0, 67);" class="">import </span>org.apache.tools.ant.filters.BaseFilterReader<br class=""></font></b><span style="font-size: 9pt;" class=""><br class="">buildscript {<br class=""> repositories {<br class=""> jcenter()<br class=""> }<br class=""><br class=""> dependencies {<br class=""></span><font size="3" class=""> classpath <span style="color: rgb(0, 128, 0); font-weight: bold;" class="">"org.xqdoc:xqdoc:1.9.3"<br class=""></span></font><span style="font-size: 9pt; color: rgb(0, 128, 0); font-weight: bold;" class=""> </span><span style="font-size: 9pt;" class="">}<br class="">}<br class=""><br class="">plugins {<br class=""> id </span><span style="font-size: 9pt; color: rgb(0, 128, 0); font-weight: bold;" class="">"net.saliman.properties" </span><span style="font-size: 9pt;" class="">version </span><span style="font-size: 9pt; color: rgb(0, 128, 0); font-weight: bold;" class="">"1.4.6"<br class=""></span><span style="font-size: 9pt; color: rgb(0, 128, 0); font-weight: bold;" class=""> </span><span style="font-size: 9pt;" class="">id </span><span style="font-size: 9pt; color: rgb(0, 128, 0); font-weight: bold;" class="">"com.marklogic.ml-gradle" </span><span style="font-size: 9pt;" class="">version </span><span style="font-size: 9pt; color: rgb(0, 128, 0); font-weight: bold;" class="">"3.6.0"<br class=""></span><span style="font-size: 9pt;" class="">}<br class=""><br class="">repositories {<br class=""> jcenter()<br class=""> maven { url </span><span style="font-size: 9pt; color: rgb(0, 128, 0); font-weight: bold;" class="">"<a href="http://developer.marklogic.com/maven2/" class="">http://developer.marklogic.com/maven2/</a>" </span><span style="font-size: 9pt;" class="">}<br class=""> maven { url </span><span style="font-size: 9pt; color: rgb(0, 128, 0); font-weight: bold;" class="">"<a href="http://repository.cloudera.com/artifactory/cloudera-repos/" class="">http://repository.cloudera.com/artifactory/cloudera-repos/</a>" </span><span style="font-size: 9pt;" class="">}<br class="">}<br class=""><br class="">configurations {<br class=""> mlcp {<br class=""> resolutionStrategy {<br class=""> force </span><span style="font-size: 9pt; color: rgb(0, 128, 0); font-weight: bold;" class="">"xml-apis:xml-apis:1.4.01"<br class=""></span><span style="font-size: 9pt; color: rgb(0, 128, 0); font-weight: bold;" class=""> </span><span style="font-size: 9pt;" class="">}<br class=""> }<br class="">}<br class=""><br class="">dependencies {<br class=""> mlcp </span><span style="font-size: 9pt; color: rgb(0, 128, 0); font-weight: bold;" class="">"com.marklogic:mlcp:9.0.6"<br class=""></span><span style="font-size: 9pt; color: rgb(0, 128, 0); font-weight: bold;" class=""> </span><span style="font-size: 9pt;" class="">mlcp files(</span><span style="font-size: 9pt; color: rgb(0, 128, 0); font-weight: bold;" class="">"marklogic/lib"</span><span style="font-size: 9pt;" class="">)<br class="">}<br class=""><br class=""></span><font size="3" class=""><span style="color: rgb(0, 0, 67); font-weight: bold;" class="">class </span>XQDocFilter <span style="color: rgb(0, 0, 67); font-weight: bold;" class="">extends </span>BaseFilterReader {<br class=""> XQDocFilter(Reader input) {<br class=""> <span style="color: rgb(0, 0, 67); font-weight: bold;" class="">super</span>(<span style="color: rgb(0, 0, 67); font-weight: bold;" class="">new </span>StringReader(<span style="color: rgb(0, 0, 67); font-weight: bold;" class="">new </span>org.xqdoc.MarkLogicProcessor().process(input.text)))<br class=""> }<br class="">}<br class=""><br class="">task generateXQDocs(type: Copy) {<br class=""> into <span style="color: rgb(0, 128, 0); font-weight: bold;" class="">'xqDoc'<br class=""></span><span style="color: rgb(0, 128, 0); font-weight: bold;" class=""> </span>from <span style="color: rgb(0, 128, 0); font-weight: bold;" class="">'src/main/ml-modules'<br class=""></span><span style="color: rgb(0, 128, 0); font-weight: bold;" class=""> </span>include <span style="color: rgb(0, 128, 0); font-weight: bold;" class="">'**/*.xqy'<br class=""></span><span style="color: rgb(0, 128, 0); font-weight: bold;" class=""> </span>rename { it - <span style="color: rgb(0, 128, 0); font-weight: bold;" class="">'.xqy' </span>+ <span style="color: rgb(0, 128, 0); font-weight: bold;" class="">'.xml' </span>} <br class=""> includeEmptyDirs = <span style="color: rgb(0, 0, 67); font-weight: bold;" class="">false<br class=""></span><span style="color: rgb(0, 0, 67); font-weight: bold;" class=""> </span>filter XQDocFilter<br class="">}<br class=""><br class=""><span style="color: rgb(128, 128, 128); font-style: italic;" class=""> </span>task importXQDoc(type: com.marklogic.gradle.task.MlcpTask) {<br class=""> classpath = configurations.mlcp<br class=""> command = <span style="color: rgb(0, 128, 0); font-weight: bold;" class="">"IMPORT"<br class=""></span><span style="color: rgb(0, 128, 0); font-weight: bold;" class=""> </span>database = <span style="color: rgb(0, 128, 0); font-weight: bold;" class="">"emh-accelerator-content"<br class=""></span><span style="color: rgb(0, 128, 0); font-weight: bold;" class=""> </span>input_file_path = <span style="color: rgb(0, 128, 0); font-weight: bold;" class="">"xqDoc"<br class=""></span><span style="color: rgb(0, 128, 0); font-weight: bold;" class=""> </span>output_collections = <span style="color: rgb(0, 128, 0); font-weight: bold;" class="">"xqdoc"<br class=""></span><span style="color: rgb(0, 128, 0); font-weight: bold;" class=""> </span>output_uri_replace = <span style="color: rgb(0, 128, 0); font-weight: bold;" class="">".*xqDoc,'/xqDoc'"<br class=""></span><span style="color: rgb(0, 128, 0); font-weight: bold;" class=""> </span>document_type = <span style="color: rgb(0, 128, 0); font-weight: bold;" class="">"mixed"<br class=""></span>}</font><span style="font-size: 9pt;" class=""><br class=""></span></pre></div><div class=""><span style="font-size: 25px;" class=""><br class=""></span></div><div class=""><span style="font-size: 22px;" class="">2.1 eXist-db equivalent</span></div><div class=""><span style="font-size: 22px;" class=""><br class=""></span></div><div class=""><font size="3" class="">The equivalent call would be</font></div><div class=""><pre style="background-color: rgb(255, 255, 255);" class=""><font size="3" class=""><span style="font-family: Menlo; color: rgb(0, 0, 67); font-weight: bold;" class="">new </span><font face="Menlo" class="">org.xqdoc.ExistDBProcessor().process(input.text)</font></font></pre><div class=""><br class=""></div></div><div class=""><span style="font-size: 25px;" class="">3.0 Issues</span></div><div class=""><span style="font-size: 25px;" class=""><br class=""></span></div><div class=""><span style="font-size: 22px;" class="">3.1 XQuery 3.1 extensions</span></div><div class=""><font size="3" class=""><br class=""></font></div><div class=""><font size="3" class="">The current grammar file is not properly parsing the following two items:</font></div><div class=""><font size="3" class=""><br class=""></font></div><div class=""><font size="3" class="">String Constructors <a href="https://www.w3.org/TR/xquery-31/#id-string-constructors" class="">https://www.w3.org/TR/xquery-31/#id-string-constructors</a></font></div><div class=""></div></div><div class=""><font size="3" class=""><br class=""></font></div><div class=""><font size="3" class="">URI Qualified Name <a href="https://www.w3.org/TR/xquery-31/#doc-xquery31-URIQualifiedName" class="">https://www.w3.org/TR/xquery-31/#doc-xquery31-URIQualifiedName</a></font></div><div class=""><font size="3" class=""><br class=""></font></div><div class=""><font size="3" class="">I need some help with the XQueryParser.g4 and XQueryLexer.g4 files to properly include those. I have a question posted to StackOverflow on the String Constructors <a href="https://stackoverflow.com/questions/53462040/i-am-having-trouble-translating-an-ebnf-grammar-to-an-antlr4-grammar" class="">https://stackoverflow.com/questions/53462040/i-am-having-trouble-translating-an-ebnf-grammar-to-an-antlr4-grammar</a></font></div><div class=""><font size="3" class=""><br class=""></font></div><div class=""><span style="font-size: 22px;" class="">3.2 Implementation specific extensions</span></div><div class=""><font size="3" class=""><br class=""></font></div><div class=""><font size="3" class="">I believe that I have al of the eXist-db and MarkLogic language extensions implemented, but I need help testing the parser. </font></div><div class=""><font size="3" class=""><br class=""></font></div><div class=""><font size="3" class="">I still need to add the BaseX and Saxon extensions.</font></div><div class=""><font size="3" class=""><br class=""></font></div><div class=""><br class=""></div><div class=""><div class=""><span style="font-size: 25px;" class="">4.0 Future</span></div></div><div class=""><font size="3" class=""><br class=""></font></div><div class=""><div class=""><ul class="MailOutline"><li class=""><span style="font-size: inherit;" class="">I would appreciate the help from any that would like to contribute to the development</span></li><li class=""><span style="font-size: inherit;" class="">Once the following issues are resolved, then I am planning on coming out with a 2.0 release.</span></li><li class=""><span style="font-size: inherit;" class="">Add the display of the comments in markdown in the xqDoc display code</span></li><li class=""><span style="font-size: inherit;" class="">I am also interested in if anyone would be interested in helping me with </span><font size="3" class=""> MarkLogic XQuery Code Scan using SonarQube utilizing the XQuery grammar and possibly the xqDoc files.</font></li></ul></div><div class=""><font size="3" class=""><br class=""></font></div></div><div class=""><br class=""></div><div class=""><br class=""></div><div class=""><br class=""></div><div class=""><br class=""></div><div class=""><br class=""></div><div class=""><br class=""></div><div class=""><br class=""></div></div></div></div></div></div><br class=""></body></html>