En esta página

Solución de problemas con las advertencias de QDoc

QDoc puede mostrar advertencias al generar tu conjunto de documentación. En esta sección se explica qué significan estas advertencias y cómo resolverlas. Este documento no trata las advertencias generadas por Clang.

Todas las propiedades de un grupo deben pertenecer al mismo tipo: <nombre>

Al documentar grupos de propiedades QML, todas las propiedades enumeradas en el bloque de comentarios deben pertenecer al mismo tipo QML.

Ya se ha generado <archivo> para este proyecto

Al generar la documentación de un proyecto, QDoc lleva un registro de los nombres de los archivos que ha generado. QDoc emitirá una advertencia al abrir un archivo para escribir en él si sabe que ese archivo ya se ha generado anteriormente, en la ejecución actual. Esto puede ocurrir si un \page comando utiliza el mismo nombre que \group por ejemplo.

Puedes configurar la variable de entorno QDOC_ALL_OVERWRITES_ARE_WARNINGS para que avise incondicionalmente de todos estos eventos. Esto puede resultar útil a la hora de localizar las definiciones problemáticas.

\brief La instrucción no termina con un punto

El argumento del comando \brief es una frase que resume el tema documentado, por lo que debe terminar con un punto. Además, debe ser breve.

QDoc emite esta advertencia cuando una parte de la documentación (identificada en el mensaje de advertencia) intenta hacer referencia a otra, pero no especifica correctamente esa otra, el destino del enlace. Esto puede deberse a que la referencia está mal escrita o a que el destino ha cambiado de nombre (en el caso de una función o un tipo) o de título (en el caso de otra sección).

Esto puede deberse a diversas causas:

  • El destino del enlace no se ha definido con un comando de tema de QDoc, p. ej., {title-command}{\title} <target>.
  • El <destino> contiene un error tipográfico.
  • El documento que contiene ese destino del enlace no se ha compilado.
  • El documento que contiene ese destino del enlace se encuentra en un módulo que no está en la ruta de compilación.
  • El destino del enlace se encuentra en otro módulo y no se ha establecido una dependencia con dicho módulo en la configuración, o bien QDoc no ha podido localizar el archivo de índice de la dependencia.

Busca en el código fuente ese destino de enlace concreto. Si no obtienes resultados, haz la búsqueda cada vez menos específica hasta que encuentres una coincidencia.

Si el destino del enlace se parece al nombre de un tipo o una función, esto también podría deberse a:

  • Que el nombre (o, en el caso de las funciones, la firma, cuando se especifique) utilizado en la documentación no coincida con el nombre utilizado en su declaración.
  • Que el destino del enlace esté marcado como \internal mientras que el texto de enlace no lo estaba.

No se encuentra la función base para <método> en <clase>

QDoc genera esta advertencia si se utiliza « \reimp » para documentar un método, como una sobrescritura de un método virtual, cuando ninguna clase base tiene un método virtual con el nombre y la firma indicados. Esto puede ocurrir porque el método que se pretendía sobrescribir ha cambiado su firma o ya no es virtual.

No se encuentra <nombre> especificado con \<comando> en ningún archivo de cabecera

Esto significa que QDoc no puede encontrar una declaración de <nombre> en ningún archivo de cabecera, pero ha encontrado un comentario que afirma documentarlo.

Un ejemplo:

Cannot find 'Color::Red' specified with '\enum' in any header file.

Un comentario de documentación afirma describir una enumeración, pero QDoc no ha encontrado una definición de dicha enumeración en ningún archivo de cabecera.

Esto también puede deberse a:

  • un error tipográfico en <nombre> o <comando>
  • la falta de un prefijo de espacio de nombres o de clase
  • que <nombre> se haya trasladado a otro espacio de nombres o clase

No se encuentra el archivo de proyecto para el ejemplo <nombre>

En el directorio fuente del ejemplo, QDoc espera encontrar un archivo de proyecto llamado CMakeLists.txt, o un archivo con la extensión .pro, .qmlproject o .pyproject, en el que el nombre base coincida con el del directorio del ejemplo. Por ejemplo, examples/mymodule/helloworld/helloworld.pro.

No se encuentra el archivo de fragmentos del que extraer la cita

QDoc muestra esta advertencia si no puede encontrar el archivo cuyo nombre se deriva de un \snippet o \quotefromfile .

