xqdoc and basex system modules
I am looking to generate documentation from the system module stubs in etc/modules.zip. I have two issues
1) There is an issue with inspect.xqm
declare namespace xqdoc="http://www.xqdoc.org/1.0";
let
$a:=inspect:xqdoc("inspect.xqm")//xqdoc:function[xqdoc:name='inspect:xqdoc']//xqdoc:description
return parse-xml-fragment($a)Errors And xqdoc:description looks like <xqdoc:description xmlns:xqdoc="http://www.xqdoc.org/1.0"></code> and end with <code></code> , and tags start with <code>@</code> . xqDoc comments can be specified for main and library modules and variable and function declarations. <p>We have slightly extended the xqDoc conventions to do justice to the current status of XQuery (Schema: <a href=" http://files.basex.org/etc/xqdoc-1.1.30052013.xsd ">xqdoc-1.1.30052013.xsd</a>): </p> <ul> <li> an <code>&lt;xqdoc:annotations/&gt;</code> node is added to each variable or function that uses annotations. The xqdoc:annotation child nodes may have additional <code>xqdoc:literal</code> elements with <code>type</code> attributes (xs:string, xs:integer, xs:decimal, xs:double) and values. </li> <li> a single <code>&lt;xqdoc:namespaces/&gt;</code> node is added to the root element, which summarizes all prefixes and namespace URIs used or declared in the module. </li> <li> name and type elements are added to variables </li> </ul></xqdoc:description>
A comment parsing/escaping issue?
2) inspect:xqdoc("array.xqm") and the same with map.xqm
Function 'array:size' is in reserved namespace. I guess this is to be expected and maybe I should just ignore any modules in namespaces http://www.w3.org/...
I guess it is a result of the code being compiled rather than just documented?
/Andy
Hi Andy,
I have just updated the modules.zip file; maybe the first error is gone?
https://github.com/BaseXdb/basex-dist/blob/master/etc/modules.zip
If not, I agree something must go wrong while there must be something wrong with parsing the description as XML.
Quoted text · Andy Bunce · 5 lines
> 2) inspect:xqdoc("array.xqm") and the same with map.xqm > > Function 'array:size' is in reserved namespace. I guess this is to be > expected and maybe I should just ignore any modules in namespaces > http://www.w3.org/...
Exactly. Maybe we should also remove it from the zip file..
Thanks, Christian
I think it is the handling of nested comments:
let $a:='
(:~
: BEFORE <code>(:~</code> MIDDLE <code>:)</code> AFTER
:)
declare function local:foo(){42};local:foo()
'
return inspect:xqdoc($a)
Result: <xqdoc:description></code> MIDDLE <code></xqdoc:description>
may be confusing [1] indeed. /Andy [1] http://www-01.ibm.com/support/knowledgecenter/SSEPEK_11.0.0/com.ibm.db2z11.doc.xml/src/tpc/db2z_commentxpxq.dita
Quoted text · Christian Grün · 21 lines
On 24 March 2015 at 15:54, Christian Grün <christian.gruen at gmail.com> wrote: > Hi Andy, > > I have just updated the modules.zip file; maybe the first error is gone? > > https://github.com/BaseXdb/basex-dist/blob/master/etc/modules.zip > > If not, I agree something must go wrong while there must be something > wrong with parsing the description as XML. > > > 2) inspect:xqdoc("array.xqm") and the same with map.xqm > > > > Function 'array:size' is in reserved namespace. I guess this is to be > > expected and maybe I should just ignore any modules in namespaces > > http://www.w3.org/... > > Exactly. Maybe we should also remove it from the zip file.. > > Thanks, > Christian >
Hi Andy,
Back again... I have fixed xqdoc parsing. Could you give it another try? The snapshot is available in a few minutes..
Christian
Quoted text · Andy Bunce · 42 lines
On Tue, Mar 24, 2015 at 5:28 PM, Andy Bunce <bunce.andy at gmail.com> wrote: > I think it is the handling of nested comments: > > let $a:=' > (:~ > : BEFORE <code>(:~</code> MIDDLE <code>:)</code> AFTER > :) > declare function local:foo(){42};local:foo() > ' > return inspect:xqdoc($a) > > Result: > <xqdoc:description></code> MIDDLE <code></xqdoc:description> > > may be confusing [1] indeed. > /Andy > [1] > http://www-01.ibm.com/support/knowledgecenter/SSEPEK_11.0.0/com.ibm.db2z11.doc.xml/src/tpc/db2z_commentxpxq.dita > > On 24 March 2015 at 15:54, Christian Grün <christian.gruen at gmail.com> wrote: >> >> Hi Andy, >> >> I have just updated the modules.zip file; maybe the first error is gone? >> >> https://github.com/BaseXdb/basex-dist/blob/master/etc/modules.zip >> >> If not, I agree something must go wrong while there must be something >> wrong with parsing the description as XML. >> >> > 2) inspect:xqdoc("array.xqm") and the same with map.xqm >> > >> > Function 'array:size' is in reserved namespace. I guess this is to be >> > expected and maybe I should just ignore any modules in namespaces >> > http://www.w3.org/... >> >> Exactly. Maybe we should also remove it from the zip file.. >> >> Thanks, >> Christian > >
Written for BaseX 8.0, 8.1. BaseX may have changed since: please check the current documentation.