Incluir código externo

Los siguientes comandos le permiten incluir fragmentos de código de archivos externos. Puede hacer que QDoc incluya el contenido completo de un archivo, o puede citar partes específicas del archivo y omitir otras. El uso típico de esta última opción es citar un archivo fragmento a fragmento.

\quotefile

El comando \quotefile se expande al contenido completo del archivo dado como argumento.

El comando considera el resto de la línea como parte de su argumento, asegúrese de seguir el nombre del archivo con un salto de línea.

El contenido del archivo se muestra en un párrafo separado, utilizando una fuente monoespaciada y la sangría estándar. El código se muestra literalmente.

/*!
   This is a simple "Hello world" example:

   \quotefile examples/main.cpp

   It contains only the bare minimum you need
   to get a Qt application up and running.
*/

A partir de la versión 6.11, se puede especificar un idioma como argumento opcional que no distingue entre mayúsculas y minúsculas en la misma línea que el comando \quotefile. Esto influye en el texto citado de la misma manera que para el comando \code .

Por ejemplo:

\quotefile [text] examples/main.cpp

Esto puede ser útil cuando se cita desde un archivo que contiene código fuente que QDoc no tiene la capacidad de marcar.

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

\quotefromfile

El comando \quotefromfile abre el archivo dado como argumento para citarlo.

El comando considera el resto de la línea como parte de su argumento, asegúrese de seguir el nombre del archivo con un salto de línea.

Este comando se utiliza para citar partes de un archivo con los comandos de recorrido: \printline, \printto, \printuntil, \skipline, \skipto, \skipuntil. Esto le permite citar partes específicas de un archivo.

/*!
   The whole application is contained within
   the \c main() function:

   \quotefromfile examples/main.cpp

   \skipto main
   \printuntil app(argc, argv)

   First we create a QApplication object using
   the \c argc and \c argv parameters.

   \skipto QPushButton
   \printuntil resize

   Then we create a QPushButton, and give it a reasonable
   size using the QWidget::resize() function.

   ...
*/

QDoc recuerda de qué archivo está citando y la posición actual en ese archivo (véase \printline para obtener más información). No es necesario "cerrar" el archivo.

A partir de la versión 6.11, se puede especificar un idioma como argumento opcional que no distingue entre mayúsculas y minúsculas en la misma línea que el comando \quotefromfile. Esto influye en el texto citado de la misma manera que para el comando \code .

Por ejemplo:

\quotefromfile [text] examples/main.cpp
\skipto main
\printuntil app(argc, argv)

QDoc también recuerda de qué lenguaje de código está citando, por lo que comandos como \printline, \printto y \printuntil citan desde el archivo actual, aplicando un estilo consistente de marcado hasta que se lee un nuevo archivo.

Véase también \quotefile, \code y \dots.

\printline

El comando \printline se expande a la línea desde la posición actual.

Para garantizar que la documentación permanece sincronizada con el archivo fuente, debe especificarse una subcadena de la línea como argumento del comando. Tenga en cuenta que el comando considera el resto de la línea como parte de su argumento, asegúrese de seguir la subcadena con un salto de línea.

La línea del archivo fuente se muestra como un párrafo separado, utilizando una fuente monoespaciada y la sangría estándar. El código se muestra literalmente.

/*!
   There has to be exactly one QApplication object
   in every GUI application that uses Qt.

   \quotefromfile examples/main.cpp

   \printline QApplication

   This line includes the QApplication class
   definition. QApplication manages various
   application-wide resources, such as the
   default font and cursor.

   \printline QPushButton

   This line includes the QPushButton class
   definition. The QPushButton widget provides a command
   button.

   \printline main

   The main function...
*/

QDoc lee el fichero secuencialmente. Para mover la posición actual hacia adelante, puede utilizar cualquiera de los comandos \skip. ... Para mover la posición actual hacia atrás, puede utilizar el comando \quotefromfile de nuevo.

Si el argumento de la subcadena está rodeado de barras inclinadas, se interpreta como regular expression.

/*!
   \quotefromfile examples/mainwindow.cpp

   \skipto closeEvent
   \printuntil /^\}/

   Close events are sent to widgets that the users want to
   close, usually by clicking \c File|Exit or by clicking
   the \c X title bar button. By reimplementing the event
   handler, we can intercept attempts to close the
   application.
*/