Algunos pasos útiles para solucionar este problema:

  • Comprueba si el nombre del archivo de fragmentos es correcto. QDoc añade el nombre del archivo de fragmentos a cada uno de los directorios indicados en la ruta de búsqueda, para obtener una ruta de acceso a un posible archivo que buscar. Genera este error cuando no existe ninguno de estos posibles archivos.
  • Comprueba la ruta de búsqueda de fragmentos, especificada por la variable de configuración « exampledirs » en el archivo « *.qdocconf ». Es posible que tengas que añadir una entrada a esta ruta o corregir una ya existente.
  • Comprueba si el archivo de fragmento existe, o si se ha movido, renombrado o eliminado, lo cual puede ocurrir cuando hay cambios en el código fuente del que QDoc intenta extraer fragmentos.

No se encuentra el archivo de inclusión de QDoc <nombre de archivo>

QDoc no ha podido encontrar un archivo de inclusión mencionado en un comando. QDoc busca en cada directorio incluido en la ruta de búsqueda. Si no hay ningún archivo con este nombre en ninguno de esos directorios, o si el archivo encontrado en la búsqueda no es legible, QDoc muestra esta advertencia. Comprueba que la combinación de la ruta de búsqueda y <nombre_archivo> esté escrita correctamente y que tengas permisos de lectura para el archivo.

Nota: < nombre_archivo> puede incluir un prefijo de nombre de directorio; el <nombre_archivo> completo se añade a cada directorio de la ruta de búsqueda.

No se encuentra <tag> en <file>

Esto significa que QDoc no puede encontrar el identificador <id> en el \include <archivo> o en {snippet-command}{\snippet} <archivo>.

No se puede localizar el archivo de índice para la dependencia <depend>

Ejemplo:

"QMake" Cannot locate index file for dependency "activeqt"

El proyecto de documentación QMake no ha podido localizar activeqt.index en ninguno de los directorios de índice especificados. En este caso, los directorios de índice especificados se indican en qmake.qdocconf.

No se pueden anidar comandos <command>

Esta advertencia se refiere a los comandos de formato: bold, italic, index, link, span, subscript, superscript, teletype, uicontrol y underline. No se puede utilizar un comando de formato dentro del texto al que se aplica. Un ejemplo de ello:

There is \b{no \b{super-}bold}.
\encode

\section1 Can't use <inner> in <outer>

This warning is issued for commands that cannot be nested.

Example:
\badcode
    \list
        \li \table
            \row \li Hello \li Hi
            \endtable
    \endlist

Da lugar a la advertencia de QDoc «No se puede utilizar '\table' en '\list'».

No se puede abrir el archivo del que se quiere citar: <nombre de archivo>

La ruta de búsqueda para <nombre de archivo> viene definida por las siguientes variables del archivo .qdocconf: sources, sourcedirs y exampledirs.

QDoc no ha podido encontrar un archivo mencionado en un comando (como \quotefromfile, \snippet, \include) que le indica que recupere el contenido del archivo mencionado. Busca en cada directorio incluido en la ruta de búsqueda. Si no hay ningún archivo con ese nombre en ninguno de esos directorios, o si se encuentra el archivo pero no es legible, QDoc muestra esta advertencia. Comprueba que la combinación de la ruta de búsqueda y <nombre de archivo> esté escrita correctamente, y que tengas permisos de lectura para el archivo.

Nota: < nombre_archivo> puede incluir un prefijo con el nombre de un directorio; el <nombre_archivo> completo se añade al final de cada directorio de la ruta de búsqueda.

No se puede vincular esta documentación a nada

QDoc ha encontrado un comentario /*! ... */ sin ningún comando de tema y no ha podido asociar la declaración o definición que sigue inmediatamente al comentario con una entidad documentada. Esto puede ocurrir si no hay ninguna declaración o definición tras el comentario, o si la entidad no es visible para QDoc, como cuando la declaración se encuentra tras una condición del preprocesador que QDoc no evalúa.

<class> intenta heredarse a sí misma

El \inherits comando se utiliza para documentar que un tipo QML hereda de otro tipo QML. Esta advertencia se emite si ese otro tipo QML es el mismo que el tipo QML documentado.

Ejemplo:

\qmltype Foo
\inherits Foo

El comando <command> ha fallado al final del archivo <filename>

Ejemplo:

