xqdoc and basex system modules
Monday, 23 March 2015 · 4 messages · last reply 7 Apr 2015
AB
Andy Bunce23 Mar 2015 14:39 #
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?
/AndyCG
Christian Grün24 Mar 2015 16:54 #
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
AB
Andy Bunce24 Mar 2015 17:28 #
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.ditaQuoted 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 >
CG
Christian Grün7 Apr 2015 09:50 #
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.
⚡Generated with XQuery