Are you thinking about adding cross-referencing capability?

[dmcbeath]

I really like your pure xquery version of the tool. I don't really have an issue as much as a question. In the original xqDoc project, we automatically captured all of the cross-referencing information (what functions used this function, what functions were used by this function, what functions used this global variable, etc.). I often found this very useful (from a learning perspective, testing as I know what was changed, etc.). I was wondering if you had any plans for providing this as an option in the generated html output. I haven't looked close enough at the xqDoc XML that you are generating under the covers so I'm not even sure that you are capturing this information when parsing the modules. Anyway, I would be interested in your thoughts. Thanks again for creating this project.

[xquery]

xquerydoc characterizes the entire xquery (like xqueryx) ... so in theory doing cyclometric complexity like metrics and dependency analysis should be doable; great idea and will add it as a task

[jpcs]

Yeah - agreed. In theory perfectly doable, but I was concentrating on getting JavaDoc like documentation working first. The function calls and variable references are all marked up by the XQuery parser, so otherwise it's not too hard. Probably the hardest parts would be:

1. Keeping track of the namespace bindings and resolving QNames.
2. Keeping track of variables in scope, to make sure a global variable wasn't occluded.
3. Tracking public/private variables and functions, and which were imported and in scope.

[dmcbeath]

Sounds great. If you want, maybe we could further discuss this at XML Prague in a few weeks.

[xquery]

great to hear you are coming and yes sounds like a plan, see you then

[xquery]

Darin apologies that we didn't have the time to chat ... very happy you were able to come to XML Prague.

Do you have any further ideas on this ?

[dmcbeath]

A couple of thoughts. When generating the xqdoc XML, the following information would need to be captured within each function.

1. What functions this function uses
2. What variables this function uses

Both of this information is captured in the and elements defined in the xqdoc schema. For each function invoked (), you would want to record the uri (namespace of the library module invoked), name (function name invoked), and arity (number of parameters in the function invoked). For each referenced variable (, you would then want to record the uri (namespace of the library module containing the variable) and name (name of the variable).

Now that you have the xqdoc XML, it's a matter of figuring out how to best use this information. It was fairly straightforward when the xqdoc XML was stored into a database (such as MarkLogic) because I could then store the xqdoc XML for each module (using the module uri as the uri) and then on the fly decide whether I could link up a cross-referenced function or variable (because I could check and see if that library module had been loaded). I had to do some funny things with main modules (as they really don't have a URI). I also had a limitation/issue that a module URI could not be split across multiple library modules (that seemed to be ok a majority of the time as most people tend to adhere to a 1 to 1 library module/URI).

In your model, I would assume that you would want to store the xqdoc xml in the file system. You might then want to have some XQuery/XSLT and perhaps some javascript to simulate what I had been doing dynamically within the context of a database. For example, this code could transform the xqdoc xml (on the fly) and perhaps work out which links to highlight for cross-referencing (based on which files are loaded). This might imply that you need to store the physical filename (as opposed the the URI) when capturing the and information.

These are just some high-level thoughts. Let me know if this doesn't make sense or if you have any questions.