Command "\snippet (//! [2]) failed at end of file qmlbars/qml/qmlbars/main.qml".

En este caso, la advertencia significa que el \snippet comando no ha encontrado una segunda etiqueta «//! [2]» que marque el final del fragmento. También podría significar que no ha encontrado ninguna aparición de esa etiqueta de fragmento en este archivo de fragmentos.

Otro ejemplo:

Command '\skipto' failed at end of file 'styling/CMakeLists.txt".

El \skipto + <patrón> desplaza el cursor a la siguiente línea que contenga ese patrón. Si \skipto no lo encuentra, QDoc muestra esta advertencia.

El comando <comando> no está permitido con los comandos de propiedades QML

Ejemplo:

\qmlproperty real QtQuick.Controls::RangeSlider::first.value
\qmlproperty real QtQuick.Controls::RangeSlider::first.position
\qmlproperty real QtQuick.Controls::RangeSlider::first.visualPosition
\qmlsignal void QtQuick.Controls::RangeSlider::first.moved()
\qmlsignal void QtQuick.Controls::RangeSlider::second.moved()

Mensaje de error:

Command '\\qmlsignal' not allowed with QML property commands

Esta advertencia es específica de la documentación de grupos de propiedades. QDoc permite varios comandos de tema qmlproperty o qmlattachedproperty en un único comentario de documentación para documentar un grupo de propiedades en el que el último elemento de la ruta sea <group>.<property>. Cualquier otro comando de tema activa esta advertencia.

No se ha podido resolver la instrucción de importación de QML para el tipo <nombre>

QDoc emite esta advertencia si se documenta un tipo QML, pero se omite el \inqmlmodule comando. Ejemplo:

Could not resolve QML import statement for type 'ItemSelectionModel'
\encode

Incorrect:
  \badcode
  \qmltype ItemSelectionModel
  \nativetype QItemSelectionModel
  \since 5.5
  \ingroup qtquick-models

Correcto:

\qmltype ItemSelectionModel
\nativetype QItemSelectionModel
\inqmlmodule QtQml.Models
\since 5.5
\ingroup qtquick-models

Herencia cíclica de tipos: <type>

La herencia cíclica o circular se produce cuando un tipo QML hereda de un tipo base que, a su vez, hereda del tipo original. Esto puede ocurrir entre dos tipos que se heredan mutuamente, o puede haber tipos intermedios entre ellos.

Esta advertencia indica dónde se ha detectado un ciclo en la jerarquía de herencia. Debes examinar el \inherits comando correspondiente al tipo y seguir la cadena de tipos base hasta encontrar uno que herede de un tipo con el que ya te hayas encontrado anteriormente. A continuación, debes romper el ciclo corrigiendo el \inherits de uno de los tipos identificados.

Se han especificado módulos dependientes, pero no se han configurado directorios de índice.

QDoc esperaba encontrar uno o más argumentos –indexdir en la línea de comandos. Sin ellos, QDoc no puede localizar los archivos de índice de ninguna de las dependencias definidas con la variable de configuración «depends».

La configuración de la documentación para <project> no define un proyecto de ayuda (qhp)

Se esperaba una configuración de Qt Help válida, pero no se ha proporcionado en el archivo .qdocconf del proyecto.

Véase también Creación de archivos de proyecto de ayuda y qhp.

Nombre de destino duplicado <target>

Esta advertencia se emite si se definen dos objetivos con el mismo parámetro, ya sea utilizando el \target o el \keyword . El nombre del objetivo proporcionado como parámetro a estos comandos debe ser único. La advertencia va seguida de «La aparición anterior se encuentra aquí: [ubicación]», donde «ubicación» contiene un nombre de archivo y un número de línea.

Fragmento qdoc vacío <tag> en <archivo>

Se ha encontrado el fragmento <tag> en el \snippet <archivo>, pero está vacío.

No se ha podido encontrar la función al analizar \fn <signature>

Cuando Clang analiza una firma de función tras un \fn comando, la compara con la declaración del archivo de cabecera. Si Clang detecta discrepancias, emite este mensaje de advertencia.

La firma debe estar completamente calificada. Entre los problemas habituales se incluyen la falta de argumentos de plantilla, el tipo de retorno o calificadores como const, o bien que estos sean incorrectos.

Nota: Un «amigo oculto» puede documentarse utilizando bien la sintaxis calificada por clase, bien la sintaxis de función libre no calificada con su tipo de retorno.

