Solución de problemas de advertencias de QDoc

QDoc puede emitir advertencias al generar su conjunto de documentación. Esta sección describe qué significan estas advertencias y cómo resolverlas. Este documento no describe las advertencias generadas por Clang.

No se puede enlazar con <target>

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 objetivo ha cambiado de nombre (para una función o tipo) o de título (para otra sección).

Busca en el código fuente ese objetivo de enlace concreto. Si no obtiene resultados, vaya haciendo la búsqueda menos específica hasta que encuentre una coincidencia.

Si el objetivo del enlace se parece al nombre de un tipo o función, también puede deberse a:

• El nombre (o, en el caso de las funciones, cuando se especifique, la firma) utilizado donde se documenta no coincide con el nombre utilizado en su declaración.
• El destino del enlace se ha marcado como \internal cuando el texto de enlace no lo estaba.

Se ha encontrado un comando \target fuera del elemento de 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 \target dentro del \li para resolver esta advertencia.

No se encuentra el archivo de fragmentos que se va a citar

QDoc emite esta advertencia si no puede encontrar el archivo cuyo nombre aparece después de un comando \snippet o \quotefromfile .

Algunos pasos útiles para corregirlo:

• Compruebe si el nombre del archivo de fragmentos es correcto. QDoc añade el nombre del archivo de recortes a cada uno de los directorios indicados en la ruta de búsqueda, para obtener un nombre de ruta para un archivo candidato a buscar. Se produce este error cuando no existe ninguno de estos candidatos.
• Compruebe la ruta de búsqueda de fragmentos, dada por la variable de configuración exampledirs en el archivo *.qdocconf. Puede que necesite añadir una entrada a esta ruta, o corregir una entrada existente.
• Compruebe si el archivo de fragmentos existe, o si se ha movido, renombrado o eliminado, lo que puede ocurrir cuando hay cambios en el código fuente que QDoc intenta citar.

Inesperado \snippet

QDoc emite esta advertencia si no puede localizar el archivo de fragmentos citado en un comando \snippet comando.

QML <module> no documentado referido por <type> o sus miembros

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

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

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

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

El identificador de módulo QML, si está definido, debe coincidir con el argumento \inqmlmodule en 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.

Valor de retorno no documentado

Para las funciones cuyo tipo de retorno no es 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 empiece por "return".

Parámetro no documentado

QDoc exige que la documentación de una función o método describa cada parámetro. Lo reconoce porque cada nombre de parámetro (tal como se especifica cuando se declara la función o el método en un archivo de cabecera) aparece después de un comando \a comando.

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

No existe tal parámetro

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

Macro desconocida

QDoc emite esta advertencia cuando ve una barra invertida, \, seguida de un símbolo que no reconoce como el nombre de un comando integrado o de una macro definida por el usuario. Al citar código que contiene secuencias de escape de caracteres, debe encerrar el código en \c{...} para evitar esta advertencia contra las secuencias de escape.

Fallo al encontrar la función al analizar \fn <firma>

Cuando Clang analiza una firma de función siguiendo un comando \fn comprueba la declaración en el fichero de cabecera. Si Clang descubre discrepancias, emite este mensaje de advertencia.

La firma debe estar completamente cualificada. Los problemas típicos incluyen argumentos de plantilla faltantes o incorrectos, tipo de retorno, o calificadores como const.

No se genera salida para <entidad> porque <padre> no está documentado

QDoc emite esta advertencia cuando analiza un comentario de documentación para 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úrese de que el elemento principal 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 debe documentarse, marque la clase como \internal o utilice el comando \dontdocument comando.

Tipo QML <NombreTipo> documentado con <NombreClase> como su tipo nativo. Sustitución de <NombreClase> por <OtraClase>.

Si el comando \nativetype 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 solucionarlo, asegúrese de utilizar el comando \nativetype sólo una vez para cada clase C++.

No se puede vincular esta documentación a nada

QDoc ha encontrado un comentario /*! ... */, sin comando topic, que no iba seguido inmediatamente de una definición de clase, función o propiedad. Por lo tanto, no sabe qué documenta el comentario.

Este comentario qdoc no contiene ningún comando de tema (por ejemplo, \module, \page)

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

<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 proporciona en los detalles de la advertencia.

Por ejemplo, esta advertencia aparece cuando una función tiene un comentario de documentación antes de su definición y un comentario \fn en otro lugar.

<topic> no puede mezclarse con otros comandos de tema

QDoc permite varios comandos de tema en un único comentario de documentación para determinados casos de uso. El uso de múltiples comandos de tema de diferentes categorías imprime esta advertencia, y el tema no genera ninguna salida.

Espacio de nombres <nombre> documentado más de una vez

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

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

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

Esto puede resolverse documentando <namespace> o, si ya está documentado en otro módulo, asegurándose de que este módulo depende de él.

