Extracting function signatures from documentation
Hi, I am doing some tooling for XQuery and need to extract function signatures from text, like from the BaseX module library documentation. But with my regex skills I just hit the wall. Next step would be to write some complex program, that does the parsing, maybe in combination with regexes, but before I start into that, I wanted to ask, whether the work has already been done. Is there a marked up version of the BaseX function docs? Or, even better (since I could apply it to other docs, then) does anyone know of a regular expression or an XQuery routine, that analyzes function signatures? Thanks a lot! -- Minden jót, all the best, Alles Gute, Andreas Mixich
Please take a look at xqDoc for XQuery that is like JavaDoc for Java. https://github.com/lcahlander/xqdoc <https://github.com/lcahlander/xqdoc> Here is a polymer based web app that runs under eXist-db. The build.gradle has a task generateXQDocs https://github.com/lcahlander/xqDoc-eXist-db <https://github.com/lcahlander/xqDoc-eXist-db>
On May 16, 2019, at 11:42 AM, Andreas Mixich <mixich.andreas@gmail.com> wrote:
Hi,
I am doing some tooling for XQuery and need to extract function signatures from text, like from the BaseX module library documentation. But with my regex skills I just hit the wall. Next step would be to write some complex program, that does the parsing, maybe in combination with regexes, but before I start into that, I wanted to ask, whether the work has already been done.
Is there a marked up version of the BaseX function docs? Or, even better (since I could apply it to other docs, then) does anyone know of a regular expression or an XQuery routine, that analyzes function signatures?
Thanks a lot!
-- Minden jót, all the best, Alles Gute, Andreas Mixich
On Thu, May 16, 2019 at 5:54 PM Loren Cahlander <loren.cahlander@gmail.com> wrote:
Please take a look at xqDoc for XQuery that is like JavaDoc for Java.
Thanks for the hint! I did not yet think about looking at xqdoc. Definitely will do this. See also my reply to Christian. -- Minden jót, all the best, Alles Gute, Andreas Mixich
Hi Andreas - (someone on the BaseX team will surely correct where I get this wrong, so...) as far as I know, many/most/all of the BaseX builtin modules are written in Java, not XQuery, so I don't know that there are modules to inspect, so to speak. However, late last year there was some discussion on the list along these same lines and Christian wrote up an XQuery script to generate xqDoc output from the wiki [1]. Maybe that would be helpful for your project? Best, Bridger [1] https://github.com/BaseXdb/basex-dist/blob/master/wiki2xqdoc.xq On Thu, May 16, 2019 at 2:34 PM Andreas Mixich <mixich.andreas@gmail.com> wrote:
On Thu, May 16, 2019 at 5:54 PM Loren Cahlander <loren.cahlander@gmail.com> wrote:
Please take a look at xqDoc for XQuery that is like JavaDoc for Java.
Thanks for the hint! I did not yet think about looking at xqdoc. Definitely will do this. See also my reply to Christian.
-- Minden jót, all the best, Alles Gute, Andreas Mixich
Exactly; thanks, Bridger! In the etc directory of our zip distribution, there is an xqdoc.zip file, which contains the generated library modules for all BaseX-specific functions. Bridger Dyson-Smith <bdysonsmith@gmail.com> schrieb am Do., 16. Mai 2019, 20:47:
Hi Andreas -
(someone on the BaseX team will surely correct where I get this wrong, so...) as far as I know, many/most/all of the BaseX builtin modules are written in Java, not XQuery, so I don't know that there are modules to inspect, so to speak. However, late last year there was some discussion on the list along these same lines and Christian wrote up an XQuery script to generate xqDoc output from the wiki [1].
Maybe that would be helpful for your project? Best, Bridger
[1] https://github.com/BaseXdb/basex-dist/blob/master/wiki2xqdoc.xq
On Thu, May 16, 2019 at 2:34 PM Andreas Mixich <mixich.andreas@gmail.com> wrote:
On Thu, May 16, 2019 at 5:54 PM Loren Cahlander < loren.cahlander@gmail.com> wrote:
Please take a look at xqDoc for XQuery that is like JavaDoc for Java.
Thanks for the hint! I did not yet think about looking at xqdoc. Definitely will do this. See also my reply to Christian.
-- Minden jót, all the best, Alles Gute, Andreas Mixich
Hi Bridger, thanks for the hint. I got the zip file Christian mentioned and it solves my problem, at least for the BaseX catalog (I just needed to change the hardcoded namespace to a temporary one for the inspect:module#1 function to accept the module). Very cool! :-) On Thu, May 16, 2019 at 8:47 PM Bridger Dyson-Smith <bdysonsmith@gmail.com> wrote:
Hi Andreas -
(someone on the BaseX team will surely correct where I get this wrong, so...) as far as I know, many/most/all of the BaseX builtin modules are written in Java, not XQuery, so I don't know that there are modules to inspect, so to speak. However, late last year there was some discussion on the list along these same lines and Christian wrote up an XQuery script to generate xqDoc output from the wiki [1].
Maybe that would be helpful for your project? Best, Bridger
[1] https://github.com/BaseXdb/basex-dist/blob/master/wiki2xqdoc.xq
On Thu, May 16, 2019 at 2:34 PM Andreas Mixich <mixich.andreas@gmail.com> wrote:
On Thu, May 16, 2019 at 5:54 PM Loren Cahlander < loren.cahlander@gmail.com> wrote:
Please take a look at xqDoc for XQuery that is like JavaDoc for Java.
Thanks for the hint! I did not yet think about looking at xqdoc. Definitely will do this. See also my reply to Christian.
-- Minden jót, all the best, Alles Gute, Andreas Mixich
-- Minden jót, all the best, Alles Gute, Andreas Mixich
The output of the inspect:module and inspect:xqdoc functions can be used to generate a documentation of your source code (in HTML, Swagger, …). Hope this helps, Christian On Thu, May 16, 2019 at 5:42 PM Andreas Mixich <mixich.andreas@gmail.com> wrote:
Hi,
I am doing some tooling for XQuery and need to extract function signatures from text, like from the BaseX module library documentation. But with my regex skills I just hit the wall. Next step would be to write some complex program, that does the parsing, maybe in combination with regexes, but before I start into that, I wanted to ask, whether the work has already been done.
Is there a marked up version of the BaseX function docs? Or, even better (since I could apply it to other docs, then) does anyone know of a regular expression or an XQuery routine, that analyzes function signatures?
Thanks a lot!
-- Minden jót, all the best, Alles Gute, Andreas Mixich
On Thu, May 16, 2019 at 7:27 PM Christian Grün <christian.gruen@gmail.com> wrote:
The output of the inspect:module and inspect:xqdoc functions can be used to generate a documentation of your source code
Sorry, I should have been more elaborate (I wanted to keep the message short). I am working on an XQuery mode for the Sublime Text 3 editor. For this I create content-completion snippets, that look like (sourced from the XPath functions 3.1 spec here): <snippet><!-- array:fold-left#3 --> <content><![CDATA[array:fold-left(${1:\$array as array(*)}, ${2:\$zero as item()*}, ${3:\$function as function(item()*, item()*) as item()*})]]></content> <tabTrigger>arfl</tabTrigger> <scope>source.xquery</scope> <description>array:fold-left($array|array(*), $zero|item()*, $function|function(item()*, item()*) as item()*) item()*</description> </snippet> As you hinted, it is easy to do this for my own modules by using the 'inspect' module. But how to do this for the built-in, BaseX library catalog (and that would just be the start, Saxon and eXist extensions shall be supported, too, I want to make it vendor agnostic, so to have as many people benefit from it as possible)?. The only way, I found so far, would be to read out the function signatures from the HTML table in the BaseX documentation. But after this, I need to analyze the signature. And this is where I tried to find a solution, but haven't so far. I will, however, check out the repository Loren is pointing at. Maybe I find something interesting there... :-) -- Minden jót, all the best, Alles Gute, Andreas Mixich
participants (4)
-
Andreas Mixich -
Bridger Dyson-Smith -
Christian Grün -
Loren Cahlander