XQDoc es una herramienta para la generación automática de documentación en formato HTML a partir de código fuente XQuery, es decir, es la herramienta Javadoc para código XQuery (Javadoc una utilidad de Sun Microsystems para la generación de documentación automática de APIs en formato HTML). Este post surgió a partir de mi anterior entrada sobre «Guía de estilos en XQuery«.
Al igual que en Javadoc, es necesario introducir comentarios especiales en los módulos/ficheros XQuery para que posteriormente la herramienta pueda generar la documentación HTML. Principalmente deben documentarse dos elementos:
- El módulo o la unidad XQuery
- Cada una de las funciones incluidas en él
Los comentarios XQDoc se establecen entre los caracteres (:~ : ) , ¡cuidado! sólo es necesario añadir ~ para que sea comentario XQdoc. Entre estos caracteres se incluye la descripción del elemento a documentar, así como ciertas palabras reservadas precedidas por el caracter «@» para añadir ciertas funcionalidades. Veamos un ejemplo:
Documentación de Módulo donde se incluye una breve descripción de su cometido, autor, fecha y versión:
(:~
: Este módulo propociona un ejemplo que sigue la especificación XQDoc. :
: @author Luis Arévalo
: @since February 8, 2010
: @version 1.0
: )
Documentación de función donde se incluye una breve descripción, parámetros de entrada y salida:
(:~
: Suma dos números
: @param $operand1 primer operando.
: @param $operand2 segundo operando.
: @return resultado de la operación
: )
Existe un mayor número de palabras reservadas (@see,…) que no analizaremos en esta entrada por ser igual que en Javadoc.
Una vez introducidos los comentarios, el siguiente paso será generar la documentación. Los autores (XQDoc) han desarrollado distintos plugins para Saxon, eXist y MarkLogic además de integrarlos en algunos editores XQuery (StylusStudio). Para el caso de Saxon es necesario:
- Desde Saxon: Saxon 9 (saxon9he.jar)
- Desde Antrl: antlr.jar
- Desde XQdoc: xqdoc_conv.jar y xqdoc_saxon.jar
Una vez que se han descargado todas las librerías, se utilizará la clase XQDocLiteDriver para generar la documentación.
java org.xqdoc.lite.XQDocLite [file | dir] [file-extension] [xquery-version] [default-function-namespace] [predefined-namespace-mappings] [output-directory] [xqdoc-display]
- file: Fichero individual a procesar
- dir: Directorio con módulos a procesar
- file-extension: Extensión de los ficheros XQuery
- xquery-version: Versión de la Especificación XQuery (MAY2003, NOV2003, OCT2004, APR2005, SEP2005, NOV2005, JAN2007).
- default-function-namespace: Un valor URI o ‘default’ para usar XPATH.
- predefined-namespace-mappings: lista de prefijos=uri o ‘none’.
- output-directory: Directorio de Salida
Yo me he hecho mi propio script (run.sh) para su ejecución que recibe los parámetros por argumento (en este caso sólo el fichero XQuery de entrada)
java -cp saxon9he.jar:antlr-2.7.7.jar:xqdoc_c:xqdoc_conv.jar:xqdoc_saxon.jar org.xqdoc.lite.XQDocLite $1 xqm NOV2005 default math="http://xqdoc.org/sample-math-lib" .
y se llamaría
./run.sh ejemplo
El fichero de ejemplo utilizado lo he obtenido de la «Guía de Estilo XQuery» anteriormente comentada y os lo podéis descargar desde aquí.