En esta página

Introducción a QDoc

QDoc es una herramienta utilizada por los desarrolladores de Qt para generar documentación para proyectos de software. Funciona extrayendo los comentarios QDoc de los archivos fuente del proyecto y, a continuación, dando formato a dichos comentarios como páginas HTML o documentos XML de DocBook. QDoc busca comentarios QDoc en los archivos « .cpp » y en los archivos « .qdoc ». QDoc no busca comentarios QDoc en los archivos « .h ». Un comentario QDoc siempre comienza 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 utilizar los comandos de QDoc en los comentarios QDoc para incluir una buena documentación en tus archivos fuente. También explica cómo crear un archivo de configuración de QDoc, que se le pasará a QDoc desde la línea de comandos.

Ejecutar QDoc

El nombre del programa QDoc es qdoc. Para ejecutar QDoc desde la línea de comandos, indícale 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 indica a QDoc dónde encontrar los archivos fuente del proyecto, los archivos de cabecera y los archivos « .qdoc ». También es donde se indica a QDoc qué tipo de salida debe generar (HTML, DocBook XML...) y dónde guardar la documentación generada. El archivo de configuración también contiene otra información para QDoc.

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

Cómo funciona QDoc

QDoc comienza leyendo el archivo de configuración que has 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 qué generadores de salida ejecutará. El valor por defecto es HTML, por lo que, si no estableces ` outputformats ` en tu archivo de configuración, QDoc generará una salida HTML. Normalmente eso es lo que querrás de todos modos, pero también puedes especificar `DocBook` para obtener una salida DocBook en su lugar.

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

Tras analizar todos los archivos de cabecera y construir el árbol maestro de elementos que deben documentarse, QDoc utiliza el valor de la variable «sourcedirs» y/o el valor de la variable «sources» para buscar y analizar todos los archivos « .cpp » y « .qdoc » de tu proyecto. Estos son los archivos en los que QDoc busca comentarios de QDoc. Recuerda 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 este contiene documentación almacenada, QDoc invoca al generador de salida especificado por la variable ` outputformats ` para dar formato y escribir la documentación en el directorio especificado en el archivo de configuración mediante la variable `outputdir`.

Tipos de comandos

QDoc interpreta tres tipos de comandos:

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

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 la página siguiente y a la anterior, la 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 se trata de una función sobrecargada o reimplementada, o si ha quedado obsoleto.

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

© 2026 The Qt Company Ltd. Documentation contributions included herein are the copyrights of their respective owners. The documentation provided herein is licensed under the terms of the GNU Free Documentation License version 1.3 as published by the Free Software Foundation. Qt and respective logos are trademarks of The Qt Company Ltd. in Finland and/or other countries worldwide. All other trademarks are property of their respective owners.