Including Code Inline | QDoc Manual 6.4.1

- Qt 6.4
- QDoc Manual
- Including Code Inline
- Qt 6.4.1 Reference Documentation

Document Structure ◦ Including External Code

# Including Code Inline

The following commands are used to render source code without formatting. The source code begins on a new line, rendered in the code.

Note: Although most of these commands are for rendering C++ code, the \snippet and \codeline commands are preferred over the others. These commands allow equivalent code snippets for other Qt language bindings to be substituted for the C++ snippets in the documentation.

## \code

The \code and \endcode commands enclose a snippet of source code.

Note: The \c command can be used for short code fragments within a sentence. The \code command is for longer code snippets. It renders the code verbatim in a separate paragraph in a html <pre> element, and parses the enclosed snippet, creating links to any known types in the code.

For documenting command-line instructions, shell scripts, or any content that is not in a Qt language recognized by QDoc, use \badcode instead.

When processing the \code command, QDoc removes all indentation that is common for the verbatim code blocks within a `/``*!` ... `*``/` comment before it adds the standard indentation.

Note: This doesn't apply to externally quoted code using the \quotefromfile or \quotefile command.

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

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

QDoc renders this as:

     #include <QApplication>
     #include <QPushButton>

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

Other QDoc commands are disabled within \code... \endcode, and the special character '\' is accepted and rendered like the rest of the code, unless it is followed by a digit and parameters were passed to \code.

### Code snippet parameters

Since QDoc version 5.12, \code command accepts also optional parameters. Parameters are useful for injecting simple strings into the code snippet. To inject a string to a specific location in the snippet, add a backslash followed by a digit (1..8). The digits correspond with the order of the argument list, where arguments are separated by spaces.

For example:

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

For the above snippet, QDoc renders the word hello enclosed in a C-style comment.

### Including code from external files

To include code snippets from an external file, use the \snippet and \codeline commands.

See also \c, \badcode, and \quotefromfile.

## \badcode

Similar to \code, \badcode and \endcode commands enclose content that is rendered verbatim in a separate paragraph, but no parsing or automatic link creation is performed. Instead, the content is treated as plain text.

Substitute \code with this command when documenting command-line instructions, shell scripts or any other content that is not in a Qt language, but should still be styled similarly to a \code paragraph.

Like \code, \badcode accepts also optional parameters.

## \qml

The \qml and \endqml commands enclose a snippet of QML source code.

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

QDoc renders this as:

     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 }
         }
     }

Like the \code command, \qml accepts optional parameters.

Document Structure ◦ Including External Code