(El archivo de ejemplo completo...)

La expresión regular /^\}/ hace que QDoc imprima hasta el primer carácter '}' que aparezca al principio de la línea sin sangría. /.../ encierra la expresión regular, y '^' significa el principio de la línea. El carácter '}' debe escaparse, ya que es un carácter especial en las expresiones regulares.

QDoc emitirá una advertencia si la subcadena o expresión regular especificada no puede localizarse, es decir, si el código fuente ha cambiado.

Véase también \printto y \printuntil.

\printto

El comando \printto se expande a todas las líneas desde la posición actual hasta y excluyendo la siguiente línea que contenga una subcadena dada.

El comando considera el resto de la línea como parte de su argumento, asegúrese de seguir la subcadena con un salto de línea. El comando también sigue las mismas convenciones de posicionamiento y argumento que el comando \printline .

Las líneas del archivo fuente se muestran en un párrafo separado, utilizando una fuente monospace y la sangría estándar. El código se muestra literalmente.

/*!
   The whole application is contained within the
   \c main() function:

   \quotefromfile examples/main.cpp
   \printto hello

   First we create a QApplication object using the \c argc and
   \c argv parameters...
*/

Véase también \printline y \printuntil.

\printuntil

El comando \printuntil se expande a todas las líneas desde la posición actual hasta la siguiente línea inclusive que contenga una subcadena dada.

El comando considera el resto de la línea como parte de su argumento, asegúrese de seguir la subcadena con un salto de línea. El comando también sigue las mismas convenciones de posicionamiento y argumento que el comando \printline .

Si se utiliza \printuntil sin argumento, se expande a todas las líneas desde la posición actual hasta el final del archivo citado.

Las líneas del fichero fuente se muestran en un párrafo separado, utilizando una fuente monoespaciada y la sangría estándar. El código se muestra literalmente.

/*!
   The whole application is contained within the
   \c main() function:

   \quotefromfile examples/main.cpp
   \skipto main
   \printuntil hello

   First we create a QApplication object using the
   \c argc and \c argv parameters, then we create
   a QPushButton.
*/

Véase también \printline y \printto.

\skipline

El comando \skipline ignora la siguiente línea no en blanco del archivo fuente actual.

Doc lee el fichero secuencialmente, y el comando \skipline se utiliza para mover la posición actual (omitiendo una línea del fichero fuente). Véase la observación anterior sobre el posicionamiento del fichero.

El comando considera el resto de la línea como parte de su argumento, asegúrese de seguir la subcadena con un salto de línea. El comando también sigue las mismas convenciones para los argumentos que el comando \printline y se utiliza junto con el comando \quotefromfile comando.

/*!
   QPushButton is a GUI push button that the user
   can press and release.

   \quotefromfile examples/main.cpp
   \skipline QApplication
   \printline QPushButton

   This line includes the QPushButton class
   definition. For each class that is part of the
   public Qt API, there exists a header file of
   the same name that contains its definition.
*/

Véase también \skipto, \skipuntil y \dots.

\skipto

El comando \skipto ignora todas las líneas desde la posición actual hasta y excluyendo la siguiente línea que contenga una subcadena dada.

QDoc lee el fichero secuencialmente, y el comando \skipto se utiliza para desplazar la posición actual (omitiendo una o varias líneas del fichero fuente). Véase la observación anterior sobre el posicionamiento del archivo.

El comando considera el resto de la línea como parte de su argumento, asegúrese de seguir la subcadena con un salto de línea.

El comando también sigue las mismas convenciones para los argumentos que el comando \printline y se utiliza junto con el comando \quotefromfile comando.

/*!
   The whole application is contained within
   the \c main() function:

   \quotefromfile examples/main.cpp
   \skipto main
   \printuntil }

   First we create a QApplication object. There
   has to be exactly one such object in
   every GUI application that uses Qt. Then
   we create a QPushButton, resize it to a reasonable
   size ...
*/

Véase también \skipline, \skipuntil y \dots.

\skipuntil

