Creación de enlaces

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

\l (enlace)

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

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

...donde los link criteria entre corchetes son opcionales pero pueden ser necesarios cuando el link target es ambiguo. Véase más abajo Corrección de enlaces ambiguos.

Puede utilizar el comando \l para enlazar con:

• una página externa:

  An URL with a custom link text:
  \l {http://doc.qt.io/qt-6/} {Qt 6 Documentation}.
  
  An URL without a custom link text: \l {http://doc.qt.io/qt-6/}.

  Se renderiza como:

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

  Una URL sin texto de enlace personalizado: http://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}.

    Renderiza como:

    Aquí hay un enlace con un texto de enlace personalizado: QDoc - Primeros pasos.

    Aquí hay un enlace con un texto de enlace que es el mismo que el destino del enlace: Introducción a QDoc.

  • el nombre del archivo de 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.

    Renderiza como:

    El artículo Crear 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 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 representa como:

    Aquí hay un enlace a una sección de Comandos QDoc del tema Escribiendo Documentación: Comandos QDoc.

    Si tiene títulos de sección únicos en todo su proyecto de documentación, puede utilizar el título de la sección como destino sin necesidad de añadir el título del tema: Comandos QDoc.

  • 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 API. Los enlaces de destino pueden ser:
  • \l QWidget - El nombre de una clase documentada con el comando \class o \qmltype .
  • \l QWidget::sizeHint() - La firma de una función sin parámetros. Si no se encuentra una función coincidente sin parámetros, el enlace se satisface con la primera función coincidente encontrada.
  • \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 satisface y QDoc informa de un error Can't link to... (No se puede enlazar con... ).
  • \l <QtGlobal> - El asunto de un comando \headerfile comando.
• 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 objetivo del enlace es equivalente al texto del enlace, puede omitir el segundo argumento.

Por ejemplo, si tiene documentación como:

/*!
    \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}.
*/

Puede 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.
*/

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

QDoc también intenta hacer un enlace de cualquier palabra que no se parezca a una palabra normal en inglés, por ejemplo, nombres de clases Qt o funciones, como QWidget o QWidget::sizeHint(). En estos casos, el comando \l puede ser omitido, pero al usarlo, te aseguras de que QDoc emita una advertencia si no puede encontrar el objetivo del enlace. Además, si sólo desea que aparezca el nombre de la función en el enlace, puede utilizar la siguiente sintaxis:

• \l {QWidget::} {sizeHint()}

Corrección de enlaces ambiguos

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

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

• \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 usar este comando link:

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

El QML entre corchetes le dice a QDoc que acepte un objetivo coincidente sólo si el objetivo está en una página QML. En realidad, Qdoc encuentra primero el objetivo del espacio de nombres C++, pero como ese objetivo está en una página C++, QDoc lo ignora y sigue buscando hasta que encuentra el mismo objetivo en una página QML.

Sin la orientación del comando\l en el argumento opcional de corchetes, QDoc enlaza con el primer objetivo coincidente que encuentra. En estos casos, QDoc no puede advertir de que el enlace es ambiguo porque no sabe si existe otro objetivo que coincida.

¿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 de corchetes sólo se permite en el comando \l (link). El ejemplo anterior muestra cómo se utiliza QML como argumento de corchetes para forzar a QDoc a que coincida con un objetivo QML. Lo más frecuente es que se trate de un tipo QML, pero también puede ser una función miembro o una propiedad QML. Además, algunos tipos QML contienen propiedades y propiedades adjuntas con el mismo nombre. Las propiedades adjuntas pueden seleccionarse con un argumento attached. Si se omite attached, las propiedades normales se enlazarán con preferencia a las propiedades adjuntas con nombres duplicados.

En el ejemplo, QDoc no necesitaba un argumento de corchetes para encontrar la página del espacio de nombres Qt C++, porque ese era el primer objetivo coincidente que QDoc encontraba de todos modos. Sin embargo, para forzar a QDoc a encontrar un objetivo C++ cuando un objetivo QML coincidente se interpone en el camino, se puede utilizar CPP como argumento de corchetes. Por ejemplo, el siguiente enlace forzará a QDoc a ignorar el tipo Qt Qml y continuar buscando hasta que coincida con el espacio de nombres Qt C++.

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

Si el objetivo del enlace no es ni una entidad C++ ni una QML, se puede utilizar DOC como argumento del corchete para evitar que QDoc coincida con ninguna de ellas. En el momento de escribir esto, no había casos de enlaces ambiguos en los que fuera necesario utilizar DOC.

A menudo, el documentador sabe en qué módulo de Qt se encuentra el objetivo del enlace. Si se conoce el nombre del módulo, utilícelo como argumento del corchete. En el ejemplo anterior, si sabemos que el tipo QML llamado 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 el nombre de un módulo como argumento del corchete, QDoc buscará el objetivo del enlace sólo en ese módulo. Esto hace que la búsqueda de objetivos de enlace sea más eficiente.

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

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

En el momento de escribir esto, no había casos en los que fuera necesario combinar ambos.

Véase también \sa, \targety \keyword.

\sa (véase también)

El comando \sa define una lista de enlaces que se mostrarán en una sección separada "Véase también" en la parte inferior de la unidad de documentación.

El comando toma como argumento una lista de enlaces separada por comas. Si la línea termina con una coma, puede 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 "Ver también" que interconecten las distintas funciones de una propiedad. Por ejemplo, una función setVisible() obtendrá automáticamente un enlace a visible() y viceversa.

En general, QDoc generará enlaces "See also" que interconectan las funciones que acceden a la misma propiedad. Reconoce cuatro versiones de sintaxis diferentes:

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

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

/*!
    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 nombra un lugar de la documentación al que se puede enlazar mediante los comandos \l (enlace) y \sa (ver también).

El texto hasta el salto de línea se convierte en el nombre de destino. Asegúrese de poner un salto de línea después del nombre del destino. Las llaves no son necesarias alrededor del nombre del destino, pero pueden ser necesarias cuando el nombre del destino se utiliza 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.

    ...
*/

El nombre de destino que captura los paréntesis se puede vincular de la siguiente manera:

• \l {capturing parentheses}

Arriba, el nombre de destino está entre paréntesis porque contiene espacios.

\target en un \table

Cuando utilice el comando \target en una tabla, asegúrese de que el comando \target sigue a un comando \li-(celda de tabla), ya que algunos generadores sólo admiten destinos a una celda individual, no a toda una fila. Además, asegúrate de que está en una línea separada, o es el último contenido que aparece en la línea en la que está. Esto se debe a cómo funciona el comando \target; consume cualquier cosa hasta el siguiente salto de línea como parámetro. En otras palabras, si tienes una tabla y necesitas un \target dentro de ella, asegúrate de que sigue 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 nombra un lugar de la documentación al que se puede enlazar mediante los comandos \l (enlace) y \sa (ver también). También añade la palabra clave y la ubicación a los índices generados.

El comando \keyword es como el comando \target con la diferencia de que, cuando se enlaza a una palabra clave, por defecto el enlace va al principio del comentario QDoc (tema) en el que aparece \keyword.

Si desea crear una palabra clave para una unidad section dentro de un tema, añada el \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 offline generados (.qch). Esto permite a los usuarios buscar la ubicación por palabra clave, por ejemplo, en Qt Assistant's Index Search, y hace que la palabra clave sea accesible en Qt Creator's context help.

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úrese de seguir la palabra clave con 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.

    ...
*/

La ubicación marcada con la palabra clave puede enlazarse con:

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

Si el texto de la palabra clave contiene espacios, los corchetes son obligatorios.

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