No se ha encontrado qhp.<proyecto>.subproyectos.<subproyecto>.indexTitle

QDoc no ha podido encontrar un título para una página designada como página de índice para <SUBPROJECT> en la configuración del proyecto de Qt Help.

Los títulos de índice de los subproyectos deben ser locales al proyecto de documentación actual. El uso de un título de página de otro proyecto, cargado como dependencia, también da lugar a esta advertencia.

Para obtener más información, consulta Creación de archivos de proyecto de ayuda.

No se ha podido abrir <archivo> para escribir

Esta advertencia indica claramente que no se puede abrir un archivo para escribir en él, probablemente debido a una ruta incorrecta o a la falta de permisos de escritura en un directorio concreto.

Se ha encontrado un comando « \target » fuera de un elemento de tabla en una tabla

Si QDoc encuentra un comando «\target » que no va precedido de un comando « \li » dentro de un bloque «\table... \endtable », emite esta advertencia. La advertencia va seguida del texto «Mueve el comando « \target » dentro del comando « \li » para resolver esta advertencia».

\generatelist <group> está vacío

A continuación se ofrece una breve descripción general de todos los argumentos posibles para \generatelist:

  • \generatelist ejemplos-anotados
  • \generatelist annotatedattributions
  • \generatelist clases <prefijo>
  • \generatelist clases por módulo <nombre del módulo>
  • \generatelist tipos QML por módulo <nombre del módulo>
  • \generatelist índice de funciones
  • \generatelist términos legales
  • \generatelist resúmenes
  • \generatelist atribuciones
  • \generatelist relacionado

QDoc muestra esta advertencia si se especifica « \generatelist <group> » y el grupo no contiene ningún elemento, o si se especifica « \generatelist <group> <pattern> » y ningún elemento del grupo coincide con el patrón.

\generatelist <grupo> no existe tal grupo

Esta advertencia se muestra si el argumento de \generatelist es un grupo que no existe.

Ejemplo:

\generatelist draganddrop

Esta instrucción genera una lista de clases o tipos QML del grupo «draganddrop». Las clases o los tipos QML se añaden al grupo «draganddrop» mediante el comando « \l {ingroup-command}{\ingroup} draganddrop » en su \class o \qmltype comentario.

QDoc muestra este mensaje de advertencia si ninguna entidad contiene esta instrucción « \ingroup draganddrop ».

No tiene el comando « \inmodule »

QDoc emite esta advertencia si los comentarios de QDoc no relacionan una clase, un espacio de nombres o un archivo de encabezado con un módulo mediante el \inmodule comando.

Si el comentario QDoc describe una entidad que no es miembro de otra entidad (normalmente un espacio de nombres o una clase), debe utilizar \relates o \inmodule para asociarla a su contexto más amplio. Si no lo hace, se muestra esta advertencia.

\reimp o no válido; no hay ninguna función virtual documentada para <comando>

QDoc intenta crear un enlace a la función que esta reimplementa, pero no ha podido encontrar el destino del enlace, probablemente porque dicha función no está documentada. Esto también puede ocurrir si ninguna clase base tiene un método virtual con este nombre y esta firma; lo cual podría deberse a un cambio de nombre, a una modificación de la firma o a que la clase base ya no lo declare como virtual.

Tipo de propiedad QML no válido

El tipo utilizado para declarar una propiedad QML no era un tipo de valor QML válido ni un tipo de objeto QML, o bien era un tipo de C++ o Qt.

Esta advertencia suele producirse cuando los desarrolladores hacen referencia al tipo Qt subyacente utilizado para implementar un tipo QML, como QStringList en lugar de list<string>.

Expresión regular no válida <regex>

Algunos comandos de QDoc aceptan expresiones regulares como parámetros. QDoc muestra esta advertencia cuando el texto proporcionado como parámetro no es una expresión regular válida, normalmente porque contiene caracteres con significados especiales en expresiones regulares que deberían haberse escapado.

Ejemplo:

notifications.qdoc:56: (qdoc) warning: Invalid regular expression '^})$'
\quotefromfile webenginewidgets/notifications/data/index.html
\skipuntil resetPermission

Expresión regular no válida:

\printuntil /^})$/

Expresión regular válida:

\printuntil /^\}\)$/

