Generating documents from XQuery annotations

Andy Bunce

Director
Quodatum Ltd

Abstract

The paper describes an implementation of an xqDoc.org documentation generator. A focus of this implementation is XQuery annotation support. In 2014, the xqDoc schema was updated to include markup to capture XQuery annotations; however, existing renderers have often not been updated to make use of this. A major driver for annotation support is documenting XQuery web applications built using the RESTXQ standard. RESTXQ defines a standard set of XQuery annotations that can be used to define RESTful Web Services from XQuery. Annotations are also being used to define frameworks for unit testing, user permissioning and web socket interfaces. Annotations are code markup that the runtime environment may choose to use to wire-in additional external functionality to XQuery applications. The xqDocA implementation is open source. It is largely written in XQuery and runs with recent versions of BaseX. It generates static, standalone HTML5 and XML and JSON output.

The included XQuery library modules can also be used to assist in the generation of other related documentation artefacts. In the case of RESTXQ, these could be the generation of openAPI (Swagger) and WADL documents.


Table of Contents

Introduction
Annotations?
What are annotations?
Use of annotations in XQuery
Built-in annotations
RestXQ
Unit testing
Other applications
XQuery documentation
The xqDoc format
Schema updates
Working with xqDoc documents
Components
XqDoc implementations
Parsers
Introducing xqDocA
Overview
Renderers
Implementation
Sample outputs
Customisation
Conclusions
Bibliography