Marcado de texto

Los comandos de formato de texto indican cómo debe presentarse el texto.

\a (marcador de parámetros)

El comando \a indica a QDoc que la siguiente palabra es un nombre de parámetro formal.

Se emite una advertencia cuando un parámetro formal no está documentado o está mal escrito, por lo que cuando documente una función debe mencionar cada parámetro formal por su nombre en la descripción de la función, precedida del comando \a. El nombre del parámetro aparece en cursiva.

El nombre del parámetro formal puede ir entre llaves, pero no es obligatorio.

\c (fuente del código)

El comando \c se utiliza para representar nombres de variables, nombres de clases definidas por el usuario y palabras clave de C++ (por ejemplo, int y for) en la fuente de código.

El comando representa su argumento utilizando una fuente monoespaciada. Si el texto a representar en la fuente de código contiene espacios, encierre todo el texto entre llaves:

\c {QLineEdit::QLineEdit(const QString &contents, QWidget *parent) : QWidget(parent)}

El comando \c acepta el carácter especial \ dentro de su argumento, que se representa como un carácter normal. Por lo tanto, si desea utilizar comandos anidados, debe utilizar el comando teletipo (\tt ) en su lugar.

Véase también \tt y \code.

\details (plegable)

Los comandos \details y \enddetails generan un elemento <details> colapsable con un <summary> para controlar el estado oculto/visible.

Al generar una salida HTML, utilice los comandos \details y \enddetails para generar un elemento HTML <details> plegable. El comando toma una cadena de resumen opcional encerrada entre llaves. Este argumento opcional especifica un encabezamiento visible para los detalles.

Por ejemplo, con la siguiente entrada:

/*!
    \details {QDoc details}
      \note You're looking at detailed information.
    \enddetails
*/

Si QDoc está generando HTML, traducirá estos comandos a:

<summary>QDoc details</summary><div class="admonition note"><p><b>Note: </b>You're looking at detailed information.</p></div>

QDoc renderiza esto como:

Para cualquier otro formato de salida, QDoc genera el contenido como un párrafo normal, ignorando la cadena de resumen. Este comando se introdujo en QDoc en Qt6.6.

\div

Los comandos \div y \enddiv delimitan un bloque grande o pequeño de texto (que puede incluir otros comandos de QDoc) al que deben aplicarse atributos especiales de formato.

Debe proporcionarse un argumento entre llaves, como en el comentario QDoc que se muestra a continuación. El argumento no se interpreta, sino que se utiliza como atributo(s) de la etiqueta que genera QDoc.

Por ejemplo, podemos querer mostrar una imagen en línea de forma que flote a la derecha del bloque de texto actual:

/*!
    \div {class="float-right"}
        \inlineimage qml-column.png
    \enddiv
*/

Si QDoc está generando HTML, traducirá estos comandos a:

<div class="float-right"><p><img src="images/qml-column.png" /></p></div>

Para HTML, el valor del atributo float-right entonces se referirá a una cláusula en el archivo style.css, que en este caso podría ser:

div.float-right
{
   float: right; margin-left: 2em
}

A continuación puede encontrar un ejemplo tomado del archivo index.qdoc utilizado para generar index.html para Qt 4.7:

\div {class="indexbox guide"}
    \div {class="heading"}
        Qt Developer Guide