El \printuntil comando imprime hasta que encuentra una línea que consta únicamente de una llave derecha seguida de un paréntesis derecho. En este caso, la llave y el paréntesis deben escaparse porque tienen un significado especial en las expresiones regulares.

Una macro no puede tener definiciones tanto específicas del formato como de la sintaxis de qdoc

Una \macro que especifique un formato de salida no puede tener también una definición genérica.

Un ejemplo de configuración que provoca esta advertencia:

macro.gui = \b
macro.gui.HTML = "<b>\1</b>"

La macro <comando> no tiene una definición por defecto

QDoc está intentando expandir una macro y espera que dicha macro tenga una definición por defecto. Algunas macros solo pueden tener definiciones específicas de formato.

Ejemplo:

macro.pi.HTML = "&pi;"    # encodes the pi symbol for HTML output format

Sin embargo, hay casos en los que la expansión de macros requiere una macro independiente del formato. Por ejemplo, se pueden incluir macros en los títulos de sección, pero estas deben tener definiciones predeterminadas.

La macro <macro> se ha invocado con muy pocos argumentos (se esperaban <muchos>, se han recibido <pocos>)

La macro indicada necesita más parámetros de los que se le han proporcionado. Consulta la definición de la macro en la configuración para obtener más detalles.

Falta una coma en \sa

Los títulos que aparecen para un \sa deberían estar separados entre sí por comas.

Falta el nombre del formato después de \raw

El \raw comando y el \endraw delimitan un bloque de código sin procesar en lenguaje de marcado. El comando \raw debe ir seguido del nombre del formato.

Falta la imagen: <archivo de imagen>

La ruta de búsqueda de la imagen es incorrecta o el archivo de imagen no existe.

Falta <outer> antes de <inner>

Algunos ejemplos:

Falta el tipo de propiedad para <nombre>

Falta la declaración del tipo de propiedad de \qmlproperty carece de su tipo de propiedad.

El comando « \qmlproperty » espera que le siga el tipo de propiedad y, a continuación, el nombre completo de la propiedad (es decir, el nombre unido mediante «:-» al nombre de la clase a la que pertenece).

Incorrecto:

\qmlproperty MyWidget::count

Correcto:

\qmlproperty int MyWidget::count

Se han encontrado varios archivos de índice para la dependencia <indexfile>:<depend>

Se utiliza <archivo_índice> como archivo de índice para la dependencia <dependencia>

Se han pasado varias rutas de « -indexdir » a QDoc como opciones de línea de comandos, y más de una contenía un archivo « .index » que coincide con una dependencia. QDoc selecciona automáticamente el que tiene la fecha y hora más recientes.

Normalmente, esta advertencia indica que quedan artefactos de compilación de una compilación de documentación anterior.

Varias definiciones de sobrecarga principal para <función>

QDoc emite esta advertencia cuando varias funciones con el mismo nombre están marcadas con \overload primary. Solo una función de un grupo de sobrecargas debe designarse como la sobrecarga principal.

La advertencia incluye las firmas de las funciones y sus ubicaciones en el código fuente para ayudar a identificar todas las sobrecargas primarias que compiten entre sí. QDoc determinará la sobrecarga primaria real mediante una comparación lexicográfica (orden alfabético de las firmas de las funciones) entre las funciones marcadas como primarias.

Para resolver esta advertencia, elimina el argumento « primary » de todos los comandos « \overload primary » del grupo de sobrecargas, excepto uno.

Ejemplo que provoca esta advertencia:

/*!
    \overload primary
    Does something with no parameters.
*/
void doSomething();

/*!
    \overload primary
    Does something with a parameter.
*/
void doSomething(int value);

Enfoque correcto: una sola función principal:

/*!
    \overload primary
    Does something with no parameters.
*/
void doSomething();

/*!
    \overload doSomething()
    Does something with a parameter.
*/
void doSomething(int value);

<nombre> documentado más de una vez

QDoc emite esta advertencia cuando encuentra dos comentarios que documentan el mismo elemento. La ubicación del comentario visto anteriormente se indica en los detalles de la advertencia.

Por ejemplo, esta advertencia aparece cuando una función tiene un comentario de documentación que precede a su definición y un comentario \fn independiente en otra parte.

<nombre> está documentado, pero el espacio de nombres <espacio de nombres> no está documentado en ningún módulo