Véase también dependencias e índices.

No tiene comando \inmodule

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

Si el comentario QDoc describe una entidad que no es miembro de alguna otra entidad (normalmente un espacio de nombres o una clase), debe utilizar o bien \relates o \inmodule para asociarlo a su contexto más amplio. En caso contrario, aparece esta advertencia.

No se puede encontrar <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 fichero 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 un enum, pero QDoc no ha encontrado una definición de ese enum en ningún fichero de cabecera.

Esto también puede deberse a

• un error tipográfico en <nombre> o <comando>.
• una falta de espacio de nombres o prefijo de clase
• <nombre> se ha movido a otro espacio de nombres o clase

módulo/calificador de tipo QML irreconocible para <identificador>.

Un parámetro pasado a \qmlproperty o \qmlmethod contiene una combinación de qmlModule::qmlType::identificador 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.

Falta el tipo de propiedad para <nombre>

En la declaración de una propiedad \qmlproperty carece de 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 ::-joined después del nombre de la clase a la que pertenece).

Incorrecto:

\qmlproperty MyWidget::count

Correcto:

\qmlproperty int MyWidget::count

Propiedad no documentada '<nombre>'

Esta advertencia indica que una clase C++ tiene una declaración 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 propósito, valores válidos y comportamiento.

Propiedad QML documentada varias veces: <identificador>

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

Comando <command> no permitido con 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 <grupo>.<propiedad>. Cualquier otro comando de tema desencadena esta advertencia.

No se puede encontrar la función base para <método> en <clase>.

QDoc produce esta advertencia si se utiliza \reimp para documentar un método, como anulación de un método virtual, cuando ninguna clase base tiene un método virtual con el nombre y la firma dados. Esto puede ocurrir porque el método para el que se escribió ha cambiado su firma, o ya no es virtual.

Ilegal \reimp; no hay función virtual documentada para <command>.

Qdoc intenta crear un enlace a la función que ésta reimplementa, pero no ha podido encontrar el objetivo del enlace, probablemente porque esa función no está documentada. Esto también puede ocurrir si ninguna clase base tiene un método virtual con este nombre y firma, lo que puede deberse a un cambio de nombre, a un cambio en la firma o a que la base ya no lo declare virtual.

Múltiples definiciones de sobrecarga primaria para <función>

QDoc emite esta advertencia cuando varias funciones con el mismo nombre están marcadas con \overload primary. Sólo una función en un grupo de sobrecarga debe ser designada como la sobrecarga primaria.

La advertencia incluye las firmas de las funciones y sus ubicaciones de origen para ayudar a identificar todas las sobrecargas primarias en competencia. QDoc determinará la sobrecarga primaria real utilizando la comparación lexicográfica (ordenación alfabética de las firmas de función) entre las funciones marcadas como primarias.

Para resolver esta advertencia, elimine el argumento primary de todos los comandos \overload primary del grupo de sobrecargas menos uno.

Ejemplo que desencadena esta advertencia:

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

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

Enfoque correcto - sólo un primario:

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

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

<clase> intenta heredarse a sí misma

El comando \inherits se utiliza para documentar que un tipo QML hereda 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

\nativetype sólo se permite en \qmltype

El comando \nativetype sólo puede utilizarse en un comentario QDoc que documente un tipo QML.

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.

No se puede encontrar el archivo de proyecto para el ejemplo <nombre>.

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

No se puede abrir el archivo que se va a citar: <nombredearchivo>.

La ruta de búsqueda de <nombredearchivo> está definida por las siguientes variables del archivo .qdocconf: sources, sourcedirs, y exampledirs.

QDoc no ha podido encontrar un archivo nombrado en un comando (por ejemplo \quotefromfile, \snippet, \include) que le indica que recupere el contenido del archivo nombrado. Busca en cada directorio nombrado en la ruta de búsqueda. Si no hay ningún archivo con este nombre en ninguno de esos directorios, o el archivo se encuentra pero no se puede leer, QDoc emite esta advertencia. Compruebe que la combinación de ruta de búsqueda y <nombre de archivo> está correctamente escrita y que dispone de permisos de lectura para el archivo.

Falta el nombre de formato después de \raw

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

La macro no puede tener definiciones específicas de formato y de sintaxis qdoc

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

Ejemplo de configuración que desencadena esta advertencia:

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

Comando desconocido <nombre>

Cuando un comentario de QDoc utiliza una barra invertida seguida de un token que no es un comando incorporado de QDoc y que no se ha definido como macro de comando personalizada, QDoc produce esta advertencia. Comprueba la ortografía del nombre del comando, y comprueba si tu configuración de QDoc no incluye lo que lo hubiera definido, si se trata de un comando personalizado.

