Variables genéricas de configuración

Con las variables generales de configuración de QDoc, puede definir dónde encontrará QDoc los distintos archivos fuente que necesita para generar la documentación, así como el directorio donde colocar la documentación generada. También puede realizar algunas manipulaciones menores del propio QDoc, controlando su comportamiento de salida y procesamiento.

codeindent

La variable codeindent especifica el nivel de sangría que QDoc utiliza 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 pudieran distinguirse fácilmente del texto circundante. Dado que podemos usar hojas de estilo para ajustar la apariencia de ciertos tipos de elementos HTML, este nivel de sangría no siempre es necesario.

codelenguajes

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 HTML que puede ser resaltado o procesado por otras herramientas.

codelanguages = Python Rust Java Swift "C#"

Dado que QDoc puede manejar 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 entrecomillarse con 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 idiomas admitidos por highlight.js.

Véase también \code.

codeprefix, codesuffix

Las variables codeprefix y codesuffix especifican un par de cadenas en las que se encierra cada fragmento de código.

define

La variable defines especifica los símbolos del preprocesador C++ que QDoc reconocerá y a los que responderá.

Cuando se especifica un símbolo de preprocesador mediante la variable defines, también se puede utilizar el comando \if para incluir documentación que sólo se incluirá si el símbolo de preprocesador está definido.

defines = QT_GUI_LIB

Esto asegura que QDoc procesará el código que requiera que estos 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)
#endif

También puede definir símbolos de preprocesador manualmente en la línea de comandos utilizando la opción -D. Por ejemplo:

currentdirectory$ qdoc -Dqtforpython qtgui.qdocconf

En este caso, la opción -D garantiza que el símbolo de preprocesador qtforpython se defina cuando QDoc procese los archivos fuente definidos en el archivo qtgui.qdocconf.

Véase también \if.

depende

La variable depends define una lista de otros proyectos de documentación de los que depende este proyecto para resolver los objetivos de enlace para la herencia de tipos y cualquier otra cosa a la que la documentación necesite enlazar.

Al igual que Qt, la documentación de Qt está distribuida en múltiples módulos. En un proyecto de documentación multimódulo, el conjunto mínimo de dependencias para un único módulo consiste en las dependencias de compilación reales. Además, si hay un proyecto de documentación (módulo) que actúa como punto de entrada de nivel superior para todo el conjunto de documentación y proporciona enlaces de navegación, la documentación de cada módulo debe incluirlo como dependencia.

Cuando QDoc genera documentación para un proyecto, también generará un archivo .index que contiene las direcciones URL de cada entidad vinculable del proyecto. Cada dependencia es un 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 \
    qtquick

Al invocar QDoc en un proyecto que tiene dependencias y utiliza la variable depends, se debe pasar una o más rutas -indexdir como opción(es) de 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_DOCS

Con lo anterior, QDoc buscará un archivo $QT_INSTALL_DOCS/qtdoc/qtdoc.index para una dependencia a qtdoc. Si no se encuentra un archivo de índice para una dependencia, QDoc emitirá una advertencia.

El comando depends acepta también un valor especial de '*'. Esto indica a QDoc que cargue todos los archivos de índice encontrados en los directorios de índice especificados; es decir, "depende de todo".

depends = *

Véase también índices, proyecto y url.

documentaciónencabeceras

Establece documentationinheaders = true para indicar a QDoc que analice los comentarios de la documentación también en los archivos de cabecera cuando genere documentación para proyectos basados en C++.

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 los programas \quotefromfile, \quotefile y \example . Si se definen las variables examples y exampledirs, 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. Sólo 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.cpp

Al procesar

\quotefromfile widgets/calculator/calculator.cpp

QDoc verá si hay un archivo llamado calculator.cpp listado como valor en la variable examples como valor. Si no lo hay, buscará en la variable exampledirs, y verá primero si existe un fichero llamado

$QTDIR/doc/src/widgets/calculator/calculator.cpp

Si no existe, QDoc seguirá buscando un fichero llamado

$QTDIR/examples/widgets/calculator/calculator.cpp

y así sucesivamente.

Véanse también los ejemplos.

ejemplos

La variable examples permite especificar archivos de ejemplo individuales además de los ubicados en los directorios especificados por la variable exampledirs la variable.

