Inclusión de código en línea

Los siguientes comandos se utilizan para mostrar el código fuente sin formato. El código fuente comienza en una nueva línea, renderizada en el código.

\code

Los comandos \code y \endcode encierran un fragmento de código fuente.

Para documentar instrucciones de línea de comandos, scripts de shell o cualquier contenido que no esté en un lenguaje Qt reconocido por QDoc, utilice en su lugar \badcode en su lugar.

Al procesar el comando \code, QDoc elimina toda la sangría que es común para los bloques de código literal dentro de un comentario /*! ... */ antes de añadir la sangría estándar.

/*!
    \code
        #include <QApplication>
        #include <QPushButton>

        int main(int argc, char *argv[])
        {
            ...
        }
    \endcode
*/

Otros comandos de QDoc están desactivados dentro de \code... \endcode, y el carácter especial '\' se acepta y renderiza como el resto del código, a menos que vaya seguido de un dígito y se hayan pasado parámetros a \code.

Resaltado y enlace automático

Los comandos de \code intentan analizar su contenido como código de un lenguaje específico, tal y como se define en la variable de configuración de lenguaje. Esto permite resaltar y enlazar automáticamente los tipos detectados en el código.

Como excepción desde la versión 6.4 de QDoc, cuando el comando \code se utiliza dentro de un tema específico de QML, QDoc intenta primero reconocer el código como QML; para otros temas, la variable de configuración de idioma tiene preferencia. Para marcar explícitamente el fragmento de código como QML, utilice en su lugar el comando \qml en su lugar.

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 \code. Cuando se especifica, el idioma anula el idioma predeterminado y cualquier otro comportamiento específico del idioma descrito anteriormente. QDoc también define el lenguaje text para que los bloques de código puedan mostrarse sin ningún tipo de marcado o resaltado.

Por ejemplo:

\code [text]
    # This is an example of unmarked code.
    implement MyModule;
    include "sys.m";
    sys: Sys;
\endcode

Esto puede ser útil cuando se cita un lenguaje que QDoc no tiene la capacidad de marcar.

Alternativamente, puede especificar un idioma para un bloque de código que QDoc no reconoce incluyendo el idioma en la lista mantenida por la variable de configuración codelanguages. Esto permite incluir metadatos en el HTML generado que pueden ser utilizados por otras herramientas para resaltar sintácticamente el código.

Parámetros del fragmento de código

Desde la versión 5.12 de QDoc, el comando \code acepta también parámetros opcionales. Los parámetros son útiles para inyectar cadenas simples en el fragmento de código. Para inyectar una cadena en un lugar específico del fragmento de código, añada una barra invertida seguida de un dígito (1..8). Los dígitos se corresponden con el orden de la lista de argumentos, en la que los argumentos están separados por espacios y siguen a cualquier argumento opcional del lenguaje.

Por ejemplo:

/*!
    \code * hello
    /\1 \2 \1/
    \endcode
*/

Para el fragmento anterior, QDoc representa la palabra hola encerrada en un comentario de estilo C.

Inclusión de código de archivos externos

Para incluir fragmentos de código de un archivo externo, utilice las etiquetas \snippet y \codeline .

Véase también \c, \qml, \badcode, \quotefromfiley lengua.

\badcode

Similares a \codelos comandos \badcode y \endcode incluyen contenido que se reproduce literalmente en un párrafo aparte, pero no se realiza ningún análisis sintáctico ni se crean enlaces automáticamente. En su lugar, el contenido se trata como texto sin formato.

Sustituya \code por este comando cuando documente instrucciones de línea de comandos, scripts de shell o cualquier otro contenido que no esté en un lenguaje Qt, pero que deba tener un estilo similar al de un párrafo de \code.

Al igual que \code, \badcode también acepta parámetros opcionales.

\qml

Los comandos \qml y \endqml encierran un fragmento de código fuente QML. Utilícelos para resaltar correctamente la sintaxis de los fragmentos de código QML. El fragmento adjunto debe estar completo, como si fuera un archivo .qml válido. Si el fragmento está incompleto, QDoc emitirá una advertencia e ignorará el fragmento.

/*!
    \qml
        import QtQuick 2.0

        Row {
            Rectangle {
                width: 100; height: 100
                color: "blue"
                transform: Translate { y: 20 }
            }
            Rectangle {
                width: 100; height: 100
                color: "red"
                transform: Translate { y: -20 }
            }
        }
    \endqml
*/

Al igual que el comando \code\qml acepta parámetros opcionales.