Esto también puede producirse debido a que se está citando código en el comentario de QDoc, por ejemplo el autor puede haberse referido al carácter de terminación de cadena C '\0' o a una de las otras secuencias de escape de cadena C como '\n' sin escapar la barra invertida. Escapa la barra invertida como \ para incluir una barra invertida literal en la documentación, o encierra el fragmento de código en \c{...}, que suprime la interpretación de barras invertidas como introducción de comandos QDoc.

Nombre de objetivo duplicado <objetivo>

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

No se puede encontrar el archivo de inclusión qdoc <nombredearchivo>.

QDoc no ha podido encontrar un archivo de inclusión nombrado en un comando. QDoc busca en cada directorio nombrado en la ruta de búsqueda. Si no hay ningún archivo con este nombre en ninguno de esos directorios, o el archivo encontrado en esa búsqueda no es legible, QDoc emite esta advertencia. Compruebe que la combinación de ruta de búsqueda y <nombre de archivo> está correctamente escrita y que tiene permisos de lectura para el archivo.

No se puede encontrar <tag> en <file>.

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

Fragmento qdoc vacío <tag> en <fichero>.

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

No se pueden anidar comandos <command>.

Esta advertencia se refiere a los comandos de formato: negrita, cursiva, índice, enlace, span, subíndice, superíndice, teletipo, uicontrol, subrayado. Un comando de formato no puede utilizarse 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

Aparece la advertencia de QDoc "No se puede utilizar '\table' en '\list'".

Falta <outer> antes de <inner>.

Algunos ejemplos:

• El comando \li sólo puede utilizarse dentro de un \list o dentro \row de un \table.
• Los comandos \row y \header sólo se pueden utilizar dentro de un comando \table.

Inesperado <comando_fin>

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

Falta una coma en \sa

Los títulos de un comando \sa comando deben estar separados entre sí por comas.

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. Es posible que algunas macros sólo tengan definiciones específicas de formato.

Ejemplo:

macro.pi.HTML = "π"    # 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, puede tener macros en los títulos de sección, pero deben tener definiciones por defecto.

Macro <macro> invocada con muy pocos argumentos (esperado <muchos>, obtenido <pocos>)

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

Paréntesis desequilibrados en <texto>

Señala un '(' sin su correspondiente ')', o viceversa.

No hay documentación para <nombre>

Ejemplo:

Warning "No documentation for QNativeInterface."

QDoc detecta la declaración del espacio de nombres QNativeInterface en un fichero de cabecera, pero no encuentra un comentario QDoc donde se haya documentado dicho espacio de nombres.

No existe tal elemento enum <nombre> en <clase>

Ejemplo:

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

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

Elemento de enumeración no documentado <enum> en <lista de enumeraciones>.

de <lista de enumeraciones> \value o \omitvalue no incluyen una para <enum>, que se nombra en la declaración de <enum list> en el fichero de cabecera.

No se pudo encontrar qhp.<proyecto>.subproyectos.<subproyecto>.indexTitle

QDoc no pudo encontrar un título para una página designada como página de índice para <subproyecto> en la configuración del proyecto de ayuda de Qt.

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 provoca esta advertencia.

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

\generatelist <grupo> está vacío

A continuación se muestra un breve resumen de todos los argumentos posibles para \generatelist:

• \generatelist annotatedexamples
• \generatelist annotatedattributions
• \generatelist classes <prefijo>
• \generatelist classesbymodule <nombre del módulo>
• \generatelist qmltypesbymodule <nombre del módulo>
• \generatelist functionindex
• \generatelist legale
• \generatelist resúmenes
• \generatelist atribuciones
• \generatelist relacionado

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

\generatelist <grupo> no existe tal grupo

Esta advertencia aparece si el argumento de \generatelist es un grupo inexistente.

Ejemplo:

\generatelist draganddrop

Esta sentencia genera una lista de clases o tipos QML en el grupo draganddrop. Las clases o tipos QML se añaden al grupo draganddrop mediante el comando \l {ingroup-command}{\ingroup} draganddrop en su campo \class o \qmltype comentario.

QDoc emite este mensaje de advertencia si ninguna entidad tiene esta sentencia \ingroup draganddrop.

Falta imagen: <archivo de imagen>

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

No se puede enlazar con <target>

Esto puede tener varias causas:

• El destino del enlace no se ha definido con un comando de tema de QDoc, por ejemplo {comando-título}{\title} <destino>.
• El <target> contiene un error tipográfico.
• El documento que contiene ese enlace no se ha compilado.
• El documento que contiene ese objetivo de 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 de ese módulo en la configuración o QDoc no ha podido localizar el archivo de índice de la dependencia.

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

QDoc emite esta advertencia si se documenta un tipo QML, pero se omite el comando \inqmlmodule pero omite el 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