Las variables examples y exampledirs son utilizadas por las variables \quotefromfile, \quotefile y \example . Si las variables examples y exampledirs QDoc buscará en ambas, primero en examples y luego en exampledirs.

QDoc buscará entre los valores listados para la variable examples, en el orden especificado, y aceptará el primero que encuentre.

Para ver un ejemplo más detallado, consulte el comando exampledirs . Pero tenga en cuenta que si sabe que el archivo está listado en la variable examples, no necesita especificar su ruta:

\quotefromfile calculator.cpp

Véase también exampledirs.

ejemplosrutainstalación

La variable examplesinstallpath establece la ruta raíz para los ejemplos de este proyecto bajo el directorio de ejemplos instalado.

Asumiendo una ruta raíz de instalación de QT_INSTALL_EXAMPLES para todos los ejemplos, entonces la ruta

<QT_INSTALL_EXAMPLES>/<examplesinstallpath>/<example_path>

se utilizará para referirse a la ruta de un único ejemplo dentro de este proyecto de documentación. Estas rutas se registran en el archivo de manifiesto de ejemplo, leído por Qt Creator.

Para asegurar que las rutas son correctas, examplesinstallpath debe coincidir con uno de los directorios listados en exampledirs. La ruta que se pasa como argumento para cada comando \example es relativa a la ruta de exampledirs.

Por ejemplo:

exampledirs = ./snippets \
              ../../../examples/mymodule

examplesinstallpath = mymodule

Y dado el siguiente comando \example:

/*!
    \example basic/hello
    ...
*/

A continuación, la ruta mymodule/basic/hello se registra en el archivo de manifiesto para este ejemplo.

Véase también: exampledirs, \exampley \meta.

ejemplos.extensionesarchivo

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 comodín estándar. Puede añadir una extensión de archivo al filtro utilizando '+='. Por ejemplo:

examples.fileextensions += *.qrc

Véase también headers.fileextensions.

examples.warnaboutmissingimages

Durante el procesamiento de la documentación de ejemplo, QDoc puede emitir advertencias si un ejemplo no contiene imágenes. Esta advertencia puede desactivarse estableciendo 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.warnaboutprojectfiles.

examples.warnaboutmissingprojectfiles

Durante el procesamiento de la documentación de ejemplo, QDoc puede emitir advertencias si un ejemplo no contiene un archivo de proyecto. Esta advertencia puede desactivarse estableciendo 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 es para listar directorios que no deben ser procesados por QDoc, incluso si los mismos directorios son incluidos por las variables sourcedirs o headerdirs.

Por ejemplo:

sourcedirs =  src/corelib
excludedirs = src/corelib/tmp

Cuando se ejecuta, QDoc excluirá los directorios de la lista. Los archivos de estos directorios no serán leídos por QDoc.

Véase también archivos excluidos.

archivos de exclusión

La variable excludefiles permite especificar archivos individuales que no deben ser procesados por QDoc.

excludefiles += $QT_CORE_SOURCES/../../src/widgets/kernel/qwidget.h \
                $QT_CORE_SOURCES/../../src/widgets/kernel/qwidget.cpp

Si incluye lo anterior en su archivo qdocconf para qtbase, no se generará documentación de clases para QWidget.

Desde Qt 5.6, también los comodines simples ('*' y '?') son reconocidos por excludefiles. Por ejemplo, para excluir todos los archivos de cabecera privados de Qt de ser analizados, defina lo siguiente:

excludefiles += "*_p.h"

Véase también excludedirs.

extraimages

La variable extraimages indica a QDoc que incorpore determinadas imágenes en la documentación generada.

QDoc copia automáticamente un archivo de imagen de imagedirs al directorio de salida si está referenciado por la variable \image o \inlineimage . Si desea copiar imágenes adicionales, debe especificarlas mediante la variable extraimages.

La sintaxis general es format.extraimages = image.

Ejemplo:

HTML.extraimages = images/qt-logo.png

Véase también imágenes e imagedirs.

falsedades

La variable falsehoods define el valor de verdad de los símbolos de preprocesador especificados como falso.