Se ha encontrado la documentación de <nombre>, pero <nombre> está declarado bajo un espacio de nombres que o bien no está documentado o bien QDoc no ha podido localizar su documentación.

Esto se puede resolver documentando <namespace> o, si ya está documentado en otro módulo, asegurándose de que este módulo tenga una dependencia de él.

Véase también «depends » e «indexes».

El espacio de nombres <name> está documentado más de una vez

Esta advertencia significa que un conjunto de documentación contiene dos comentarios con \namespace comandos con el mismo argumento, <nombre>.

\nativetype solo está permitido en \qmltype

El \nativetype comando solo se puede utilizar en un comentario QDoc que documente un tipo QML.

No hay documentación para <nombre>

Ejemplo:

Warning "No documentation for QNativeInterface."

QDoc detecta la declaración del espacio de nombres QNativeInterface en un archivo de cabecera, pero no encuentra ningún comentario QDoc en el que se haya documentado dicho espacio de nombres.

No se ha generado documentación para la función <name> en el ámbito global

QDoc ha podido asociar la documentación de la función <name> a su declaración, pero no se ha generado ningún resultado porque la función está declarada en el espacio de nombres global.

Utiliza el \relates para asociar la función a un tipo, un espacio de nombres o un archivo de cabecera documentados. La función aparecerá entonces como un elemento no miembro relacionado en la página de referencia asociada.

No se ha generado ninguna salida para <entidad> porque <padre> no está documentado

QDoc emite esta advertencia al analizar un comentario de documentación de una entidad de la API, como un miembro de clase, pero no puede generar ningún resultado porque el padre asociado (clase) no está documentado. Asegúrate de que el padre esté documentado y de que QDoc esté configurado para analizar el archivo fuente que contiene el comentario de documentación.

Si el miembro documentado pertenece a una clase que no está destinada a ser documentada, marca la clase como \internal o utiliza el \dontdocument .

No existe el elemento de enumeración <nombre> en <clase>

Ejemplo:

Cannot find 'QSGMaterialRhiShader::RenderState::DirtyState' specified
with \enum in any header file.

QDoc emite esta advertencia cuando encuentra una \value directiva en un \enum comentario que nombra un valor que no se encuentra en el archivo de cabecera que declaró el tipo enumerado documentado.

No existe ese parámetro

QDoc emite esta advertencia cuando el nombre del parámetro indicado tras un \a comando no coincide con ninguno de los parámetros indicados en la declaración, en el archivo de cabecera, de la función o método que se está documentando.

No existe tal <tipo> en el <módulo> de QML

QDoc emite esta advertencia si un \qmlproperty, \qmlmethodo \qmlsignal utiliza un identificador de módulo QML, pero el \qmltype no pertenece a ese módulo.

El identificador de módulo QML, si está definido, debe coincidir con el \inqmlmodule argumento de la documentación del tipo QML. En la mayoría de los casos, QDoc es capaz de localizar el tipo QML sin un identificador de módulo.

Sobrescribe una documentación anterior

QDoc emite esta advertencia cuando encuentra dos comentarios que parecen describir la misma entidad. La ubicación del comentario visto anteriormente se indica en los detalles de la advertencia.

Propiedad QML documentada varias veces: <identificador>

QDoc utiliza esta advertencia cuando encuentra dos comentarios de QDoc que documentan la misma propiedad QML, ya sea porque aparecen justo antes de su definición o porque se ha utilizado el \qmlproperty comando.

Tipo QML <TypeName> documentado con <ClassName> como su tipo nativo. Sustitución de <ClassName> por <OtherClass>

Si el \nativetype comando se utiliza con el mismo argumento en varios comentarios de documentación de tipos QML que pertenecen al mismo proyecto de documentación, QDoc emite esta advertencia. Para resolverlo, asegúrate de utilizar el comando \nativetype solo una vez por cada clase de C++.

QtDeclarative no está instalado; no se puede analizar QML

QDoc emite esta advertencia si se ha compilado sin soporte para el análisis de QML. Esto no debería ocurrir a menos que tengas una compilación personalizada de QDoc.

Un documento contiene un enlace a sí mismo en las referencias definidas en su \sa comando.

Este problema suele producirse cuando hay un conjunto de propiedades o métodos relacionados que se remiten entre sí, y en los que se han copiado los comandos « \sa » entre ellos, como en este ejemplo:

