En esta página

Creación de enlaces

Estos comandos sirven para crear hipervínculos a clases, funciones, ejemplos y otros destinos.

El comando « \l » se utiliza para crear un hipervínculo a muchos tipos diferentes de destinos. La sintaxis general del comando es:

\l [ link criteria ] { link target } { link text }

...donde el « link criteria » entre corchetes es opcional, pero puede ser necesario cuando el « link target » es ambiguo. Véase «Corregir enlaces ambiguos» más abajo.

Puedes utilizar el comando « \l » para enlazar a:

  • una página externa:
    An URL with a custom link text:
    \l {https://doc.qt.io/qt-6/} {Qt 6 Documentation}.
    
    An URL without a custom link text: \l {https://doc.qt.io/qt-6/}.

    Se muestra como:

    Una URL con un texto de enlace personalizado: Documentación de Qt 6.

    Una URL sin texto de enlace personalizado: https://doc.qt.io/qt-6/.

    Véase también \externalpage.

  • una página de documentación. El destino del enlace puede ser:
    • el título de la página especificado con el \title comando:
      Here is a link with a custom link text:
      \l {Getting Started with QDoc}{QDoc - Getting Started}.
      
      Here is a link with a link text that is the same as the link
      target: \l {Getting Started with QDoc}.

      Se muestra como:

      Aquí hay un enlace con un texto de enlace personalizado: QDoc - Introducción.

      Aquí hay un enlace cuyo texto es el mismo que el destino del enlace: Primeros pasos con QDoc.

    • el nombre del archivo de la página especificado con el \page comando:
      \page 08-qdoc-commands-creatinglinks.html
      \title Creating Links
      
      These commands are for creating hyperlinks to classes, functions,
      examples, and other targets.
      
      ...
      
      The \l {08-qdoc-commands-creatinglinks.html} {Creating Links page}
      explains how to create links with QDoc.

      Se muestra como:

      El artículo de la página «Creación de enlaces » explica cómo crear enlaces con QDoc.

    • la página con un \keyword comando.
  • una sección de anclaje concreta dentro de un documento. El destino del enlace puede ser:
    • un título de sección especificado con uno de los comandos de sección:
      Here is a link to a QDoc Commands section of the Writing
      Documentation topic:
      \l {Writing Documentation#QDoc Commands}{QDoc Commands}.
      
      If you have unique section titles across your documentation
      project, you can use the section title as a target without
      the need to add the topic title:
      \l {QDoc Commands}.

      Se muestra como:

      Aquí hay un enlace a la sección «Comandos de QDoc» del tema «Redacción de documentación»: Comandos de QDoc.

      Si los títulos de las secciones de tu proyecto de documentación son únicos, puedes utilizar el título de la sección como destino sin necesidad de añadir el título del tema: Comandos de QDoc.

      Dado que el carácter « # » se utiliza para crear enlaces dentro de los documentos, no se puede utilizar tal cual al enlazar a títulos que lo contengan. En su lugar, debe escaparse utilizando una barra invertida:

      \l {Using Qt with C\\#}

      Se utilizan dos barras invertidas porque QDoc procesará el texto antes de que se envíe al comando de enlace.

    • un ancla definida con un \target comando:
      \target assertions
      
      Assertions make some statement about the text at the
      point where they occur in the regexp, but they do not
      match any characters.
      
      ...
      
      Regexps are built up from expressions, quantifiers, and
      \l {assertions} {assertions}.
  • un elemento de la API. Los enlaces de destino pueden ser:
    • \l QWidget - El nombre de una clase documentada con el \class o \qmltype .
    • \l QWidget::sizeHint() - La firma de una función sin parámetros. Si no se encuentra una función sin parámetros que coincida, el enlace se considera válido con la primera función coincidente que se encuentre.
    • \l QWidget::removeAction(QAction* action) - La firma de una función con parámetros. Si no se encuentra una coincidencia exacta, el enlace no se establece y QDoc muestra el error «No se puede enlazar a... ».
    • \l <QtGlobal> - El sujeto de un \headerfile comando.

    Si solo quieres que aparezca el nombre de la función en el enlace, puedes utilizar la siguiente sintaxis: \l{QWidget::}{sizeHint()}.

  • Un ejemplo. El enlace de destino es el título del ejemplo o una ruta relativa utilizada en un \example comando:
    /*!
        \example widgets/imageviewer
        \title ImageViewer Example
        \brief Shows how to combine QLabel and QScrollArea
        to display an image.
    
        ...
    */
    
    ...
    
    See the example: \l widgets/imageviewer

Si el destino del enlace es equivalente al texto del enlace, puedes omitir el segundo argumento.

Por ejemplo, si tienes documentación como esta:

/*!
    \target assertions

    Assertions make some statement about the text at the
    point where they occur in the regexp, but they do not
    match any characters.

    ...

    Regexps are built up from expressions, quantifiers, and
    \l {assertions} {assertions}.
*/

Puedes simplificarlo de la siguiente manera:

/*!
    \target assertions

    Assertions make some statement about the text at the
    point where they occur in the regexp, but they do not
    match any characters.

    ...

    Regexps are built up from expressions, quantifiers, and
    \l assertions.
*/

En la versión de un parámetro, a menudo se pueden omitir las llaves.

Enlaces automáticos

QDoc también intenta crear un enlace a partir de cualquier palabra que no se parezca a una palabra normal en inglés, por ejemplo, nombres de clases o funciones de Qt, como QWidget o QWidget::sizeHint(). En estos casos, el comando \l puede omitirse, pero al utilizarlo te aseguras de que QDoc emita una advertencia si no puede encontrar el destino del enlace.

Si la creación automática de enlaces genera un enlace no deseado para una palabra que coincide con un destino de enlace, puede suprimirlo mediante la variable de configuración ignorewords.

Un enlace ambiguo es aquel cuyo destino coincide con más de un módulo de Qt o conjunto de documentación. Por ejemplo, el mismo título de sección puede aparecer en más de un módulo de Qt, o el nombre de una clase de C++ en un módulo puede ser también el nombre de un tipo de QML en otro módulo. Un ejemplo real en Qt es el propio nombre «Qt»: es el nombre tanto de un espacio de nombres de C++ en QtCore como de un tipo de QML en QtQml.

Supongamos que queremos enlazar con Qt C++ namespace. En el momento en que QDoc generó esta página HTML, ese enlace era correcto. ¿Sigue dirigiendo al espacio de nombres de C++? QDoc generó ese enlace a partir de este comando de enlace:

  • \l {Qt} {Qt C++ namespace}

Ahora supongamos que queremos enlazar a Qt QML type. En el momento en que QDoc generó esta página HTML, ese enlace también era correcto, pero tuvimos que utilizar este comando de enlace:

  • \l [QML] {Qt} {Qt QML type}

El código QML entre corchetes indica a QDoc que acepte un destino coincidente solo si dicho destino se encuentra en una página QML. En realidad, QDoc encuentra primero el destino del espacio de nombres de C++, pero, dado que ese destino se encuentra en una página de C++, QDoc lo ignora y sigue buscando hasta que encuentra el mismo destino en una página QML.

Sin la indicación del comando\l en el argumento opcional entre corchetes, QDoc establece el enlace con el primer destino coincidente que encuentra. QDoc no puede advertir de que el enlace es ambiguo en estos casos, ya que no sabe que existe otro destino coincidente.

¿Qué argumentos pueden aparecer entre corchetes?

Un comando de enlace con un argumento entre corchetes tiene la siguiente sintaxis:

\l [QML|CPP|DOC|attached|QtModuleName] {link target} {link text}

El argumento entre corchetes solo está permitido en el comando « \l (link) ». El ejemplo anterior muestra cómo se utiliza « QML » como argumento entre corchetes para obligar a QDoc a buscar una etiqueta QML. En la mayoría de los casos, se tratará de un tipo QML, pero también puede ser una función miembro o una propiedad de QML. Además, algunos tipos QML contienen propiedades y propiedades adjuntas con el mismo nombre. Las propiedades adjuntas se pueden seleccionar con un argumento « attached ». Si se omite « attached », se establecerán enlaces a las propiedades normales en lugar de a las propiedades adjuntas con nombres duplicados.

En el ejemplo, QDoc no necesitó un argumento entre corchetes para encontrar la página del espacio de nombres de Qt C++, ya que ese era, de todos modos, el primer objetivo coincidente que QDoc encontró. Sin embargo, para obligar a QDoc a buscar un objetivo C++ cuando un objetivo QML coincidente se interpone, se puede utilizar CPP como argumento entre corchetes. Por ejemplo, el siguiente enlace obligará a QDoc a ignorar el tipo Qt Qml y a seguir buscando hasta que encuentre una coincidencia con el espacio de nombres de Qt C++.

  • \l [CPP] {Qt} {Qt C++ namespace}

Si el destino del enlace no es ni una entidad C++ ni una QML, se puede utilizar DOC como argumento entre corchetes para evitar que QDoc coincida con ninguna de ellas. En el momento de redactar este artículo, no había casos de enlaces ambiguos en los que fuera necesario utilizar DOC.

A menudo, el autor del documento sabe en qué módulo de Qt se encuentra el destino del enlace. Cuando se conoce el nombre del módulo, utilice dicho nombre como argumento entre corchetes. En el ejemplo anterior, si sabemos que el tipo QML denominado «Qt» se encuentra en el módulo « QtQml », podemos escribir el comando de enlace de la siguiente manera:

  • \l [QtQml] {Qt} {Qt QML type}

Cuando se utiliza un nombre de módulo como argumento entre corchetes, QDoc buscará el destino del enlace únicamente en ese módulo. Esto hace que la búsqueda de destinos de enlaces sea más eficiente.

Por último, los argumentos de nombre de módulo y tipo de entidad pueden combinarse, separados por un espacio, por lo que también se permite algo como esto:

  • \l [CPP QtQml] {Window} {C++ class Window}

En el momento de redactar este artículo, no se había dado ningún caso en el que fuera necesario combinar ambos.

Véase también \sa, \target, y \keyword.

\sa (véase también)

El comando « \sa » define una lista de enlaces que se mostrarán en una sección independiente titulada «Véase también» al final de la unidad de documentación.

El comando toma como argumento una lista de enlaces separados por comas. Si la línea termina con una coma, puedes continuar la lista en la línea siguiente. La sintaxis general es:

\sa {the first link}, {the second link},
    {the third link}, ...

QDoc intentará generar automáticamente enlaces «Véase también» que interconecten las distintas funciones de una propiedad. Por ejemplo, la función setVisible() obtendrá automáticamente un enlace a visible() y viceversa.

En general, QDoc generará enlaces «Véase también» que interconecten las funciones que acceden a la misma propiedad. Reconoce cuatro versiones sintácticas diferentes:

  • property()
  • setProperty()
  • isProperty()
  • hasProperty()

El comando « \sa » admite el mismo tipo de enlaces que el \l comando.

/*!
    Appends the actions \a actions to this widget's
    list of actions.

    \sa removeAction(), QMenu, addAction()
*/
void QWidget::addActions(QList<QAction *> actions)
{
    ...
}

Véase también \l, \target y \keyword.

\target

El comando « \target » designa un lugar de la documentación al que se puede enlazar mediante los comandos «\l » (enlace) y «\sa » (véase también).

El texto hasta el salto de línea se convierte en el nombre del destino. Asegúrate de que el nombre del destino vaya seguido de un salto de línea. No es necesario encerrar el nombre del destino entre llaves, pero puede ser necesario cuando se utilice en un comando de enlace. Véase más abajo.

/*!
    \target capturing parentheses
    \section1 Capturing Text

    Parentheses allow us to group elements together so that
    we can quantify and capture them.

    ...
*/

Los paréntesis que encierran el nombre del destino pueden enlazarse de la siguiente manera:

  • \l {capturing parentheses}

En el ejemplo anterior, el nombre del destino aparece entre corchetes porque contiene espacios.

Nota: El comando « \target » no admite macro la expansión en su argumento.

\target en un \table

Cuando utilices el comando « \target » en una tabla, asegúrate de que el comando « \target » vaya a continuación de un \li(celda de tabla), ya que algunos generadores solo admiten destinos en una celda concreta, no en una fila completa. Además, asegúrate de que esté en una línea separada o que sea el último contenido que aparezca en la línea en la que se encuentra. Esto se debe al funcionamiento del comando « \target », que toma como parámetro todo lo que hay hasta el siguiente salto de línea. En otras palabras, si tienes una tabla y necesitas incluir un « \target » en ella, asegúrate de que siga la siguiente estructura:

\table
    \row
        \li \target my-target
        My text goes here.
        \li This is my next table cell.
\endtable

Véase también \l, \sa y \keyword.

\keyword

El comando « \keyword » designa un lugar de la documentación al que se puede enlazar mediante los comandos «\l » (enlace) y «\sa » (véase también). Además, añade la palabra clave y la ubicación a los índices generados.

El comando ` \keyword ` es similar al \target , salvo que, al enlazar a una palabra clave, por defecto el enlace lleva a la parte superior del comentario QDoc (tema) en el que aparece \keyword.

Si deseas crear una palabra clave para una unidad « section » dentro de un tema, añade « \keyword » directamente encima del título de la sección:

\keyword debug
\section1 Debug command line option (--debug)
...

A diferencia de \target, las palabras clave se registran en los índices de los archivos de documentación generados sin conexión (.qch). Esto permite a los usuarios buscar la ubicación por palabra clave, por ejemplo, en la búsqueda por índice deQt Assistant, y hace que la palabra clave sea accesible en la ayuda contextual de Qt Creator.

Las palabras clave deben ser únicas en todos los documentos procesados durante la ejecución de QDoc. El comando utiliza el resto de la línea como argumento. Asegúrate de que la palabra clave vaya seguida de un salto de línea.

/*!
    \class QRegularExpression
    \reentrant
    \brief The QRegularExpression class provides pattern
           matching using regular expressions.
    \ingroup tools
    \ingroup misc
    \ingroup shared

    \keyword regular expression

    Regular expressions, or "regexps", provide a way to
    find patterns within text.

    ...
*/

Se puede crear un enlace a la ubicación marcada con la palabra clave mediante:

/*!
    When a string is surrounded by slashes, it is
    interpreted as a \l {regular expression}.
*/

Si el texto de la palabra clave contiene espacios, es obligatorio utilizar corchetes.

Nota: El comando « \keyword » no admite macro la expansión en su argumento.

Véase también «\l » (enlace), «\sa » (véase también) y \target.

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