Los valores de la variable son expresiones regulares (véase QRegularExpression para más detalles). Si no se establece esta variable para un símbolo de preprocesador, QDoc asume que su valor de verdad es verdadero. La excepción es '0', que siempre es falso.

QDoc reconoce y puede evaluar la siguiente sintaxis de preprocesador:

#ifdef NOTYET
 ...
#endif

#if defined (NOTYET)
 ...
#end if

Sin embargo, ante una sintaxis desconocida como

#if NOTYET
    ...
#endif

QDoc lo evaluará como verdadero por defecto, a menos que el símbolo del preprocesador se especifique dentro de la entrada de variable falsehoods:

falsehoods = NOTYET

Véase también defines.

generateindex

La variable generateindex contiene un valor booleano que especifica si se debe generar un archivo de índice cuando se genera la documentación HTML.

Por defecto, siempre se genera un archivo de índice con la documentación HTML, por lo que esta variable sólo suele utilizarse cuando se desactiva esta función (estableciendo el valor en false) o cuando se activa 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/uilib

Cuando se ejecuta, lo primero que hace QDoc es leer las cabeceras especificadas en la variable headers y las ubicadas en los directorios especificados en la variable headerdir (incluyendo todos los subdirectorios), construyendo una estructura interna de las clases y sus funciones.

A continuación, leerá las fuentes especificadas en la variable sourcesy los ubicados en los directorios especificados en la variable sourcedirs (incluyendo todos los subdirectorios), fusionando la documentación con la estructura que recuperó de los archivos de cabecera.

Si las variables headers y headerdirs están definidas, QDoc leerá ambas, primero headers luego headerdirs.

En los directorios especificados, QDoc sólo leerá los archivos con el fileextensions especificado en la variable 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.

cabeceras

La variable headers permite especificar archivos de cabecera individuales además de los ubicados en los directorios especificados por la variable headerdirs la variable.

headers = $QTDIR/src/gui/widgets/qlineedit.h \
          $QTDIR/src/gui/widgets/qpushbutton.h

Al procesar la variable headers, QDoc se comporta de la misma manera que al procesar la variable headerdirs se comporta de la misma manera. Para más información, véase la variable headerdirs variable.

Véase también headerdirs.

headers.extensionesarchivo

La variable headers.fileextensions especifica la extensión utilizada por las cabeceras.

Al procesar los archivos de cabecera especificados en la variable headerdirs QDoc sólo leerá los archivos con las extensiones especificadas en la variable headers.fileextensions. De este modo, QDoc evita perder tiempo leyendo ficheros irrelevantes.

Las extensiones por defecto son *.ch, *.h, *.h++, *.hh, *.hpp, y *.hxx.

Las extensiones se dan como expresiones comodín estándar. Puede añadir una extensión de archivo al filtro utilizando '+='. Por ejemplo:

header.fileextensions += *.H

Véase también headerdirs.

includepaths

La variable includepaths se utiliza para pasar rutas de inclusión adicionales al analizador Clang que QDoc utiliza para analizar el código C++ para los comentarios de la documentación.

La variable acepta una lista de rutas, prefijadas con -I (ruta de inclusión), -F (ruta de inclusión del framework macOS) o -isystem (ruta de inclusión del sistema). Si se omite un prefijo, se utiliza -I por defecto.

Las rutas relativas al archivo .qdocconf actual se convierten en rutas absolutas. Las rutas que no existen en el sistema de archivos se ignoran.

Véase también moduleheader.

includeprivate

Utilice includeprivate para incluir miembros privados de clases C++ en su documentación. QDoc normalmente excluye las funciones, tipos y variables privadas de la documentación generada.

Para incluir todos los miembros privados, establezca includeprivate en true:

includeprivate = true

Tambié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 = true

La configuración específica anula la configuración global. Por ejemplo:

includeprivate = true
includeprivate.types = false

Esta configuración incluye funciones y variables privadas pero excluye los tipos privados.

QDoc introdujo includeprivate en Qt 6.11.

internalfilepatterns

La variable internalfilepatterns especifica patrones de ruta de archivos que identifican archivos de implementación interna. Las clases declaradas en archivos que coinciden con estos patrones se marcan automáticamente como Internas, junto con todos sus miembros (propiedades, funciones, enums, tipos anidados). Las funciones libres, los enums y los typedefs en el ámbito del fichero no se ven afectados por esta configuración.