\fn void Items::append(const Item &)
...
\sa append(), count(), insert(), remove()

Es útil sustituir el enlace autorreferencial por uno que apunte a otra propiedad o método relacionado.

Por otra parte, es posible que el enlace no sea lo suficientemente específico como para que QDoc lo resuelva, como en este ejemplo:

\fn void MyPicture::setSize(int)
...
\sa setSize()

En este caso, es posible que la intención fuera hacer referencia a una sobrecarga que acepte un argumento « double »:

\fn void MyPicture::setSize(int)
...
\sa setSize(double)

El contenido es demasiado largo

QDoc utiliza un búfer de tamaño fijo al tokenizar los archivos fuente. Si algún token del archivo tiene más caracteres que el límite máximo, QDoc emite esta advertencia.

Aunque QDoc continúa analizando el archivo, solo se tiene en cuenta la parte del token que cabe en el búfer, lo que significa que la salida podría verse alterada.

Para resolver esta advertencia, hay que reducir el tamaño del contenido en cuestión, ya sea dividiéndolo, si es posible, o eliminando algunas de sus partes.

El número máximo de caracteres para un único token se muestra junto a la advertencia, por ejemplo:

file.qdoc:71154: (qdoc) warning: The content is too long.

[The maximum amount of characters for this content is 524288.
Consider splitting it or reducing its size.]

Nota: Dado que el contenido demasiado largo no se analiza en su totalidad, QDoc puede emitir advertencias que sean falsos positivos. Resuelve todas las advertencias de este tipo antes de corregir otras advertencias.

Este título de página existe en más de un archivo

El \title comando establece el título de una página.

\page activeqt-server.html
\title Building ActiveX servers in Qt

QDoc emite esta advertencia si un título concreto se utiliza en más de una página.

Este comentario de QDoc no contiene ningún comando de tema (p. ej., \module, \page)

Si un comentario de QDoc no contiene un comando de tema, QDoc no sabe qué documenta el comentario y muestra esta advertencia. Es muy similar a «No se puede vincular esta documentación a nada», pero específico para comentarios que no se encuentran en archivos C++ o QML.

<topic> no se puede mezclar con otros comandos de tema

QDoc permite utilizar varios comandos de tema en un mismo comentario de documentación para determinados casos de uso. El uso de varios comandos de tema de diferentes categorías genera esta advertencia, y el tema no produce ningún resultado.

El tipo es su propio tipo base: <type>

El tipo QML se ha definido incorrectamente como su propio tipo base, posiblemente utilizando el \inherits comando.

No se puede analizar el fragmento de QML: <code> en la línea <y>, columna <x>

Los comentarios de QDoc pueden contener código QML. Este código puede encontrarse en un fragmento de código o en los comentarios de QDoc delimitados por \qml y {endqml-command}{\endqml}.

Ejemplo:

Si hay un error de sintaxis en el código QML, QDoc emite la advertencia

Unable to parse QML snippet: Syntax error at line 97, column 42

Los fragmentos de código también pueden contener QML y, en ese caso, el código se comprueba. Si, por ejemplo, falta una llave en el código, QDoc muestra la advertencia

Unable to parse QML snippet: Expected token '{' at line 63, column 52

A menudo, QDoc no consigue analizar fragmentos de código QML incompletos; en estos casos, suele bastar con sustituir los comandos « \qml... \endqml » por « \code... \endcode » para suprimir esta advertencia.

Paréntesis desequilibrados en <text>

