Variables de configuración genéricas
Con las variables de configuración generales de QDoc, puedes definir dónde encontrará QDoc los distintos archivos fuente que necesita para generar la documentación, así como el directorio en el que se guardará la documentación generada. También puedes realizar algunas modificaciones menores en el propio QDoc, controlando su salida y su comportamiento de procesamiento.
codeindent
La variable codeindent especifica el nivel de sangría que utiliza QDoc al escribir fragmentos de código.
QDoc utilizaba originalmente un valor fijo de cuatro espacios para la sangría del código, con el fin de garantizar que los fragmentos de código se pudieran distinguir fácilmente del texto circundante. Dado que podemos utilizar hojas de estilo para ajustar el aspecto de ciertos tipos de elementos HTML, este nivel de sangría no siempre es necesario.
lenguajes de programación
La variable codelanguages especifica una lista de lenguajes de código fuente no reconocidos por QDoc que pueden utilizarse dentro de los bloques \code... \endcode. Esto permite escribir bloques de código en lenguajes que QDoc no puede analizar, y generar código HTML que pueda ser resaltado o procesado por otras herramientas.
codelanguages = Python Rust Java Swift "C#"Dado que QDoc admite C++ (Cpp), QML y texto, no es necesario especificar estos lenguajes en esta lista. Los nombres de lenguajes que contengan caracteres especiales, como C#, deben escribirse entre comillas dobles cuando se incluyan en esta lista.
La variable ` codelanguages ` se introdujo en QDoc 6.11 para permitir que la documentación en línea de Qt utilice el resaltado de sintaxis para un subconjunto de los lenguajes compatibles con highlight.js.
Véase también \code.
codeprefix, codesuffix
Las variables « codeprefix » y « codesuffix » especifican un par de cadenas que enmarcan cada fragmento de código.
define
La variable defines especifica los símbolos del preprocesador de C++ que QDoc reconocerá y a los que responderá.
Cuando se especifica un símbolo del preprocesador mediante la variable defines, también se puede utilizar el \if para incluir documentación que solo se incorporará si el símbolo del preprocesador está definido.
defines = QT_GUI_LIBEsto garantiza que QDoc procesará el código que requiere que dichos símbolos estén definidos. Por ejemplo:
#ifdef Q_GUI_LIB
void keyClick(QWidget *widget, Qt::Key key, Qt::KeyboardModifiers modifier = Qt::NoModifier, int delay = -1)
#endifTambién puedes definir símbolos del preprocesador manualmente en la línea de comandos utilizando la opción -D. Por ejemplo:
currentdirectory$ qdoc -Dqtforpython qtgui.qdocconfEn este caso, la opción -D garantiza que el símbolo del preprocesador « qtforpython » quede definido cuando QDoc procese los archivos fuente definidos en el archivo qtgui.qdocconf.
Véase también «falsehoods» y \if.
depende
La variable depends define una lista de otros proyectos de documentación de los que depende este proyecto para resolver los destinos de los enlaces relacionados con la herencia de tipos y cualquier otro elemento al que la documentación necesite enlazar.
Al igual que el propio Qt, la documentación de Qt se distribuye en varios módulos. En un proyecto de documentación con varios módulos, el conjunto mínimo de dependencias para un único módulo consiste en las dependencias reales de compilación. Además, si existe un proyecto de documentación (módulo) que actúa como punto de entrada de primer nivel para todo el conjunto de documentación y proporciona enlaces de navegación, la documentación de cada módulo debería incluirlo como dependencia.
Cuando QDoc genera documentación para un proyecto, también genera un archivo .index que contiene las URL de cada entidad enlazable del proyecto. Cada dependencia es el nombre (en minúsculas) de un proyecto. Este nombre debe coincidir con el nombre base del archivo de índice generado para ese proyecto.
depends = \
qtdoc \
qtcore \
qtquickAl ejecutar QDoc en un proyecto que tiene dependencias y utiliza la variable ` depends `, se deben pasar una o varias rutas ` --indexdir ` como opciones de la línea de comandos. QDoc utiliza estas rutas para buscar los archivos de índice de las dependencias.
qdoc mydoc.qdocconf --outputdir $PWD/html --indexdir $QT_INSTALL_DOCSCon lo anterior, QDoc buscará un archivo $QT_INSTALL_DOCS/qtdoc/qtdoc.index para una dependencia de qtdoc. Si no se encuentra un archivo de índice para una dependencia, QDoc mostrará una advertencia.
El comando depends también acepta un valor especial: «*». Esto indica a QDoc que cargue todos los archivos de índice que se encuentren en los directorios de índice especificados; es decir, «depende de todo».
depends = *Véase también índices, proyecto y url.
documentación en encabezados
Establece documentationinheaders = true para indicar a QDoc que analice también los comentarios de documentación de los archivos de cabecera al generar la documentación para proyectos basados en C++.
Advertencia: en bases de código de gran tamaño, esto puede afectar al tiempo de procesamiento de QDoc. Por lo tanto, no debes activar esta opción a menos que sea necesario.
Esta característica se introdujo en QDoc con Qt 6.9.
exampledirs
La variable « exampledirs » especifica los directorios que contienen el código fuente de los archivos de ejemplo.
Las variables «examples » y «exampledirs » son utilizadas por la \quotefromfile, \quotefile y \example. Si se definen ambas variables, QDoc buscará en ambas, primero en «examples » y luego en «exampledirs».
QDoc buscará en los directorios en el orden especificado y aceptará el primer archivo coincidente que encuentre. Solo buscará en los directorios especificados, no en los subdirectorios.
exampledirs = $QTDIR/doc/src \
$QTDIR/examples \
$QTDIR \
$QTDIR/qmake/examples
examples = $QTDIR/examples/widgets/analogclock/analogclock.cppAl procesar
\quotefromfile widgets/calculator/calculator.cppQDoc comprobará si existe un archivo llamado « calculator.cpp » como valor de la examples variable. Si no lo hay, buscará en la variable exampledirs y comprobará primero si existe un archivo llamado
$QTDIR/doc/src/widgets/calculator/calculator.cppSi no lo hay, QDoc seguirá buscando un archivo llamado
$QTDIR/examples/widgets/calculator/calculator.cppy así sucesivamente.
Véanse también los ejemplos.
ejemplos
La variable examples te permite especificar archivos de ejemplo individuales, además de los que se encuentran en los directorios especificados por la exampledirs variable.
Las variables examples y exampledirs son utilizadas por la \quotefromfile, \quotefile y \example . Si están definidas tanto la variable examples como exampledirs están definidas, QDoc buscará en ambas, primero en examples y luego en exampledirs.
QDoc buscará entre los valores enumerados para la variable ` examples `, en el orden especificado, y aceptará el primero que encuentre.
Para ver un ejemplo detallado, consulta el exampledirs . Pero ten en cuenta que, si sabes que el archivo figura en la variable ` examples `, no es necesario que especifiques su ruta:
\quotefromfile calculator.cppVéase también exampledirs.
examplesinstallpath
La variable « examplesinstallpath » establece la ruta raíz de los ejemplos de este proyecto dentro del directorio de ejemplos instalado.
Suponiendo que la ruta raíz de instalación de todos los ejemplos sea QT_INSTALL_EXAMPLES, entonces la ruta
<QT_INSTALL_EXAMPLES>/<examplesinstallpath>/<example_path>se utilizará para hacer referencia a la ruta de un ejemplo concreto dentro de este proyecto de documentación. Estas rutas se registran en el archivo de manifiesto de los ejemplos, que lee Qt Creator.
Para garantizar que las rutas sean correctas, examplesinstallpath debe coincidir con uno de los directorios que figuran en exampledirs. La ruta pasada como argumento para cada \example comando es relativa a la ruta de «exampledirs».
Por ejemplo:
exampledirs = ./snippets \
../../../examples/mymodule
examplesinstallpath = mymoduleY supongamos el siguiente comando « \example »:
/*!
\example basic/hello
...
*/Entonces, la ruta mymodule/basic/hello queda registrada en el archivo de manifiesto de este ejemplo.
Véase también: exampledirs, \example, y \meta.
ejemplos.extensiones de archivo
La variable « examples.fileextensions » especifica las extensiones de archivo que QDoc buscará al recopilar archivos de ejemplo para mostrarlos en la documentación.
Las extensiones predeterminadas son *.cpp, *.h, *.js, *.xq, *.svg, *.xml y *.ui.
Las extensiones se indican como expresiones estándar con comodines. Puedes añadir una extensión de archivo al filtro utilizando «+=». Por ejemplo:
examples.fileextensions += *.qrcVéase también headers.fileextensions.
ejemplos.advertir_sobre_imágenes_faltantes
Al procesar la documentación de ejemplos, QDoc puede mostrar advertencias si un ejemplo no contiene ninguna imagen. Esta advertencia se puede desactivar configurando la siguiente variable de configuración en el archivo .qdocconf del proyecto:
examples.warnaboutmissingimages = false
Esta variable de configuración se introdujo en QDoc con Qt 6.9.
Véase también examples.warnaboutmissingprojectfiles.
examples.warnaboutmissingprojectfiles
Al procesar la documentación de ejemplos, QDoc puede emitir advertencias si un ejemplo no contiene un archivo de proyecto. Esta advertencia se puede desactivar configurando la siguiente variable de configuración en el archivo .qdocconf del proyecto:
examples.warnaboutmissingprojectfiles = false
Esta variable de configuración se introdujo en QDoc con Qt 6.9.
Véase también examples.warnaboutmissingimages.
excludedirs
La variable « excludedirs » sirve para indicar los directorios que QDoc no debe procesar, incluso si dichos directorios están incluidos en las variables «sourcedirs » o «headerdirs ».
Por ejemplo:
sourcedirs = src/corelib
excludedirs = src/corelib/tmpAl ejecutarse, QDoc excluirá los directorios enumerados de su análisis posterior. QDoc no leerá los archivos que se encuentren en dichos directorios.
Véase también excludefiles.
excludefiles
La variable ` excludefiles ` permite especificar archivos concretos que no deben ser procesados por QDoc.
excludefiles += $QT_CORE_SOURCES/../../src/widgets/kernel/qwidget.h \
$QT_CORE_SOURCES/../../src/widgets/kernel/qwidget.cppSi incluyes lo anterior en tu archivo qdocconf para qtbase, no se generará documentación de clase para QWidget.
Desde Qt 5.6, excludefiles también reconoce los comodines simples («*» y «?»). Por ejemplo, para excluir del análisis todos los archivos de cabecera privados de Qt, define lo siguiente:
excludefiles += "*_p.h"Véase también excludedirs.
extraimages
La variable « extraimages » indica a QDoc que incorpore imágenes específicas en la documentación generada.
QDoc copia automáticamente un archivo de imagen desde imagedirs al directorio de salida si se hace referencia a él mediante la variable \image o \inlineimage . Si deseas copiar imágenes adicionales, debes especificarlas mediante la variable extraimages.
La sintaxis general es format.extraimages = image.
Ejemplo:
HTML.extraimages = images/qt-logo.pngVéanse también las funciones images e imagedirs.
falsedades
La variable « falsehoods » define el valor de verdad de los símbolos del preprocesador especificados como «false».
Los valores de la variable son expresiones regulares (véase QRegularExpression para más detalles). Si esta variable no está definida para un símbolo del preprocesador, QDoc asume que su valor de verdad es verdadero. La excepción es «0», que siempre es falso.
QDoc reconocerá y podrá evaluar la siguiente sintaxis del preprocesador:
#ifdef NOTYET
...
#endif
#if defined (NOTYET)
...
#end ifSin embargo, ante una sintaxis desconocida como
#if NOTYET
...
#endifQDoc la evaluará como verdadera por defecto, a menos que se especifique el símbolo del preprocesador en la entrada de la variable falsehoods:
falsehoods = NOTYETVéase también «defines».
generateindex
La variable generateindex contiene un valor booleano que especifica si se debe generar un archivo de índice al generar la documentación HTML.
Por defecto, siempre se genera un archivo de índice con la documentación HTML, por lo que esta variable solo se suele utilizar para desactivar esta función (estableciendo el valor en « false ») o para habilitar la generación de índices para la salida WebXML (estableciendo el valor en « true »).
headerdirs
La variable headerdirs especifica los directorios que contienen los archivos de cabecera asociados a los archivos fuente .cpp utilizados en la documentación.
headerdirs = $QTDIR/src \
$QTDIR/extensions/activeqt \
$QTDIR/extensions/motif \
$QTDIR/tools/designer/src/lib/extension \
$QTDIR/tools/designer/src/lib/sdk \
$QTDIR/tools/designer/src/lib/uilibAl ejecutarse, lo primero que hará QDoc será leer los encabezados especificados en la headers variable, así como los que se encuentran en los directorios especificados en la variable headerdir (incluidos todos los subdirectorios), creando una estructura interna de las clases y sus funciones.
A continuación, leerá los archivos fuente especificados en la sources, así como los que se encuentran en los directorios especificados en la sourcedirs (incluidos todos los subdirectorios), fusionando la documentación con la estructura que ha obtenido de los archivos de cabecera.
Si se definen ambas variables, headers y headerdirs, QDoc leerá ambas, primero headers luego headerdirs.
En los directorios especificados, QDoc solo leerá los archivos con la extensión fileextensions especificada en la headers.fileextensions variable. Los archivos especificados por headers se leerán sin tener en cuenta sus extensiones de archivo.
Véase también headers y headers.fileextensions.
headers
La variable « headers » permite especificar archivos de encabezado individuales, además de los que se encuentran en los directorios indicados por la headerdirs variable.
headers = $QTDIR/src/gui/widgets/qlineedit.h \
$QTDIR/src/gui/widgets/qpushbutton.hAl procesar la variable headers, QDoc se comporta de la misma manera que al procesar la headerdirs variable. Para obtener más información, consulta la headerdirs variable.
Véase también headerdirs.
headers.fileextensions
La variable « headers.fileextensions » especifica la extensión utilizada por los encabezados.
Al procesar los archivos de cabecera especificados en la headerdirs variable, QDoc solo leerá los archivos con las extensiones especificadas en la variable headers.fileextensions. De esta forma, QDoc evita perder tiempo leyendo archivos irrelevantes.
Las extensiones por defecto son *.ch, *.h, *.h++, *.hh, *.hpp y *.hxx.
Las extensiones se indican como expresiones estándar con comodines. Puedes añadir una extensión de archivo al filtro utilizando «+=». Por ejemplo:
header.fileextensions += *.HAdvertencia: Es posible quela asignación anterior no funcione tal y como se describe.
Véase también headerdirs.
includepaths
La variable « includepaths » se utiliza para pasar rutas de inclusión adicionales al analizador de Clang que utiliza QDoc para analizar el código C++ en busca de comentarios de documentación.
La variable acepta una lista de rutas, precedidas por el prefijo -I (ruta de inclusión), -F (ruta de inclusión de marcos de macOS) o -isystem (ruta de inclusión del sistema). Si se omite el prefijo, se utiliza por defecto -I.
Las rutas relativas al archivo .qdocconf actual se convierten en rutas absolutas. Las rutas que no existen en el sistema de archivos se ignoran.
Nota: En los proyectos de documentación de Qt, el sistema de compilación suele proporcionar las rutas de inclusión necesarias como argumentos de línea de comandos al invocar QDoc.
Véase también moduleheader.
includeprivate
Utiliza « includeprivate » para incluir miembros privados de clases C++ en tu documentación. QDoc suele excluir las funciones, los tipos y las variables privadas de la documentación generada.
Para incluir todos los miembros privados, configura « includeprivate » en « true »:
includeprivate = trueTambién puedes habilitar tipos de miembros específicos:
# Include only private functions
includeprivate.functions = true
# Include only private types (classes, enums, typedefs)
includeprivate.types = true
# Include only private variables
includeprivate.variables = trueLa configuración específica prevalece sobre la configuración global. Por ejemplo:
includeprivate = true
includeprivate.types = falseEsta configuración incluye funciones y variables privadas, pero excluye los tipos privados.
Nota: Documenta los miembros privados solo cuando sea necesario explicar las API internas y los detalles de implementación. Evita revelar detalles de implementación que los usuarios no necesiten.
QDoc introdujo includeprivate en Qt 6.11.
internalfilepatterns
La variable internalfilepatterns especifica patrones de ruta de archivo que identifican los archivos de implementación interna. Las clases declaradas en archivos que coincidan con estos patrones se marcan automáticamente como «Internal», junto con todos sus miembros (propiedades, funciones, enumeraciones y tipos anidados). Las funciones libres, las enumeraciones y los typedefs en el ámbito del archivo no se ven afectados por esta configuración.
Cuando `showinternal` es ` false ` (el valor por defecto), estas entidades se excluyen de la validación de la documentación. Cuando ` showinternal ` es ` true`, se incluyen en la documentación pero conservan su estado «Internal», lo que permite a los generadores aplicarles un estilo diferente (como añadir indicadores visuales para las API internas).
Esto resulta útil para los encabezados de implementación privados que contienen clases que no forman parte de la interfaz pública documentada. En Qt, esto incluye los encabezados privados que terminan en _p.h.
Sintaxis del patrón
Los patrones admiten dos sintaxis:
- Patrones «glob» al estilo de Shell: comodines sencillos en los que «
*» coincide con cualquier carácter y «?» coincide con exactamente un carácter. Los patrones «glob» se comparan únicamente con el nombre del archivo, no con la ruta completa, lo que los hace ideales para patrones como «*_p.h». - Expresiones regulares: para la coincidencia basada en la ruta, utiliza la sintaxis de expresiones regulares. Cualquier patrón que contenga metacaracteres de expresiones regulares (
^$[]{}()|+\\.) se trata como una expresión regular y se compara con la ruta completa normalizada del archivo.
Los patrones se comparan utilizando barras (/) como separadores de directorios. QDoc normaliza internamente los separadores de ruta, por lo que siempre debes utilizar / en los patrones, independientemente de la plataforma.
Cuando una clase se marca como «Internal» debido a la ubicación de su archivo, el estado «Internal» se propaga automáticamente a todos sus miembros a través de la jerarquía de nodos.
Ejemplo: convención de Qt (glob):
internalfilepatterns = *_p.hCoincide con cualquier archivo que termine en _p.h, independientemente de la profundidad del directorio.
Ejemplo: varios patrones de nombres de archivo (glob):
internalfilepatterns = *_p.h *_impl.h *_pch.hCoincide con archivos que terminen en _p.h, _impl.h o _pch.h.
Nota: Los patronesglob no funcionan para la búsqueda de directorios, ya que solo tienen en cuenta el nombre del archivo. Para patrones basados en directorios, utiliza expresiones regulares (regex) en su lugar.
Ejemplo: coincidencia basada en directorios (expresiones regulares):
internalfilepatterns = .*/internal/.*\.hCoincide con cualquier archivo .h en cualquier directorio internal a cualquier profundidad.
Ejemplo: patrones múltiples:
internalfilepatterns = *_p.h .*/private/.*\.hCombina patrones glob para casos sencillos con expresiones regulares para rutas complejas.
QDoc introdujo la función « internalfilepatterns » en Qt 6.11.
Véase también: excludedirs y excludefiles.
ignorewords
La variable ignorewords se utiliza para especificar una lista de cadenas que QDoc ignorará al resolver los destinos de los hipervínculos.
QDoc cuenta con una función de creación automática de enlaces, mediante la cual se intenta crear enlaces para palabras que se asemejen a entidades de C++ o QML. Concretamente, una cadena cumple los requisitos para la creación automática de enlaces si tiene una longitud mínima de tres caracteres, no contiene espacios en blanco y
- es una palabra en «camelCase», es decir, contiene al menos un carácter mayúsculo en un índice mayor que cero, o
- contiene la subcadena «
()» o «::», o - contiene al menos un carácter especial, como «
@» o «_».
Añadir un calificativo a « ignorewords » impide que QDoc enlace esa palabra automáticamente. Por ejemplo, si la palabra «OpenGL» es un destino de enlace válido (una sección, \pageo \externalpage título), se puede evitar que se cree un hipervínculo cada vez que aparece utilizando
ignorewords += OpenGLEl enlace explícito con \l sigue funcionando para las palabras ignoradas.
La variable ` ignorewords ` se introdujo en QDoc 5.14.
ignoresince
La variable ignoresince se utiliza para establecer un valor de corte para las versiones pasadas al \since comando. Todos los comandos « \since » que definan una versión inferior al valor de corte se ignoran y no generan salida.
Los valores de corte son específicos de cada proyecto. El nombre del proyecto se puede definir como una subvariable. El nombre predeterminado del proyecto es Qt. Por ejemplo:
ignoresince = 5.0
ignoresince.QDoc = 5.0Esto ignorará los comandos ` \since ` en los que la versión principal sea 4 o inferior y el proyecto sea « QDoc » o esté sin definir.
\since 3.2 # Ignored
\since 5.2 # Documented (as 'Qt 5.2')
\since QDoc 4.6 # Ignored
\since QtQuick 2.5 # DocumentedLa variable ignoresince se introdujo en QDoc 5.15.
Véase también \since.
imagedirs
La variable ` imagedirs ` especifica los directorios que contienen las imágenes utilizadas en la documentación.
Las images y imagedirs son utilizadas por la \image y \inlineimage . Si se definen ambas variables, images y imagedirs están definidas, QDoc buscará en ambas. Primero en images, y después en imagedirs.
QDoc buscará en los directorios en el orden especificado y aceptará el primer archivo coincidente que encuentre. Solo buscará en los directorios especificados, no en los subdirectorios.
imagedirs = $QTDIR/doc/src/images \
$QTDIR/examples
images = $QTDIR/doc/src/images/calculator-example.pngAl procesar
\image calculator-example.pngQDoc comprobará entonces si hay un archivo llamado calculator-example.png incluido como valor en la variable images. Si no lo hay, buscará en la variable imagedirs:
$QTDIR/doc/src/images/calculator-example.pngSi el archivo no existe, QDoc buscará un archivo llamado
$QTDIR/examples/calculator-example.pngimagesoutputdir
La variable imagesoutputdir controla el nombre del subdirectorio, dentro del directorio de salida, que QDoc utiliza para almacenar las imágenes.
El valor por defecto de imagesoutputdir es «images».
Los archivos de imagen pasados como argumento a \image y \inlineimage se copian en este directorio.
Establecer un directorio de salida personalizado para las imágenes resulta útil en compilaciones de documentación con varios módulos, en las que se configuran varios proyectos de documentación para que utilicen un directorio de salida compartido. Por ejemplo, con la siguiente configuración (compartida):
imagesoutputdir = images/${project}Cada proyecto de documentación de la compilación utiliza <outputdir>/images/<project name> para almacenar imágenes, evitando así que los archivos de imagen con el mismo nombre se sobrescriban entre sí.
Esta variable se introdujo en QDoc con Qt 6.11.
idioma
La variable ` language ` especifica el idioma del código fuente que se utiliza en la documentación. En concreto, define el idioma predeterminado para analizar el código fuente dentro de los bloques ` \code ` y ` \endcode `.
language = CppEl idioma por defecto es C++ (Cpp) y no es necesario especificarlo explícitamente. Si los fragmentos de código de la documentación consisten principalmente en código QML, establece QML como idioma por defecto:
language = QMLVéase también \code.
información sobre la ubicación
La variable booleana « locationinfo » determina si la información detallada sobre la ubicación de cada entidad se escribe en los archivos « .index » y « .webxml » (cuando se utiliza el formato de salida WebXML).
La información de ubicación consiste en la ruta completa y el número de línea de la declaración o del bloque de comentarios de documentación en el código fuente.
Si se establece en « false », se desactiva la información de ubicación:
locationinfo = falseEl valor por defecto es « true ».
La variable « locationinfo » se introdujo en QDoc 5.15.
logwarnings
La variable booleana logwarnings determina si QDoc escribe mensajes de advertencia en un archivo de registro, además de en stderr.
Cuando se establece en « true », QDoc crea un archivo de registro llamado « <project>-qdoc-warnings.log » en el directorio de salida y escribe todos los mensajes de advertencia en este archivo. Las advertencias también se siguen escribiendo en stderr, como de costumbre.
El archivo de registro incluye un encabezado con información del proyecto y, por defecto, los argumentos de la línea de comandos utilizados para ejecutar QDoc, con el fin de garantizar la reproducibilidad.
Al establecer este valor en « true », se habilita el registro de advertencias:
logwarnings = trueEl valor por defecto es « false ».
Esta función resulta útil para conjuntos de documentación extensos o entornos de integración continua (CI), en los que las advertencias pueden ser numerosas y pasar demasiado rápido como para analizarlas de forma sistemática.
La variable logwarnings se introdujo en QDoc 6.11.
logwarnings.disablecliargs
La subvariable booleana logwarnings.disablecliargs controla si se omiten los argumentos de la CLI en los encabezados de los archivos de registro de advertencias.
logwarnings.disablecliargs = trueCuando se establece en « true », los argumentos de la línea de comandos se omiten del encabezado del archivo de registro, lo que hace que los archivos de registro sean portables entre diferentes entornos. Esto resulta útil para conjuntos de pruebas y sistemas de integración continua (CI), en los que los argumentos de la línea de comandos contienen rutas específicas del entorno y directorios temporales.
El valor por defecto es « false ». La variable « logwarnings.disablecliargs » se introdujo en QDoc 6.11.
macro
La variable macro se utiliza para crear tus propios comandos sencillos de QDoc. La sintaxis es macro.command = definition. El comando se limita a una combinación de letras y números, pero no admite caracteres especiales como el guión o el guión bajo. La definición se escribe utilizando la sintaxis de QDoc.
El uso de una variable de macro puede restringirse a un tipo concreto de generación de salida. Al añadir « .HTML » al nombre de la macro, por ejemplo, esta solo se utilizará al generar salida HTML.
macro.key = "\\b"
macro.raisedaster.HTML = "<sup>*</sup>"La primera macro define el comando « \key » para mostrar su argumento en negrita. La segunda macro define el comando « \raisedaster » para mostrar un asterisco en superíndice, pero solo al generar HTML.
Una macro también puede admitir hasta siete parámetros:
macro.hello = "Hello \1!"Los parámetros se pasan a las macros de la misma forma que a otros comandos:
\hello WorldCuando se utilice más de un parámetro, o cuando un argumento contenga espacios en blanco, hay que encerrar cada argumento entre llaves:
macro.verinfo = "\1 (version \2)"\verinfo {QFooBar} {1.0 beta}Se puede añadir una opción especial de macro, «match», para realizar una coincidencia adicional de patrones de expresiones regulares en las macros expandidas.
Por ejemplo,
macro.qtminorversion = "$QT_VER"
macro.qtminorversion.match = "\\d+\\.(\\d+)"Esto crea una macro « \qtminorversion » que se expande a la versión menor en función de la variable de entorno QT_VER.
Una macro que define un patrón de coincidencia muestra todos los grupos de captura (paréntesis) concatenados entre sí, o la cadena que coincide exactamente si el patrón no contiene ningún grupo de captura.
Para obtener más información sobre las macros predefinidas, consulta Macros.
manifestmeta
La variable « manifestmeta » especifica metadatos adicionales para los archivos de manifiesto de ejemplo generados por QDoc.
Consulte la sección «Contenido meta del manifiesto » para obtener más información.
moduleheader
La variable « moduleheader » define el nombre del encabezado de un módulo C++ documentado.
Los proyectos que documentan API de C++ requieren un encabezado a nivel de módulo que incluya todas las clases públicas, los espacios de nombres y los archivos de encabezado del módulo. El analizador sintáctico de Clang de QDoc utiliza este archivo para generar un encabezado precompilado (PCH) para el módulo, con el fin de aumentar la velocidad de análisis de los archivos fuente.
Por defecto, el nombre del proyecto se utiliza también como nombre del encabezado del módulo.
project = QtCoreCon el nombre de proyecto anterior, QDoc busca un encabezado de módulo llamado QtCore en todas las rutas de inclusión conocidas; primero utiliza las rutas pasadas como argumentos de la línea de comandos y, a continuación, las rutas enumeradas en la variable `includepaths`.
QDoc emitirá una advertencia si no encuentra el encabezado del módulo. A continuación, intentará crear un encabezado de módulo artificial basándose en los encabezados que figuran en la variable `headerdirs`.
En los proyectos de documentación de Qt, el sistema de compilación suele proporcionar a QDoc las rutas de inclusión correctas para localizar el encabezado del módulo, siempre que la variable ` project ` esté configurada correctamente. La variable ` moduleheader ` proporciona un nombre de archivo alternativo que QDoc debe buscar.
Para proyectos que no contengan documentación en C++, utilice la parsecppcomments para desactivar el análisis sintáctico de C++. Establecer moduleheader en una cadena vacía tiene el mismo efecto y se admite por motivos de compatibilidad con versiones anteriores:
# No C++ code to document in this project
moduleheader =Véase también parsecppcomments, includepaths y project.
lenguaje natural
La variable « naturallanguage » especifica el idioma natural utilizado para la documentación generada por QDoc.
naturallanguage = zh-HansPor defecto, el idioma natural es « en » para garantizar la compatibilidad con la documentación heredada.
QDoc añadirá la información sobre el idioma natural al código HTML que genere, utilizando los atributos « lang » y « xml:lang ».
Véase también «sourceencoding», «outputencoding», C.7. Los atributos «lang» y «xml:lang» y la buena práctica 13: Uso de los códigos Hans y Hant.
navegación
Las subvariables « navigation », si se definen, establecen la página de inicio, la página de destino, la página de clases de C++ y la página de tipos de QML que se muestran en la barra de navegación generada para cada página.
En un proyecto con varios subproyectos (por ejemplo, módulos Qt), cada subproyecto suele definir su propia página de destino, mientras que se utiliza la misma página de inicio en todos los subproyectos.
Subvariables
navigation.homepage | Página de inicio del proyecto. |
navigation.hometitle | (Opcional) Título de la página de inicio visible para el usuario. El valor por defecto se toma de homepage. |
navigation.landingpage | Página de destino del subproyecto. |
navigation.landingtitle | (Opcional) Título visible para el usuario de la página de inicio. El valor por defecto se toma de landingpage. |
navigation.cppclassespage | Página de nivel superior que enumera todas las clases de C++ de este (sub)proyecto. Normalmente, el título de una \module página. |
navigation.cppclassestitle | (Opcional) Título visible para el usuario de la página de clases de C++. El valor por defecto es «Clases de C++». |
navigation.qmltypespage | Página de primer nivel que enumera todos los tipos QML de este (sub)proyecto. Normalmente, el título de una \qmlmodule página. |
navigation.qmltypestitle | (Opcional) Título visible para el usuario de la página de tipos de QML. El valor por defecto es «Tipos de QML». |
navigation.toctitles (Desde QDoc 6.0) | Título(s) de página que contiene una \list estructura que actúa como índice (TOC). QDoc genera enlaces de navegación para las páginas que aparecen en el índice, sin necesidad de \nextpage y \previouspage , así como una jerarquía de navegación visible en la barra de navegación (ruta de navegación) para la salida en HTML. |
navigation.toctitles.inclusive (Desde QDoc 6.3) | Si se establece en « true », las páginas que figuran en « navigation.toctitles » también aparecerán en la barra de navegación como elemento raíz. |
navigation.trademarkspage (Desde QDoc 6.8) | Título de una página que documenta las marcas registradas mencionadas en la documentación. Véase también \tm comando. |
Por ejemplo:
# Common configuration
navigation.homepage = index.html
navigation.hometitle = "Qt $QT_VER"
# qtquick.qdocconf
navigation.landingpage = "Qt Quick"
navigation.cppclassespage = "Qt Quick C++ Classes"
navigation.qmltypespage = "Qt Quick QML Types"La configuración anterior genera la siguiente barra de navegación para el tipo QML « Item »:
Qt 5.10 > Qt Quick > QML Types > Item QML TypeÍndice y enlaces de navegación
Si hay una o más páginas que actúan como índice (TOC), enumera sus títulos en navigation.toctitles para automatizar la generación de enlaces de navegación (páginaanterior y siguiente ) para todas las páginas que figuran en el índice.
QDoc espera encontrar una \list en cada página del TOC. Se permiten sublistas anidadas.
Por ejemplo,
\list
\li \l {Home}
\li \l {Getting started}
\li What's new
\list
\li \l {What's new in v1.3} {v1.3}
\li \l {What's new in v1.2} {v1.2}
\li \l {What's new in v1.1} {v1.1}
\endlist
\endlistDesde la versión 6.10 de QDoc, también \generatelist pueden aparecer en la lista de la tabla de contenidos:
\list
\li \l {Home}
\li \l {Getting started}
\li What's new
\generatelist [descending] whatsnew
\endlistEn este caso, el resultado es similar al del primer \list, suponiendo que las tres páginas «Novedades» formen parte del mismo grupo whatsnew.
Véase también \ingroup.
overloadedsignalstarget
Valor por defecto: connecting-overloaded-signals
La variable « overloadedsignalstarget » especifica el destino del enlace que se utiliza en las notas generadas automáticamente para las señales sobrecargadas.
Cuando QDoc encuentra una señal sobrecargada, genera una nota con un enlace a la documentación de ayuda sobre cómo conectarse a señales sobrecargadas. Por defecto, este enlace apunta a un destino denominado connecting-overloaded-signals.
Los proyectos pueden personalizar esto para que el enlace apunte a su propia documentación:
# Link to a target within the project
overloadedsignalstarget = signals-guide.html#overloaded-signals
# Link to external documentation
overloadedsignalstarget = https://example.com/docs/signals.html#overloaded-signalsEl destino puede ser:
- Un nombre de destino sencillo (para su uso con
\targetlos comandos):connecting-overloaded-signals - Una URL relativa:
signals-guide.html#overloaded-signals - Una URL absoluta:
https://example.com/docs/signals.html#overloaded-signals
Véase también «overloadedslotstarget».
overloadedslotstarget
Valor por defecto: connecting-overloaded-slots
La variable « overloadedslotstarget » especifica el destino del enlace que se utiliza en las notas generadas automáticamente para las ranuras sobrecargadas.
Cuando QDoc encuentra un slot sobrecargado, genera una nota con un enlace a la documentación de ayuda sobre cómo conectarse a los slots sobrecargados. Por defecto, este enlace apunta a un destino denominado connecting-overloaded-slots.
Los proyectos pueden personalizar esta configuración para que el enlace apunte a su propia documentación:
# Link to a target within the project
overloadedslotstarget = signals-guide.html#overloaded-slots
# Link to external documentation
overloadedslotstarget = https://example.com/docs/slots.html#overloaded-slotsEl destino puede ser:
- Un nombre de destino sencillo (para su uso con
\targetlos comandos):connecting-overloaded-slots - Una URL relativa:
signals-guide.html#overloaded-slots - Una URL absoluta:
https://example.com/docs/slots.html#overloaded-slots
Véase también overloadedsignalstarget.
outputdir
La variable outputdir especifica el directorio en el que QDoc guardará la documentación generada.
outputdir = $QTDIR/doc/htmlubica la documentación de referencia de Qt generada en $QTDIR/doc/html. Por ejemplo, la documentación de la clase QWidget se encuentra en
$QTDIR/doc/html/qwidget.htmlLas imágenes asociadas se colocarán en un subdirectorio llamado « images ».
Advertencia: al ejecutar QDoc varias veces utilizando el mismo directorio de salida, se perderán todos los archivos de la ejecución anterior.
codificación de salida
La variable outputencoding especifica la codificación utilizada para la documentación generada por QDoc.
outputencoding = UTF-8Por defecto, la codificación de salida es ISO-8859-1 (Latin1) para garantizar la compatibilidad con la documentación heredada. Al generar documentación para algunos idiomas, especialmente los no europeos, esto no es suficiente y se requiere una codificación como UTF-8.
QDoc codificará el HTML utilizando esta codificación y generará las declaraciones correctas para indicar a los navegadores qué codificación se está utilizando. También se debe especificar la variable de configuración `naturallanguage ` para proporcionar a los navegadores un conjunto completo de información sobre la codificación de caracteres y el idioma.
Véanse también «outputencoding » y «naturallanguage».
formatos_de_salida
La variable « outputformats » especifica el formato o formatos de la documentación generada.
Desde Qt 5.11, QDoc admite los formatos HTML y WebXML; desde Qt 5.15, también puede generar la documentación en DocBook. Si no se especifica ningún outputformats, QDoc genera la documentación en HTML (el formato predeterminado). Se pueden especificar todos los formatos de salida, con directorios de salida específicos y otros ajustes. Por ejemplo:
outputformats = WebXML HTML
WebXML.nosubdirs = true
WebXML.outputsubdir = webxml
WebXML.quotinginformation = trueEsto genera documentación HTML utilizando la configuración predeterminada, así como documentación WebXML en el subdirectorio de salida webxml.
prefijos de salida
La variable outputprefixes especifica una correspondencia entre los tipos de archivos y los prefijos que se antepondrán a los nombres de los archivos de salida en la documentación generada.
QDoc permite añadir un prefijo de salida a los nombres de los archivos de las páginas de referencia de tipos QML, clases C++, espacios de nombres y archivos de cabecera.
outputprefixes = QML CPP
outputprefixes.QML = uicomponents-
outputprefixes.CPP = components-Por defecto, los archivos que contienen la documentación de la API para los tipos QML llevan el prefijo qml-. En el ejemplo anterior, se utiliza en su lugar el prefijo uicomponents-.
Del mismo modo, las páginas de documentación de tipos de C++ llevan el prefijo components- en el ejemplo anterior. Por defecto, las páginas de tipos de C++ no tienen prefijo.
sufijos de salida
La variable outputsuffixes especifica una correspondencia entre los tipos de archivo y los sufijos que se deben aplicar al nombre del módulo o del tipo tal y como aparecen en los nombres de los archivos de salida.
QDoc permite añadir un sufijo de salida a los nombres de los archivos de las páginas de módulos, de tipos QML, de clases C++, de espacios de nombres y de páginas de referencia de archivos de encabezado.
Por defecto, no se utiliza ningún sufijo. El sufijo de salida de QML, si se define, se aplica como sufijo al nombre del módulo tal y como aparece en los nombres de archivo de las páginas de tipos QML y módulos QML.
Los nombres de archivo de los tipos de C++ no incluyen el nombre del módulo. El sufijo de salida CPP, si se define, se aplica como sufijo al nombre del tipo.
outputsuffixes = QML CPP
{outputsuffixes.QML,outputsuffixes.CPP} = -tpCon las definiciones anteriores, dado un nombre de módulo QML «FooBar» y el prefijo de salida predeterminado (qml-), el nombre del archivo generado para un tipo QML «FooWidget» es qml-foobar-tp-foowidget.html.
Del mismo modo, para una clase de C++ QFoobar, QDoc genera qfoobar-tp.html.
La variable outputsuffixes se introdujo en QDoc 5.6.
parsecppcomments
La variable parsecppcomments controla si QDoc analiza los archivos fuente de C++ utilizando el analizador sintáctico de C++ basado en Clang.
Cuando se establece en « false », QDoc omite el análisis de Clang y la generación de PCH para el proyecto, y procesa los archivos « .cpp » utilizando en su lugar el analizador de documentación puro. Esto resulta útil para proyectos que solo documentan API de QML, en los que los archivos fuente de C++ contienen comentarios de QDoc pero ninguna entidad de C++ que documentar.
El valor por defecto es « true ».
parsecppcomments = falseNota: Establecer moduleheader una cadena vacía tiene el mismo efecto y se admite por motivos de compatibilidad con versiones anteriores. « parsecppcomments » es la forma recomendada de expresar esta intención.
La variable parsecppcomments se introdujo en QDoc con Qt 6.12.
Véase también moduleheader.
qhp
Las subvariables « qhp » se utilizan para definir la información que se va a escribir en los archivos de un proyecto de « Qt Help » (qhp).
Consulte el capítulo «Creación de archivos de proyectos de ayuda » para obtener información sobre este proceso.
Desde QDoc 6.6, al establecer la variable base « qhp » en « true », se espera una configuración válida del proyecto de ayuda:
qhp = trueAsí, si una configuración de proyecto no ha definido qhp.projects, QDoc emite una advertencia. Esto resulta útil para garantizar que todos los proyectos de documentación que compartan un archivo .qdocconf de nivel superior (como en Qt) estén configurados correctamente.
Para desactivar la advertencia, establece la variable en false.
showautogenerateddocs
La variable booleana ` showautogenerateddocs ` determina si la documentación que QDoc genera automáticamente para las funciones miembro especiales con valores por defecto explícitos y eliminadas aparece en la salida.
QDoc genera esta documentación cuando ningún \fn bloque documente dicha función. La documentación escrita con \fn siempre tiene prioridad sobre el texto generado y no se ve afectada por esta variable.
Si se establece en « false », se omite la documentación generada automáticamente:
showautogenerateddocs = falseEl valor por defecto es true.
La variable « showautogenerateddocs » se introdujo en QDoc 6.12.
sourcedirs
La variable sourcedirs especifica los directorios que contienen los archivos .cpp o .qdoc utilizados en la documentación.
sourcedirs += .. \
../../../examples/gui/doc/srcAl ejecutarse, lo primero que hará QDoc es leer los encabezados especificados en la header variable, así como los que se encuentran en los directorios especificados en la variable headerdir (incluidos todos los subdirectorios), creando una estructura interna de las clases y sus funciones.
A continuación, leerá los archivos fuente especificados en la sources, así como los que se encuentran en los directorios especificados en la sourcedirs (incluidos todos los subdirectorios), fusionando la documentación con la estructura que ha obtenido de los archivos de cabecera.
Si se definen ambas variables, « sources » y « sourcedirs », QDoc leerá ambas, primero sources luego sourcedirs.
En los directorios especificados, QDoc solo leerá los archivos con el fileextensions especificado en la sources.fileextensions variable. Los archivos especificados por sources se leerán independientemente de sus extensiones.
Véase también sources y sources.fileextensions.
sourceencoding
La variable « sourceencoding » especifica la codificación utilizada para el código fuente y la documentación.
sourceencoding = UTF-8Por defecto, la codificación del código fuente es ISO-8859-1 (Latin1) para garantizar la compatibilidad con la documentación heredada. Para algunos idiomas, especialmente los no europeos, esto no es suficiente y se requiere una codificación como UTF-8.
Aunque QDoc utilizará esta codificación para leer los archivos fuente y de documentación, las limitaciones de los compiladores de C++ pueden impedirte utilizar caracteres no ASCII en los comentarios del código fuente. En casos como estos, es posible escribir la documentación de la API íntegramente en archivos de documentación.
Véase también «naturallanguage » y «outputencoding».
fuentes
La variable « sources » permite especificar archivos fuente individuales, además de los que se encuentran en los directorios indicados por la variable «sourcedirs ».
sources = $QTDIR/src/gui/widgets/qlineedit.cpp \
$QTDIR/src/gui/widgets/qpushbutton.cppAl procesar la variable ` sources `, QDoc se comporta de la misma manera que al procesar la variable `sourcedirs`. Para obtener más información, consulta la variable `sourcedirs `.
Véase también «sourcedirs».
sources.fileextensions
La variable « sources.fileextensions » filtra los archivos de un directorio de origen.
Al procesar los archivos fuente especificados en la sourcedirs variable, QDoc solo leerá los archivos con las extensiones especificadas en la variable sources.fileextensions. De esta forma, QDoc evita perder tiempo leyendo archivos irrelevantes.
Las extensiones predeterminadas son *.c++, *.cc, *.cpp, *.cxx, *.mm, *.qml y *.qdoc.
Las extensiones se indican como expresiones estándar con comodines. Puedes añadir una extensión de archivo al filtro utilizando «+=». Por ejemplo:
sources.fileextensions += *.CCAdvertencia: es posible quela asignación anterior no funcione tal y como se describe.
Véase también sourcedirs y sources.
espurio
La variable « spurious » excluye de la salida las advertencias de QDoc especificadas. Las advertencias se especifican mediante expresiones estándar con comodines.
spurious = "Cannot find .*" \
"Missing .*"garantiza que las advertencias que coincidan con cualquiera de estas expresiones no se incluyan en la salida al ejecutar QDoc. Por ejemplo, ¿se omitiría la siguiente advertencia de la salida?:
src/opengl/qgl_mac.cpp:156: Missing parameter nameresaltado de sintaxis
La variable ` syntaxhighlighting ` especifica si QDoc debe aplicar resaltado de sintaxis al código fuente citado en la documentación que genera.
syntaxhighlighting = trueactivará el resaltado de sintaxis para todos los lenguajes de programación compatibles.
tabsize
La variable « tabsize » define el tamaño del carácter de tabulación.
tabsize = 4asignará al carácter de tabulación un tamaño equivalente a 4 espacios. El valor por defecto de la variable es 8, y no es necesario especificarlo.
archivo de etiquetas
La variable ` tagfile ` especifica el archivo de etiquetas de Doxygen que se generará al crear el código HTML.
versión
La variable version especifica el número de versión del software documentado.
version = 5.6.0Cuando se especifica un número de versión (utilizando la version o versionsym en un archivo ` .qdocconf `), se puede acceder a él mediante el comando correspondiente ` \version ` para utilizarlo en la documentación.
Advertencia: La funcionalidad del comando \version no está totalmente implementada; actualmente solo funciona dentro de código HTML sin formato.
Véase también versionsym.
versionsym
La variable ` versionsym ` especifica un símbolo del preprocesador de C++ que define el número de versión del software documentado.
versionsym = QT_VERSION_STRQT_VERSION_STR Se define en qglobal.h de la siguiente manera
#define QT_VERSION_STR "5.14.1"Cuando se especifica un número de versión (utilizando la version o versionsym en un archivo ` .qdocconf `), se puede acceder a él mediante el comando correspondiente ` \version ` para utilizarlo en la documentación.
Advertencia: La funcionalidad del comando « \version » no está totalmente implementada. Actualmente, solo funciona dentro de código HTML sin formato.
Véase también \version.
warninglimit
La variable ` warninglimit ` establece el número máximo de advertencias de documentación permitidas. Si se supera este límite, QDoc continúa con normalidad, pero finaliza con el recuento de advertencias como código de error. Si no se ha superado el límite o no se ha definido ` warninglimit `, el proceso de QDoc finaliza con 0, siempre que no haya habido otros errores críticos.
Establecer ` warninglimit ` en ` 0 ` implica un error ante cualquier advertencia.
Nota: Por defecto, QDoc no aplica el límite de advertencias. Actívalo con warninglimit.enabled = true o definiendo la variable de entorno QDOC_ENABLE_WARNINGLIMIT.
Por ejemplo,
# Fail the documentation build if we have more than 100 warnings
warninglimit = 100
warninglimit.enabled = trueLa variable warninglimit se introdujo en Qt 5.11.
© 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.