Cuando showinternal es false (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 mantienen su estado Internal, permitiendo a los generadores darles un estilo diferente (como añadir indicadores visuales para APIs internas).

Esto es útil para las cabeceras de implementación privadas que contienen clases que no forman parte de la interfaz pública documentada. En Qt, esto incluye las cabeceras privadas que terminan en _p.h.

Sintaxis de patrones

Los patrones admiten dos sintaxis:

• Patrones glob tipo shell: Comodines simples en los que * coincide con cualquier carácter y ? coincide exactamente con un carácter. Los patrones glob se comparan sólo con el nombre del archivo, no con la ruta completa, lo que los hace ideales para patrones como *_p.h.
• Expresiones regulares: Para las coincidencias basadas en rutas, utilice la sintaxis regex. Cualquier patrón que contenga metacaracteres regex (^$[]{}()|+\\.) se trata como una expresión regular y se compara con la ruta de archivo completa normalizada.

Los patrones se comparan con barras inclinadas (/) como separadores de directorio. QDoc normaliza internamente los separadores de ruta, por lo que siempre se debe utilizar / en los patrones, independientemente de la plataforma.

Cuando una clase se marca como Interna debido a su ubicación de archivo, el estado Interno se propaga automáticamente a todos sus miembros a través de la jerarquía de nodos.

Ejemplo - Convención Qt (glob):

internalfilepatterns = *_p.h

Coincide con cualquier archivo que termine en _p.h en cualquier profundidad de directorio.

Ejemplo - Múltiples patrones de nombre de archivo (glob):

internalfilepatterns = *_p.h *_impl.h *_pch.h

Coincide con archivos que terminen en _p.h, _impl.h, o _pch.h.

Ejemplo - Coincidencia basada en directorios (regex):

internalfilepatterns = .*/internal/.*\.h

Coincide con cualquier archivo .h en cualquier directorio internal a cualquier profundidad.

Ejemplo - Patrones múltiples:

internalfilepatterns = *_p.h .*/private/.*\.h

Combina patrones glob para casos sencillos con regex para rutas complejas.

QDoc introdujo 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 objetivos de hipervínculo.

QDoc dispone de una función de autoenlace, en la que se intenta enlazar palabras que se parecen a entidades C++ o QML. Específicamente, una cadena califica para auto-enlace si tiene al menos tres caracteres de longitud, no tiene espacios en blanco, y es

• es una palabra camelCase, es decir, contiene al menos un carácter en mayúscula en un índice mayor que cero, o
• contiene la subcadena () o ::, o
• contiene al menos un carácter especial, @ o _.

Si se añade una palabra cualificada a ignorewords, QDoc deja de enlazarla automáticamente. Por ejemplo, si la palabra OpenGL es un objetivo de enlace válido (una sección, \pageo \externalpage título), puede evitarse un hiperenlace para cada aparición con

ignorewords += OpenGL

El enlace explícito con \l sigue funcionando para las palabras ignoradas.

La variable ignorewords se introdujo en QDoc 5.14.

ignoraporque

La variable ignoresince se utiliza para establecer un valor de corte para las versiones pasadas al comando \since comando. Todos los comandos \since que definan una versión inferior a la de corte se ignoran y no generan salida.

Los valores de corte son específicos de cada proyecto. El nombre del proyecto puede definirse como una subvariable. El nombre de proyecto por defecto es Qt. Por ejemplo:

ignoresince      = 5.0
ignoresince.QDoc = 5.0

Se ignorarán los comandos \since cuando la versión principal sea 4 o inferior y el proyecto sea QDoc o indefinido.

\since 3.2          # Ignored
\since 5.2          # Documented (as 'Qt 5.2')
\since QDoc 4.6     # Ignored
\since QtQuick 2.5  # Documented

La 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 variables images y imagedirs son utilizadas por las variables \image y \inlineimage . Si se definen las variables images y imagedirs, QDoc buscará en ambas. Primero en imagesy después en imagedirs.

QDoc buscará en los directorios en el orden especificado y aceptará el primer archivo coincidente que encuentre. Sólo buscará en los directorios especificados, no en los subdirectorios.

imagedirs = $QTDIR/doc/src/images \
            $QTDIR/examples

images    = $QTDIR/doc/src/images/calculator-example.png

Al procesar

\image calculator-example.png

QDoc comprobará si existe un archivo llamado calculadora-ejemplo.png listado como valor en la variable images. Si no lo hay, buscará en la variable imagedirs:

$QTDIR/doc/src/images/calculator-example.png

Si el archivo no existe, QDoc buscará un archivo llamado

$QTDIR/examples/calculator-example.png

imagesoutputdir

La variable imagesoutputdir controla el nombre del subdirectorio, bajo el directorio de salida, que QDoc utiliza para almacenar las imágenes.

El valor por defecto para 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 es útil para compilaciones de documentación multimódulo en las que varios proyectos de documentación están configurados para utilizar 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 archivos de imagen con nombres idénticos se sobrescriban entre sí.

Esta variable se introdujo en QDoc con Qt 6.11.

lenguaje

La variable language especifica el idioma del código fuente que se utiliza en la documentación. Específicamente, define el lenguaje por defecto para analizar el código fuente dentro de los bloques \code.. \endcode.

language = Cpp

El lenguaje 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, establezca QML como predeterminado:

language = QML

Véase también \code.

locationinfo

La variable booleana locationinfo determina si se escribe información detallada sobre la ubicación de cada entidad en .index-files y .webxml-files (cuando se utiliza el formato de salida WebXML).

La información de localización consiste en la ruta completa y el número de línea del bloque de declaración o de comentario de la documentación en el código fuente.

Si se establece en false, se desactiva la información de ubicación:

locationinfo = false

El valor por defecto es true.

La variable locationinfo se introdujo en QDoc 5.15.

advertencias de registro

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 escriben en stderr como de costumbre.

El archivo de registro incluye una cabecera con información sobre el proyecto y, por defecto, los argumentos de línea de comandos utilizados para invocar QDoc con fines de reproducibilidad.

Si se establece en true, se activa el registro de advertencias:

logwarnings = true

El valor por defecto es false.

Esta característica es útil para grandes conjuntos de documentación o entornos CI donde las advertencias pueden ser numerosas y pasar demasiado rápido para ser analizadas sistemáticamente.

La variable logwarnings se introdujo en QDoc 6.11.

logwarnings.disablecliargs

La subvariable booleana logwarnings.disablecliargs controla si los argumentos CLI se omiten en las cabeceras de los archivos de registro de advertencias.

logwarnings.disablecliargs = true

Cuando se establece en true, los argumentos de la línea de comandos se omiten de la cabecera del archivo de registro, haciendo que los archivos de registro sean portables a través de diferentes entornos. Esto es útil para suites de pruebas y sistemas CI donde los argumentos de 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 sus propios comandos QDoc simples. La sintaxis es macro.command = definition. el comando se limita a una combinación de caracteres de letras y números, pero no caracteres especiales como guiones o guiones bajos. la definición se escribe utilizando la sintaxis de QDoc.

Una variable de macro puede restringirse para su uso en un tipo de generación de salida. Por ejemplo, añadiendo .HTML al nombre de la macro, ésta sólo se utilizará cuando se genere una salida HTML.

macro.key              = "\\b"
macro.raisedaster.HTML = "<sup>*</sup>"

La primera macro define el comando \key para mostrar su argumento utilizando una fuente en negrita. La segunda macro define el comando \raisedaster para mostrar un asterisco en superíndice, pero sólo cuando se genera HTML.

Una macro puede tener hasta siete parámetros:

macro.hello            = "Hello \1!"

Los parámetros se pasan a las macros del mismo modo que a otros comandos:

\hello World

Cuando utilice más de un parámetro, o cuando un argumento contenga espacios en blanco, encierre cada argumento entre llaves:

macro.verinfo          = "\1 (version \2)"

\verinfo {QFooBar} {1.0 beta}

Se puede añadir una opción de macro especial, match, para obtener un patrón de expresión regular adicional para 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 basada en la variable de entorno QT_VER.

Una macro que define un patrón de coincidencia muestra todos los grupos de captura (paréntesis) concatenados, o la cadena exacta coincidente si el patrón no contiene ningún grupo de captura.

Para más información sobre macros predefinidas, véase Macros.

manifestmeta

La variable manifestmeta especifica metacontenido adicional para los archivos de manifiesto de ejemplo generados por QDoc.

Consulte la sección Metacontenido del manifiesto para obtener más información.

cabecera del módulo

La variable moduleheader define el nombre de la cabecera del módulo de un módulo C++ documentado.

Los proyectos que documentan APIs C++ requieren una cabecera a nivel de módulo que incluya todas las clases públicas, espacios de nombres y archivos de cabecera del módulo. El analizador Clang en QDoc utiliza este archivo para construir una cabecera precompilada (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 de la cabecera del módulo.

project = QtCore

Con el nombre de proyecto anterior, QDoc busca una cabecera de módulo QtCore en todas las rutas de inclusión conocidas; primero usando las rutas pasadas como argumentos de la línea de comandos, luego las rutas listadas en la variable includepaths.

QDoc emitirá una advertencia si no se encuentra la cabecera del módulo. Entonces intentará construir una cabecera de módulo artificial basada en las cabeceras listadas en la variable headerdirs.

Para los proyectos de documentación de Qt, el sistema de compilación normalmente proporciona a QDoc las rutas de inclusión correctas para localizar la cabecera del módulo, siempre que la variable project esté configurada correctamente. La variable moduleheader proporciona un nombre de archivo alternativo para que QDoc lo busque.

Si el proyecto no contiene documentación C++, QDoc debe ser instruido para omitir la generación de un PCH estableciendo moduleheader a una cadena vacía:

# No C++ code to document in this project
moduleheader =

Véase también includepaths y project.

lenguaje natural

La variable naturallanguage especifica el lenguaje natural utilizado para la documentación generada por QDoc.

naturallanguage = zh-Hans

Por defecto, el lenguaje natural es en por compatibilidad con la documentación heredada.

QDoc añadirá la información del lenguaje natural al 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 Práctica recomendada 13: Utilización de los códigos Hans y Hant.

navegación

Las subvariables navigation, si están definidas, establecen la página de inicio, la página de aterrizaje, la página de clases C++ y la página de tipos QML que son visibles en la barra de navegación generada para cada página.

En un proyecto con múltiples subproyectos (por ejemplo, módulos Qt), cada subproyecto suele definir su propia página de destino, mientras que la misma página de inicio se utiliza en todos los subproyectos.

Subvariables

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 produce la siguiente barra de navegación para Item tipo QML:

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 tabla de contenidos (TOC), enumere 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 enumeradas en una TOC.

QDoc espera un \list de enlaces en cada página de la 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
\endlist

Desde la versión 6.10 de QDoc, también puede aparecer \generatelist puede aparecer en la lista del índice:

\list
    \li \l {Home}
    \li \l {Getting started}
    \li What's new
    \generatelist [descending] whatsnew
\endlist

Aquí, el resultado es similar al del primer \list, suponiendo que las tres páginas `What's new` formen parte del mismo grupo whatsnew.

Véase también \ingroup.

overloadedsignalstarget

Predeterminado: connecting-overloaded-signals

La variable overloadedsignalstarget especifica el objetivo de enlace utilizado 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 la conexión a señales sobrecargadas. Por defecto, el enlace es connecting-overloaded-signals.

Los proyectos pueden personalizarlo para enlazar con 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-signals

El destino puede ser:

• Un nombre de destino simple (para usar con \target 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

Por defecto: connecting-overloaded-slots

La variable overloadedslotstarget especifica el objetivo de enlace utilizado en las notas generadas automáticamente para las ranuras sobrecargadas.

Cuando QDoc encuentra una ranura sobrecargada, genera una nota con un enlace a la documentación de ayuda sobre la conexión a ranuras sobrecargadas. Por defecto, el enlace es connecting-overloaded-slots.

Los proyectos pueden personalizarlo para enlazar con 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-slots

El destino puede ser:

• Un nombre de destino simple (para usar con \target 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 sobrecargar el objetivo de la señal.

outputdir

La variable outputdir especifica el directorio donde QDoc pondrá la documentación generada.

outputdir = $QTDIR/doc/html

ubica la documentación de referencia Qt generada en $QTDIR/doc/html. Por ejemplo, la documentación de la clase QWidget se encuentra en

$QTDIR/doc/html/qwidget.html

Las imágenes asociadas se pondrán en un subdirectorio images.

codificación de salida

La variable outputencoding especifica la codificación utilizada para la documentación generada por QDoc.

outputencoding = UTF-8

Por defecto, la codificación de salida es ISO-8859-1 (Latin1) por compatibilidad con la documentación heredada. Cuando se genera documentación para algunos idiomas, especialmente idiomas no europeos, esto no es suficiente y se requiere una codificación como UTF-8.

QDoc codificará HTML utilizando esta codificación y generará las declaraciones correctas para indicar a los navegadores qué codificación se está utilizando. También debe especificarse la variable de configuración naturallanguage para proporcionar a los navegadores un conjunto completo de información sobre codificación de caracteres e idioma.

Véase 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 soporta los formatos HTML y WebXML; desde Qt 5.15, también puede generar la documentación en DocBook. Si no se especifica outputformats, QDoc genera la documentación en HTML (el formato por defecto). Se pueden especificar todos los formatos de salida, con directorios de salida dedicados y otros ajustes. Por ejemplo:

outputformats = WebXML HTML
WebXML.nosubdirs = true
WebXML.outputsubdir = webxml
WebXML.quotinginformation = true

Esto genera documentación HTML usando la configuración por defecto, así como documentación WebXML en el subdirectorio de salida webxml.

outputprefixes

La variable outputprefixes especifica una correspondencia entre los tipos de archivos y los prefijos que se añadirá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 archivo 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-

De forma predeterminada, los archivos que contienen la documentación de la API para tipos QML llevan como prefijo qml-. En el ejemplo anterior, se utiliza el prefijo uicomponents- en su lugar.

Del mismo modo, las páginas de documentación de tipos C++ llevan el prefijo components- en el ejemplo anterior. Por defecto, las páginas de tipos C++ no tienen prefijo.

prefijos de salida

La variable outputsuffixes especifica un mapeo entre tipos de archivos y sufijos a aplicar al nombre del módulo o 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 archivo de las páginas de módulos, tipos QML, clases C++, espacios de nombres y páginas de referencia de archivos de cabecera.

Por defecto, no se utiliza ningún sufijo. El sufijo de salida QML, si está definido, se aplica como sufijo al nombre del módulo tal y como aparece en los nombres de archivo de las páginas de tipo QML y de módulo QML.

Los nombres de archivo de los tipos C++ no incluyen el nombre del módulo. El sufijo de salida CPP, si está definido, se aplica como sufijo del nombre del tipo.

outputsuffixes = QML CPP
{outputsuffixes.QML,outputsuffixes.CPP} = -tp

Con las definiciones anteriores, dado un nombre de módulo QML FooBar y el prefijo de salida por defecto (qml-), el nombre del archivo generado para un tipo QML FooWidget es qml-foobar-tp-foowidget.html.

Del mismo modo, para una clase C++ QFoobar, QDoc genera qfoobar-tp.html.

La variable outputsuffixes se introdujo en QDoc 5.6.

qhp

Las subvariables qhp se utilizan para definir la información que se escribirá en los archivos del proyecto Qt Help (qhp).

Consulte el capítulo Creación de archivos de proyecto de ayuda para obtener información sobre este proceso.

Desde QDoc 6.6, establecer la variable base qhp en true significa que se espera una configuración válida del proyecto de ayuda:

qhp = true

Entonces, si una configuración de proyecto no definió qhp.projects, QDoc emite una advertencia. Esto es útil para asegurar que todos los proyectos de documentación con un archivo .qdocconf de nivel superior compartido (como en Qt) están configurados correctamente.

Para desactivar la advertencia, establezca la variable en false.

sourcedirs

La variable sourcedirs especifica los directorios que contienen los archivos .cpp o .qdoc utilizados en la documentación.

sourcedirs  += .. \
               ../../../examples/gui/doc/src

Cuando se ejecuta, lo primero que hace QDoc es leer las cabeceras especificadas en la variable header y las ubicadas en los directorios especificados en la variable headerdir (incluyendo todos los subdirectorios), construyendo una estructura interna de las clases y sus funciones.

A continuación, leerá las fuentes especificadas en la variable sourcesy los ubicados en los directorios especificados en la variable sourcedirs (incluyendo todos los subdirectorios), fusionando la documentación con la estructura que recuperó de los archivos de cabecera.

Si se definen las variables sources y sourcedirs, QDoc leerá ambas, primero sources después sourcedirs.

En los directorios especificados, QDoc sólo leerá los archivos con el fileextensions especificado en la variable sources.fileextensions variable. Los archivos especificados por sources se leerán independientemente de su extensión.

Véase también sources y sources.fileextensions.

codificación de fuentes

La variable sourceencoding especifica la codificación utilizada para el código fuente y la documentación.

sourceencoding = UTF-8

Por defecto, la codificación fuente es ISO-8859-1 (Latin1) por 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á la codificación para leer los archivos fuente y de documentación, las limitaciones de los compiladores de C++ pueden impedirle utilizar caracteres no ASCII en los comentarios del código fuente. En casos como éste, es posible escribir la documentación de la API completamente 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 ubicados en los directorios especificados por la variable sourcedirs.

sources = $QTDIR/src/gui/widgets/qlineedit.cpp \
          $QTDIR/src/gui/widgets/qpushbutton.cpp

Al procesar la variable sources, QDoc se comporta del mismo modo que al procesar la variable sourcedirs. Para más información, véase la variable sourcedirs.

Véase también sourcedirs.

fuentes.extensionesarchivo

La variable sources.fileextensions filtra los archivos de un directorio fuente.

Al procesar los archivos fuente especificados en la variable sourcedirs QDoc sólo leerá los archivos con las extensiones de archivo especificadas en la variable sources.fileextensions. De este modo, QDoc evita perder tiempo leyendo archivos irrelevantes.

Las extensiones por defecto son *.c++, *.cc, *.cpp, *.cxx, *.mm, *.qml y *.qdoc.

Las extensiones se indican como expresiones comodín estándar. Puede añadir una extensión de archivo al filtro utilizando '+='. Por ejemplo:

sources.fileextensions += *.CC

Véase también fuentes y fuentes.

espurio

La variable spurious excluye de la salida las advertencias de QDoc especificadas. Las advertencias se especifican utilizando expresiones comodín estándar.

spurious = "Cannot find .*" \
"Missing .*"

asegura que las advertencias que coincidan con cualquiera de estas expresiones, no formarán parte de la salida al ejecutar QDoc. Por ejemplo, la siguiente advertencia se omitiría de la salida:

src/opengl/qgl_mac.cpp:156: Missing parameter name

syntaxhighlighting

La variable syntaxhighlighting especifica si QDoc debe realizar resaltado de sintaxis en el código fuente citado en la documentación que genera.

syntaxhighlighting = true

habilitará el resaltado de sintaxis para todos los lenguajes de programación soportados.

tabsize

La variable tabsize define el tamaño de un carácter de tabulación.

tabsize = 4

dará al carácter de tabulación el tamaño de 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 Doxygen que se escribirá cuando se genere HTML.

versión

La variable version especifica el número de versión del software documentado.

version = 5.6.0

Cuando se especifica un número de versión (mediante los botones version o versionsym en un archivo .qdocconf ), es accesible a través del comando \version correspondiente para su uso en la documentación.

Véase también versionsym.

versionsym

La variable versionsym especifica un símbolo del preprocesador C++ que define el número de versión del software documentado.

versionsym = QT_VERSION_STR

QT_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 el parámetro version o versionsym en un archivo .qdocconf ), es accesible a través del comando \version correspondiente para su uso en la documentación.

Véase también \version.

límite de advertencia

La variable warninglimit establece el número máximo de advertencias de documentación permitidas. Si se supera este límite, QDoc continúa normalmente pero sale con el número de advertencias como código de error. Si no se ha superado el límite o no se ha definido warninglimit, el proceso QDoc sale con 0, asumiendo que no ha habido otros errores críticos.

Si se define warninglimit como 0, se produce un fallo ante cualquier advertencia.

Por ejemplo,

# Fail the documentation build if we have more than 100 warnings
warninglimit = 100
warninglimit.enabled = true

La variable warninglimit se introdujo en Qt 5.11.