El comando \skipuntil ignora todas las líneas desde la posición actual hasta la siguiente línea incluida que contenga una subcadena determinada.

QDoc lee el archivo secuencialmente, y el comando \skipuntil se utiliza para desplazar la posición actual (omitiendo una o varias líneas del archivo fuente). Véase la observación anterior sobre el posicionamiento del archivo.

El comando considera el resto de la línea como parte de su argumento, asegúrese de seguir la subcadena con un salto de línea.

El comando también sigue las mismas convenciones para los argumentos que el comando \printline y se utiliza junto con el comando \quotefromfile comando.

/*!
   The first thing we did in the \c main() function
   was to create a QApplication object \c app.

   \quotefromfile examples/main.cpp
   \skipuntil show
   \dots
   \printuntil }

   In the end we must remember to make \c main() pass the
   control to Qt. QCoreApplication::exec() will return when
   the application exits...
*/

Véase también \skipline, \skipto y \dots.

\dots

El comando \dots indica que se han omitido partes del archivo fuente al citar un archivo.

Este comando se utiliza junto con el comando \quotefromfile y debe indicarse en su propia línea. Los puntos se representan en una nueva línea, utilizando una fuente monoespaciada.

/*!
   \quotefromfile examples/main.cpp
   \skipto main
   \printuntil {
   \dots
   \skipuntil exec
   \printline }
*/

La sangría por defecto es de 4 espacios, pero puede ajustarse utilizando el argumento opcional del comando.

/*!
    \dots 0
    \dots
    \dots 8
    \dots 12
    \dots 16
*/

Véase también \skipline, \skipto y \skipuntil.

\snippet

El comando \snippet hace que un fragmento de código se incluya literalmente como texto preformateado, que puede estar resaltado sintácticamente.

Cada fragmento de código está referenciado por el archivo que lo contiene y por un identificador único para ese archivo. Los archivos de fragmentos de código suelen almacenarse en un directorio snippets dentro del directorio de documentación (por ejemplo, $QTDIR/doc/src/snippets).

Por ejemplo, la siguiente documentación hace referencia a un fragmento en un archivo que reside en un subdirectorio del directorio de documentación:

\snippet snippets/textdocument-resources/main.cpp Adding a resource

El texto que sigue al nombre del archivo es el identificador único del fragmento. Se utiliza para delimitar el código citado en el archivo de fragmentos correspondiente, como se muestra en el siguiente ejemplo que corresponde al comando \snippet anterior:

    ...
    QImage image(64, 64, QImage::Format_RGB32);
    image.fill(qRgb(255, 160, 128));

//! [Adding a resource]
    document->addResource(QTextDocument::ImageResource,
        QUrl("mydata://image.png"), QVariant(image));
//! [Adding a resource]
    ...

Por defecto, QDoc busca //! como marcador de fragmento de código. Para los archivos .pro, .py, .cmake y CMakeLists.txt, se detecta #!. Por último, se acepta <!-- en los archivos .html, .qrc, .ui, .xml y .xq.

QDoc normaliza la sangría de los fragmentos comparando la sangría basada en el espacio del marcador de fragmento con la sangría mínima del contenido del fragmento (ignorando las macros Qt, las líneas en blanco y los comentarios de línea completa). A continuación, automáticamente elimina la sangría del cuerpo del fragmento de código en función de la que sea menor, lo que garantiza que el código generado siempre conserve su estructura natural, independientemente de dónde se sitúen los marcadores. Los marcadores sin sangría no se modifican.

A partir de la versión 6.11, se puede especificar un idioma como argumento opcional que no distingue entre mayúsculas y minúsculas en la misma línea que el comando \snippet. Esto influye en el texto citado de la misma manera que para el comando \code .

Este ejemplo de uso del comando anula el estilo de marcado C++ predeterminado y en su lugar muestra texto sin formato:

\snippet [text] code.cpp

Esto puede ser útil cuando se cita un lenguaje que QDoc no tiene la capacidad de marcar, o cuando se necesita citar desde un archivo con un nombre de archivo no convencional.

\codeline

El comando \codeline inserta una línea en blanco de texto preformateado. Se utiliza para insertar espacios entre fragmentos sin cerrar el área de texto preformateado actual y abrir una nueva.