Indica un «('» sin el «)» correspondiente, o viceversa.

Elemento de enumeración no documentado <enum> en <enum list>

<lista de enumeraciones> \value o \omitvalue no incluían una entrada para <enum>, cuyo nombre aparece en la declaración de <lista de enumeración> en el archivo de cabecera.

Parámetro no documentado

QDoc requiere que la documentación de una función o método describa todos los parámetros. Lo reconoce cuando cada nombre de parámetro (tal y como se especifica en la declaración de la función o método en un archivo de cabecera) aparece tras el comando \a comando.

Este requisito no se aplica a la documentación de sobrecargas de funciones, siempre que la sobrecarga esté marcada con el comando \overload y exista una función con el mismo nombre que esté completamente documentada.

Propiedad sin documentar «<nombre>»

Esta advertencia indica que una clase de C++ tiene una declaración de tipo « Q_PROPERTY » que carece de documentación. Las propiedades forman parte de la API pública de una clase y requieren documentación mediante el comando « \property » para describir su finalidad, valores válidos y comportamiento.

Nota: Si aparecen juntas las advertencias «No se puede encontrar '<ClassName::propertyName>' especificada con '\property'» y «Propiedad no documentada '<ClassName::propertyName>'», significa que el comando \property existe, pero no puede encontrar la propiedad en el código. Las advertencias dobles indican una discrepancia en la documentación de la propiedad: el comando « \property » no encuentra su objetivo y el PropertyNode no tiene documentación asociada. Comprueba que el nombre completo coincida exactamente, incluyendo el espacio de nombres y el ámbito de la clase.

<módulo> QML no documentado al que hace referencia <tipo> o sus miembros

QDoc emite esta advertencia si no puede localizar un módulo QML basándose en el identificador pasado a la \inqmlmodule o \qmlproperty asociados a un tipo QML.

Esto significa que o bien falta la documentación del \qmlmodule , o bien se ha utilizado un identificador de módulo incorrecto en los comandos \qmlproperty, \qmlmethod o \qmlsignal.

Valor de retorno no documentado

En el caso de las funciones cuyo tipo de retorno no sea `void`, QDoc comprueba si el valor de retorno está documentado. Esta advertencia se emite si la documentación de una función o método no contiene una palabra que comience por «return».

<end_command> inesperado

Esta advertencia se emite si, por ejemplo, tienes un \endlist sin un \list. Se aplica a todos los comandos que aparecen en pares (p. ej., startFoo/endFoo).

Inesperado \snippet

QDoc emite esta advertencia si no puede localizar el archivo de fragmento de código citado en un \snippet comando.

Base <nombre> desconocida para el tipo QML <tipo>

No se ha encontrado el nombre del tipo declarado como tipo base para un tipo QML, o bien no se ha declarado con el \inherits comando.

Comando desconocido <nombre>

Cuando un comentario de QDoc utiliza una barra invertida seguida de un token que no es un comando integrado de QDoc y que no se ha definido como una macro de comando personalizada, QDoc genera esta advertencia. Comprueba la ortografía del nombre del comando y verifica si tu configuración de QDoc incluye lo que lo habría definido, en caso de que se trate de un comando personalizado.

Esto también puede deberse a que el código aparece entre comillas en el comentario de QDoc; por ejemplo, el autor puede haber hecho referencia al carácter de terminación de cadena de C '\0' o a alguna de las otras secuencias de escape de cadenas de C, como '\n', sin escapar la barra invertida. Utiliza el escape de la barra invertida como \ para incluir una barra invertida literal en la documentación, o bien encierra el fragmento de código entre \c{...}, lo que impide que las barras invertidas se interpreten como el inicio de comandos de QDoc.

Macro desconocida

QDoc emite esta advertencia cuando detecta una barra invertida, \, seguida de un token que no reconoce como el nombre de un comando integrado ni de una macro definida por el usuario. Al citar código que contenga secuencias de escape de caracteres, debes encerrar el código entre \c{...} para evitar esta advertencia relacionada con las secuencias de escape.

Calificador de módulo/tipo QML no reconocido para <identificador>

Se ha pasado un parámetro a \qmlproperty o \qmlmethod contiene una combinación de qmlModule::qmlType::identifier que no está definida en ninguna parte.

Ejemplo:

Unrecognizable QML module/type qualifier for real QtQuick::DragHandler::DragAxis::minimum

DragHandler no tiene una propiedad llamada DragAxis.

Estilo de lista no reconocido <name>

\listpuede admitir un argumento opcional: un único número o carácter que modifica el estilo de la lista. Consulte la documentación de {list-command}{\list} para obtener más detalles. Si utiliza un argumento no reconocido, QDoc muestra esta advertencia.

Lenguaje de marcado no reconocido

Esta advertencia se produce cuando se especifica un lenguaje de programación para un comando \code que QDoc no reconoce. Por ejemplo, a este bloque de código QML se le ha asignado el lenguaje «QL», que no es válido:

\code [QL]
Item {
    id: my_item
}
\endcode

Véase también «No se puede abrir el archivo del que se va a citar: <nombre de archivo>» y «No se encuentra el archivo de inclusión de qdoc <nombre de archivo>».

© 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.