\brief La sentencia 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. También debe ser breve.

QtDeclarative no está instalado; no puede analizar QML

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

Expresión regular no válida <regex>

Algunos comandos de QDoc utilizan expresiones regulares como parámetros. QDoc emite esta advertencia cuando el texto dado como parámetro no es una expresión regular válida, normalmente debido a que 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 comando \printuntil imprime hasta que encuentra una línea formada únicamente por 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.

Se han encontrado varios archivos de índice para la relación <archivo_de_índice>:<dependencia>.

Utilización de <ficheroíndice> como fichero índice para la relación <dependencia>.

Se han pasado varias rutas -indexdir a QDoc como opciones de línea de comandos y más de una contiene un archivo .index que coincide con una dependencia. QDoc selecciona automáticamente el más reciente.

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

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 pudo localizar activeqt.index en ninguno de los directorios de índice especificados. En este caso, los directorios de índice especificados se especifican en qmake.qdocconf.

Se especificaron módulos dependientes, pero no se establecieron directorios de índices.

QDoc esperaba ver uno o más argumentos -indexdir en la línea de comandos. Sin ellos, QDoc no puede localizar los archivos de índice de ninguna dependencia definida con la variable de configuración 'depends'.

Anulación de un documento anterior

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

Estilo de lista no reconocido <nombre>

\listpuede tomar 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 que no se reconoce, QDoc emite esta advertencia.

No se ha podido analizar el fragmento 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 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 allí también se comprueba el código. Si, por ejemplo, falta una llave en el código, QDoc emite una advertencia.

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

QDoc a menudo falla al analizar fragmentos QML incompletos; en estos casos, suele ser correcto sustituir los comandos \qml... \endqml por \code... \endcode para suprimir esta advertencia.

El comando <command> falló 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 comando \snippet ¡comando no encontró una segunda etiqueta "//! [2]" para marcar el final del fragmento. También podría significar que no encontró ninguna ocurrencia de esa etiqueta de fragmento en este archivo de fragmentos.

Otro ejemplo:

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

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

Error al abrir <fichero> para escritura

Esta advertencia significa claramente que no se puede abrir un archivo para escribir, probablemente debido a una ruta incorrecta, o permiso para escribir en un directorio determinado.

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

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

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

QDoc emite este aviso si un título determinado se utiliza en más de una página.

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.

Mientras QDoc continúa analizando el archivo, sólo se tiene en cuenta la parte del token que cabe en el búfer, lo que significa que la salida puede quedar deformada.

Para resolver esta advertencia, debe reducirse el tamaño del contenido relevante, ya sea dividiéndolo, si es posible, o eliminando algunas de sus partes.

Junto a la advertencia se indica, por ejemplo, el número máximo de caracteres de un token:

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

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

QDoc ha podido hacer coincidir la documentación de una función <nombre> con su declaración, pero no se ha generado ninguna salida porque la función está declarada en el espacio de nombres global.

Utilice el comando \relates para asociar la función con un tipo documentado, un espacio de nombres o un archivo de encabezado. La función aparece entonces como no miembro relacionado en la página de referencia asociada.

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

Se esperaba una configuración de ayuda de Qt válida pero no se proporcionó en el archivo .qdocconf del proyecto.

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

FICHERO ya generado para este proyecto

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

Puede configurar la variable de entorno QDOC_ALL_OVERWRITES_ARE_WARNINGS para que advierta incondicionalmente de todos estos eventos. Esto puede ser útil a la hora de localizar las definiciones infractoras.

Tipo de propiedad QML no válido

El tipo utilizado para declarar una propiedad QML no era un tipo de valor QML o un tipo de objeto QML válido, o era un tipo 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>.

El tipo es su propio tipo base: <tipo>

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

Herencia de tipo cíclica: <tipo>

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.

Este aviso indica dónde se ha detectado un ciclo en la jerarquía de herencia. Debe examinar el \inherits para el tipo y seguir el rastro de tipos base hasta encontrar uno que herede de un tipo que haya encontrado previamente. A continuación, debe romper el ciclo corrigiendo el comando incorrecto para uno de los tipos identificados. \inherits incorrecto para uno de los tipos identificados.

Enlace redundante a sí mismo en el comando \sa para <nombre>.

Una parte de la documentación contiene un enlace a sí misma en las referencias definidas en su comando \sa comando.

Este problema suele producirse cuando hay una colección de propiedades o métodos relacionados que hacen referencia unos a otros, y donde los comandos \sa se han copiado entre ellos, como en este ejemplo:

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

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

Otra posibilidad es que el enlace no sea lo suficientemente específico para que QDoc lo resuelva, como en este ejemplo:

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

En este caso, la intención puede haber sido hacer referencia a una sobrecarga que acepte un argumento double:

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

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

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

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" no válido:

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