\enddiv
    \div {class="indexboxcont indexboxbar"}
        \div {class="section indexIcon"} \emptyspan
        \enddiv
        \div {class="section"}
            Qt is a cross-platform application and UI
            framework. Using Qt, you can write web-enabled
            applications once and deploy them across desktop,
            mobile and embedded operating systems without
            rewriting the source code.
        \enddiv
        \div {class="section sectionlist"}
            \list
               \li \l{Getting Started}
               \li \l{Installation} {Installation}
               \li \l{how-to-learn-qt.html} {How to learn Qt}
               \li \l{tutorials.html} {Tutorials}
               \li \l{Qt Examples} {Examples}
               \li \l{qt4-7-intro.html} {What's new in Qt 4.7}
            \endlist
        \enddiv
    \enddiv
\enddiv

Cuando todos los valores de los atributos de clase se definen tal y como están en el archivo style.css que se utiliza para renderizar la documentación de Qt, el ejemplo anterior se renderiza como:

Ver también \span.

\span

El comando \span aplica un formato especial a un pequeño bloque de texto.

Deben proporcionarse dos argumentos, cada uno entre llaves, como se muestra en el comentario de QDoc a continuación. El primer argumento no se interpreta, sino que especifica los atributos de formato de la etiqueta emitida por QDoc. El segundo argumento es el texto que se mostrará con los atributos de formato especiales.

Por ejemplo, podemos querer que la primera palabra de cada elemento de una lista numérica aparezca en azul.

/*!
    Global variables with complex types:
\list 1
        \li \span {class="variableName"} {mutableComplex1} in globals.cpp at line 14
        \li \span {class="variableName"} {mutableComplex2} in globals.cpp at line 15
        \li \span {class="variableName"} {constComplex1} in globals.cpp at line 16
        \li \span {class="variableName"} {constComplex2} in globals.cpp at line 17
    \endlist
*/

La clase variableName se refiere a una cláusula en su style.css.

.variableName
{
    font-family: courier;
color: blue
}

Usando la cláusula variableName mostrada arriba, el ejemplo se renderiza como:

Variables globales con tipos complejos:

1. mutableComplex1 en globals.cpp en la línea 14
2. mutableComplex2 en globals.cpp en la línea 15
3. constComplex1 en globals.cpp en la línea 16
4. constComplex2 en globals.cpp en la línea 17

Véase también \div.

\tm (marca comercial)

El comando \tm indica que su argumento es una marca comercial. QDoc añade un símbolo de marca comercial `™` a la primera aparición del argumento al generar una página.

En la configuración del proyecto, la variable navigation.trademarkspage se utiliza para definir el título de una página que contiene documentación relacionada con marcas comerciales.

navigation.trademarkspage = Trademarks

Si se establece, cada aparición del símbolo de marca comercial también enlaza con la página de marcas comerciales.

Véase también \section1 y navigation.

\tt (fuente de teletipo)

El comando \tt muestra su argumento en una fuente monoespaciada. Este comando se comporta igual que el comando \c con la salvedad de que \tt permite anidar comandos QDoc dentro del argumento (por ejemplo \e, \b y \underline).

/*!
    After having populated the main container with
    child widgets, \c setupUi() scans the main container's list of
    slots for names with the form
    \tt{on_\e{objectName}_\e{signalName}().}
*/

Si el texto que se va a representar en la fuente de código contiene espacios, encierre todo el texto entre llaves.

\tt {QLineEdit::QLineEdit(const QString &contents, QWidget *parent) :QWidget(parent)}

Véase también \c.

\b

El comando \b muestra su argumento en negrita. Este comando solía llamarse \bold.

/*!
    This is regular text; \b {this text is
    rendered using the \\b command}.
*/

\br

El comando \br fuerza un salto de línea.

\e (énfasis, cursiva)

El comando \e muestra su argumento en un tipo de letra especial, normalmente cursiva. Este comando solía llamarse \i, que ahora está obsoleto.

Si el argumento contiene espacios u otros signos de puntuación, enciérrelo entre llaves.

/*!
    Here, we render \e {a few words} in italics.
*/

Si quieres usar otros comandos de QDoc dentro de un argumento que contiene espacios, siempre necesitas encerrar el argumento entre llaves. Pero QDoc es lo suficientemente inteligente como para contar paréntesis, por lo que no necesita llaves en casos como este:

/*!
    An argument can sometimes contain whitespaces,
    for example: \e QPushButton(tr("A Brand New Button"))
*/

Por último, la puntuación final no se incluye en un argumento, ni tampoco las "'s".

\sub

El comando \sub muestra su argumento por debajo de la línea de base del texto normal, utilizando una fuente más pequeña.

/*!
    Definition (Range): Consider the sequence
    {x\sub n}\sub {n > 1} . The set

    {x\sub 2, x\sub 3, x\sub 4, ...} = {x\sub n ; n = 2, 3, 4, ...}

    is called the range of the sequence.
*/

Si el argumento contiene espacios u otros signos de puntuación, enciérrelo entre llaves.

\sup

El comando \sup hace que su argumento aparezca por encima de la línea de base del texto normal, utilizando una fuente más pequeña.

/*!
    The series

    1 + a + a\sup 2 + a\sup 3 + a\sup 4 + ...

    is called the \i {geometric series}.
*/

Si el argumento contiene espacios u otros signos de puntuación, enciérrelo entre llaves.

\uicontrol

El comando \uicontrol se utiliza para marcar el contenido como utilizado para elementos de control de la interfaz de usuario. Cuando se utiliza HTML, la salida se muestra en negrita.

Véase también \b.

\underline

El comando \underline hace que su argumento aparezca subrayado.

/*!
    The \underline {F}ile menu gives the users the possibility
    to edit an existing file, or save a new or modified
    file, and exit the application.
*/

Si el argumento contiene espacios u otros signos de puntuación, enciérrelo entre llaves.

\\ (doble barra invertida)

La secuencia \ se expande a una sola barra invertida.

Los comandos de QDoc empiezan siempre con una barra invertida. Para mostrar una sola barra invertida en el texto, debe escribir dos barras invertidas. Si desea mostrar dos barras invertidas, debe escribir cuatro.

/*!
    The \\\\ command is useful if you want a
    backslash to appear verbatim, for example,
    writing C:\\windows\\home\\.
*/

Sin embargo, si desea que el texto aparezca también en una fuente monoespaciada, puede utilizar el comando \c que acepta y muestra la barra invertida como cualquier otro carácter. Por ejemplo:

/*!
    The \\c command is useful if you want a
    backslash to appear verbatim, and the word
    that contains it written in a monospace font,
    like this: \c {C:\windows\home\}.
*/

-- (barra invertida)

QDoc interpreta los guiones dobles como un guión. Los comandos de marcado de QDoc diseñados para que su entrada aparezca textualmente -como el comando \c - no sustituirán los guiones dobles por un carácter de guión bajo. Por ejemplo:

/*!
    The \\c command -- useful if you want text in a monospace font --
    is well documented.
*/

Sin embargo, otros comandos pueden requerir que los guiones se escapen para asegurar que QDoc muestra la salida como se espera. Por ejemplo;

/*!
    This \l {endash-sequence}{link to the -- (endash) sequence}
    isn't escaped and QDoc therefore renders an endash in the link
    text. However, the escaped
    \l {endash-sequence}{link to the \-- (endash) sequence}
    renders both hyphens as intended.
*/

Véase también --- (guión em).

--- (guión em)

QDoc representa los guiones triples como un guión. Los comandos de marcado de QDoc diseñados para que su entrada aparezca textualmente -como el comando \c - no sustituyen los guiones triples por un carácter de guión bajo. Por ejemplo:

/*!
    The \\c command---useful when you want text to be rendered
    verbatim---is well documented.
*/

Sin embargo, otros comandos pueden requerir que los guiones se escapen para asegurar que QDoc muestra la salida como se espera. Por ejemplo;

/*!
    This \l {emdash-sequence}{link to the --- (emdash) sequence}
    isn't escaped and QDoc therefore renders an emdash in the link
    text. However, the escaped
    \l {emdash-sequence}{link to the -\-- (emdash) sequence}
    renders both hyphens as intended.
*/

Véase también -- (guión bajo).