Introducción a QDoc

QDoc es una herramienta utilizada por los desarrolladores de Qt para generar documentación para proyectos de software. Funciona extrayendo comentarios QDoc de los archivos fuente del proyecto y luego formateando estos comentarios como páginas HTML o documentos DocBook XML. QDoc encuentra comentarios QDoc en archivos .cpp y en archivos .qdoc. QDoc no busca comentarios QDoc en los archivos .h. Un comentario QDoc comienza siempre con un signo de exclamación (!)). Por ejemplo:

/*!
    \class QObject
    \brief The QObject class is the base class of all Qt objects.

    \ingroup objectmodel

    \reentrant

    QObject is the heart of the Qt \l{Object Model}. The
    central feature in this model is a very powerful mechanism
    for seamless object communication called \l{signals and
    slots}. You can connect a signal to a slot with connect()
    and destroy the connection with disconnect(). To avoid
    never ending notification loops you can temporarily block
    signals with blockSignals(). The protected functions
    connectNotify() and disconnectNotify() make it possible to
    track connections.

    QObjects organize themselves in \l {Object Trees &
    Ownership} {object trees}. When you create a QObject with
    another object as parent, the object will automatically
    add itself to the parent's \c children() list. The parent
    takes ownership of the object. It will automatically
    delete its children in its destructor. You can look for an
    object by name and optionally type using findChild() or
    findChildren().

    Every object has an objectName() and its class name can be
    found via the corresponding metaObject() (see
    QMetaObject::className()). You can determine whether the
    object's class inherits another class in the QObject
    inheritance hierarchy by using the \c inherits() function.

....
*/

A partir del comentario QDoc anterior, QDoc genera la página HTML QObject class reference.

Este manual explica cómo usar los comandos QDoc en los comentarios QDoc para incrustar buena documentación en tus archivos fuente. También explica cómo crear un archivo de configuración QDoc, que pasarás a QDoc en la línea de comandos.

Ejecutar QDoc

El nombre del programa QDoc es qdoc. Para ejecutar QDoc desde la línea de comandos, indíquele el nombre de un archivo de configuración:

$ ../../bin/qdoc ./config.qdocconf

QDoc reconoce el sufijo .qdocconf como un archivo de configuración de QDoc. El archivo de configuración es donde se le indica a QDoc dónde encontrar los archivos fuente del proyecto, los archivos de cabecera y los archivos .qdoc. También es donde le dices a QDoc qué tipo de salida generar (HTML, DocBook XML...), y dónde poner la documentación generada. El archivo de configuración también contiene otra información para QDoc.

Consulte El archivo de configuración de QDoc para obtener instrucciones sobre cómo configurar un archivo de configuración de QDoc.

Funcionamiento de QDoc

QDoc comienza leyendo el archivo de configuración especificado en la línea de comandos. Almacena todas las variables del archivo de configuración para su uso posterior. Una de las primeras variables que utiliza es outputformats. Esta variable indica a QDoc los generadores de salida que ejecutará. El valor por defecto es HTML, por lo que si no establece outputformats en su archivo de configuración, QDoc generará salida HTML. Esto es lo que normalmente se desea, pero también se puede especificar DocBook para obtener la salida DocBook.

A continuación, QDoc utiliza los valores de la variable headerdirs y/o la variable headers para encontrar y analizar todos los archivos de cabecera de su proyecto. QDoc no analiza los archivos de cabecera en busca de comentarios QDoc. Analiza los archivos de cabecera para construir un árbol maestro de todos los elementos que deben ser documentados, en otras palabras, los elementos para los que QDoc debe encontrar comentarios QDoc.

Después de analizar todos los archivos de cabecera y construir el árbol maestro de elementos a documentar, QDoc utiliza el valor de la variable sourcedirs y/o el valor de la variable sources para encontrar y analizar todos los archivos .cpp y .qdoc de tu proyecto. Estos son los archivos que QDoc escanea en busca de comentarios QDoc. Recuerde que un comentario QDoc comienza con un signo de exclamación: /*!.

Por cada comentario QDoc que encuentra, busca en el árbol maestro el elemento al que pertenece la documentación. A continuación, interpreta los comandos QDoc del comentario y almacena los comandos interpretados y el texto del comentario en el nodo del árbol correspondiente al elemento.

Por último, QDoc recorre el árbol maestro. Para cada nodo, si el nodo ha almacenado documentación, QDoc llama al generador de salida especificado por la variable outputformats para formatear y escribir la documentación en el directorio especificado en el archivo de configuración en la variable outputdir.

Tipos de comandos

QDoc interpreta tres tipos de comandos:

• Comandos de tema
• Comandos de contexto
• Comandos de marcado

Los comandos de tema identifican el elemento que se está documentando, por ejemplo, una clase C++, una función, un tipo o una página adicional de texto que no se corresponde con un elemento C++ subyacente.

Los comandos de contexto indican a QDoc cómo se relaciona el elemento que se está documentando con otros elementos documentados, por ejemplo, enlaces a páginas anteriores y siguientes, inclusión en grupos de páginas o módulos de biblioteca. Los comandos de contexto también pueden proporcionar información sobre el elemento documentado que QDoc no puede obtener de los archivos fuente, por ejemplo, si el elemento es seguro para subprocesos, si es una función sobrecargada o reimplementada, o si ha sido obsoleta.

Los comandos de marcado indican a QDoc cómo deben representarse los elementos de texto e imagen en el documento, o sobre la estructura del documento.