| QDoc Syntax | Generated Documentation | |
|---|---|---|
| 1 | A variation of a command button is a \e menu button. | A variation of a command button is a menu button. |
| 2 | The QPushButton widget provides a \e {command button}. | The QPushButton widget provides a command button. |
| 3 | Another class of buttons are option buttons \e (see QRadioButton). | Another class of buttons are option buttons (see QRadioButton). |
| 4 | A push button emits the signal \e clicked(). | A push button emits the signal clicked(). |
| 5 | The \e QPushButton's checked property is false by default. | The QPushButton's checked property is false by default. |
This is the first section.
This is the first subsubsection.
This is the second subsubsection.
This is the third subsubsection.
This is the second subsection.
This is the first subsubsection.
...This is the second section.
This is the second section's first subsection.
This is the first subsubsection.
... \endraw \endquotation Each section is a logical unit in the document. The section heading appears in the automatically generated table of contents that normally appears in the upper right-hand corner of the page. \target sectionOne-command \section1 \\section1 The \\section1 command starts a new section. See \l{section-commands} {Section commands} for an explanation of the various section units, command argument, and rendering. \target sectionTwo-command \section1 \\section2 The \\section2 command starts a new section. See \l{section-commands} {Section commands} for an explanation of the various section units, command argument, and rendering. \target sectionThree-command \section1 \\section3 The \\section3 command starts a new section. See \l{section-commands} {Section commands} for an explanation of the various section units, command argument, and rendering. \target sectionFour-command \section1 \\section4 The \\section4 command starts a new section. See \l{section-commands} {Section commands} for an explanation of the various section units, command argument, and rendering. */ /*! \page 06-qdoc-commands-includecodeinline.html \previouspage Document Structure \nextpage Including External Code \title 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 \l{07-0-qdoc-commands-includingexternalcode.html#snippet-command} {\\snippet} and \l{07-0-qdoc-commands-includingexternalcode.html#codeline-command} {\\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. \target code-command \section1 \\code The \\code and \\endcode commands enclose a snippet of source code. \note The \l {c-command} {\\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 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
\l {badcode-command}{\\badcode} instead.
When processing any of the \\code, \l {newcode-command} {\\newcode} or \l
{oldcode-command} {\\oldcode} commands, QDoc removes all
indentation that is common for the verbatim code blocks within a
\c{/}\c{*!} ... \c{*}\c{/} comment before it adds the standard
indentation.
\note This doesn't apply to externally quoted code using the \l
{quotefromfile-command} {\\quotefromfile} or \l
{quotefile-command} {\\quotefile} command.
\code
/ *!
\code
#include
#include
int main(int argc, char *argv[])
{
...
}
\ endcode
* /
\endcode
QDoc renders this as:
\code
#include
#include
int main(int argc, char *argv[])
{
...
}
\endcode
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.
\section2 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
/ *!
\code * hello
/\1 \2 \1/
\ endcode
* /
\endcode
For the above snippet, QDoc renders the word \e hello enclosed in
a C-style comment.
\section2 Including code from external files
To include code snippets from an external file, use the
\l{07-0-qdoc-commands-includingexternalcode.html#snippet-command}
{\\snippet} and
\l{07-0-qdoc-commands-includingexternalcode.html#codeline-command}
{\\codeline} commands.
See also \l {c-command} {\\c}, \l {badcode-command} {\\badcode}, \l
{07-0-qdoc-commands-includingexternalcode.html#quotefromfile-command}
{\\quotefromfile}, \l{newcode-command} {\\newcode}, and \l {oldcode-command}
{\\oldcode}.
\target badcode-command
\section1 \\badcode
Similar to \l {code-command}{\\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.
\target newcode-command
\section1 \\newcode
The \\newcode, \\oldcode, and \\endcode commands enable you to
show how to port a snippet of code to a new version of an API.
The \\newcode command and its companion the \\oldcode command are
a convenience combination of the \l {code-command} {\\code} commands:
this combination provides a text relating the two code snippets to each
other.
The \\newcode command requires a preceding \\oldcode statement.
Like the \l{code-command}{\\code} command, the \\newcode command renders its
code on a new line in the documentation using a monospace font and the
standard indentation.
\code
/ *!
\oldcode
if (printer->setup(parent))
...
\newcode
QPrintDialog dialog(printer, parent);
if (dialog.exec())
...
\ endcode
* /
\endcode
QDoc renders this as:
\quotation
\oldcode
if (printer->setup(parent))
...
\newcode
QPrintDialog dialog(printer, parent);
if (dialog.exec())
...
\endcode
\endquotation
Other QDoc commands are disabled within \\oldcode ... \\endcode,
and the '\\' character doesn't need to be escaped.
\target oldcode-command
\section1 \\oldcode
The \\oldcode command requires a corresponding
\\newcode statement; otherwise QDoc fails to parse the command
and emits a warning.
See also \l {newcode-command} {\\newcode}.
\target qml-command
\section1 \\qml
The \\qml and \\endqml commands enclose a snippet of QML source
code.
\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
* /
\endcode
QDoc renders this as:
\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
Like the \l{code-command}{\\code} command, \\qml accepts optional
parameters.
*/
/*!
\page 07-0-qdoc-commands-includingexternalcode.html
\previouspage Including Code Inline
\nextpage Creating Links
\title Including External Code
The following commands enable you to include code snippets from
external files. You can make QDoc include the complete contents of
a file, or you can quote specific parts of the file and skip
others. The typical use of the latter is to quote a file chunk by
chunk.
\note Although all these commands can be used for rendering C++
code, the
\l{07-0-qdoc-commands-includingexternalcode.html#snippet-command}
{\\snippet} and
\l{07-0-qdoc-commands-includingexternalcode.html#codeline-command}
{\\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.
\target quotefile-command
\section1 \\quotefile
The \\quotefile command expands to the complete contents of the
file given as argument.
The command considers the rest of the line as part of its
argument, make sure to follow the file name with a line break.
The file's contents is rendered in a separate paragraph, using a
monospace font and the standard indentation. The code is shown
verbatim.
\code
/ *!
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.
* /
\endcode
QDoc renders this as:
\quotation
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.
\endquotation
See also \l {quotefromfile-command} {\\quotefromfile} and
\l {code-command} {\\code}.
\target quotefromfile-command
\section1 \\quotefromfile
The \\quotefromfile command opens the file given as argument for
quoting.
The command considers the rest of the line as part of its
argument, make sure to follow the file name with a line break.
The command is intended for use when quoting parts from file with
the walkthrough commands: \l {printline-command} {\\printline}, \l
{printto-command} {\\printto}, \l {printuntil-command}
{\\printuntil}, \l {skipline-command} {\\skipline}, \l
{skipto-command} {\\skipto}, \l {skipuntil-command}
{\\skipuntil}. This enables you to quote specific portions of a
file.
\code
/ *!
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.
...
* /
\endcode
QDoc renders this as:
\quotation
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.
...
\endquotation
QDoc remembers which file it is quoting from, and the current
position in that file (see \l {file} {\\printline} for more
information). There is no need to "close" the file.
See also \l {quotefile-command} {\\quotefile}, \l {code-command}
{\\code} and \l {dots} {\\dots}.
\target printline-command
\section1 \\printline
The \\printline command expands to the line from the current
position to the next non-blank line of the current source file.
To ensure that the documentation remains synchronized with the
source file, a substring of the line must be specified as an
argument to the command. Note that the command considers the rest
of the line as part of its argument, make sure to follow the
substring with a line break.
The line from the source file is rendered as a separate paragraph,
using a monospace font and the standard indentation. The code is
shown verbatim.
\code
/ *!
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...
* /
\endcode
QDoc renders this as:
\quotation
There has to be exactly one QApplication object
in every GUI application that uses Qt.
\quotefromfile examples/main.cpp
\skipto QApplication
\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...
\endquotation
\target file
QDoc reads the file sequentially. To move the current position
forward you can use either of the \l {skipline-command}
{\\skip...} commands. To move the current position backward, you
can use the \l {quotefromfile-command} {\\quotefromfile} command
again.
\target substring
If the substring argument is surrounded by slashes it is
interpreted as a \l {QRegularExpression}{regular expression}.
\code
/ *!
\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.
* /
\endcode
QDoc renders this as:
\quotation
\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.
\endquotation
(\l {widgets/scribble} {The complete example file...})
The regular expression \c /^\}/ makes QDoc print until the first
'}' character occurring at the beginning of the line without
indentation. /.../ encloses the regular expression, and '^' means
the beginning of the line. The '}' character must be escaped since
it is a special character in regular expressions.
QDoc will emit a warning if the specified substring or regular
expression cannot be located, i.e. if the source code has changed.
See also \l {printto-command} {\\printto} and \l
{printuntil-command} {\\printuntil}.
\target printto-command
\section1 \\printto
The \\printto command expands to all the lines from the current
position up to and \e excluding the next line containing a given
substring.
The command considers the rest of the line as part of its
argument, make sure to follow the substring with a line break. The
command also follows the same conventions for \l {file}
{positioning} and \l {substring} {argument} as the \l
{printline-command} {\\printline} command.
The lines from the source file are rendered in a separate
paragraph, using a monospace font and the standard
indentation. The code is shown verbatim.
\code
/ *!
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...
* /
\endcode
QDoc renders this as:
\quotation
The whole application is contained within the
\c main() function:
\quotefromfile examples/main.cpp
\skipto main
\printto hello
First we create a QApplication object using the \c argc
and \c argv parameters...
\endquotation
See also \l {printline-command} {\\printline} and \l
{printuntil-command} {\\printuntil}.
\target printuntil-command
\section1 \\printuntil
The \\printuntil command expands to all the lines from the current
position up to and \e including the next line containing a given
substring.
The command considers the rest of the line as part of its
argument, make sure to follow the substring with a line break. The
command also follows the same conventions for \l {file}
{positioning} and \l {substring} {argument} as the \l
{printline-command} {\\printline} command.
If \\printuntil is used without an argument, it expands to all the
lines from the current position to the end of the quoted file.
The lines from the source file are rendered in a separate
paragraph, using a monospace font and the standard
indentation. The code is shown verbatim.
\code
/ *!
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.
* /
\endcode
QDoc renders this as:
\quotation
The whole application is contained within the
\c main() function:
\quotefromfile examples/main.cpp
\skipto main
\printuntil hello
First we create a \l
{http://doc.qt.io/qt-6/qapplication.html} {QApplication}
object using the \c argc and \c argv parameters, then we
create a \l
{http://doc.qt.io/qt-6/qpushbutton.html} {QPushButton}.
\endquotation
See also \l {printline-command} {\\printline} and \l
{printto-command} {\\printto}.
\target skipline-command
\section1 \\skipline
The \\skipline command ignores the next non-blank line in the
current source file.
Doc reads the file sequentially, and the \\skipline command is
used to move the current position (omitting a line of the source
file). See the remark about \l {file} {file positioning} above.
The command considers the rest of the line as part of its
argument, make sure to follow the substring with a line break. The
command also follows the same conventions for \l {substring}
{argument} as the \l {printline-command} {\\printline} command,
and it is used in conjunction with the \l {quotefromfile-command}
{\\quotefromfile} command.
\code
/ *!
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.
* /
\endcode
QDoc renders this as:
\quotation
\l
QPushButton is a GUI push button that the user
can press and release.
\quotefromfile examples/main.cpp
\skipto QApplication
\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.
\endquotation
See also \l {skipto-command} {\\skipto}, \l {skipuntil-command}
{\\skipuntil} and \l {dots} {\\dots}.
\target skipto-command
\section1 \\skipto
The \\skipto command ignores all the lines from the current
position up to and \e excluding the next line containing a given
substring.
QDoc reads the file sequentially, and the \\skipto command is used
to move the current position (omitting one or several lines of the
source file). See the remark about \l {file} {file positioning}
above.
The command considers the rest of the line as part of its
argument, make sure to follow the substring with a line break.
The command also follows the same conventions for \l {substring}
{argument} as the \l {printline-command} {\\printline} command,
and it is used in conjunction with the \l {quotefromfile-command}
{\\quotefromfile} command.
\code
/ *!
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...
* /
\endcode
QDoc renders this as:
\quotation
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 ...
\endquotation
See also \l {skipline-command} {\\skipline}, \l
{skipuntil-command} {\\skipuntil} and \l {dots} {\\dots}.
\target skipuntil-command
\section1 \\skipuntil
The \\skipuntil command ignores all the lines from the current
position up to and \e including the next line containing a given
substring.
QDoc reads the file sequentially, and the \\skipuntil command is
used to move the current position (omitting one or several lines
of the source file). See the remark about \l {file} {file
positioning} above.
The command considers the rest of the line as part of its
argument, make sure to follow the substring with a line break.
The command also follows the same conventions for \l {substring}
{argument} as the \l {printline-command} {\\printline} command,
and it is used in conjunction with the \l {quotefromfile-command}
{\\quotefromfile} command.
\code
/ *!
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...
* /
\endcode
QDoc renders this as:
\quotation
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...
\endquotation
See also \l {skipline-command} {\\skipline}, \l {skipto-command}
{\\skipto} and \l {dots} {\\dots}.
\target dots-command
\section1 \\dots
The \\dots command indicates that parts of the source file have
been omitted when quoting a file.
The command is used in conjunction with the \l
{quotefromfile-command} {\\quotefromfile} command, and should be
stated on its own line. The dots are rendered on a new line, using
a monospace font.
\code
/ *!
\quotefromfile examples/main.cpp
\skipto main
\printuntil {
\dots
\skipuntil exec
\printline }
* /
\endcode
QDoc renders this as:
\quotefromfile examples/main.cpp
\skipto main
\printuntil {
\dots
\skipuntil exec
\printline }
The default indentation is 4 spaces, but this can be adjusted
using the command's optional argument.
\code
/ *!
\dots 0
\dots
\dots 8
\dots 12
\dots 16
* /
\endcode
QDoc renders this as:
\dots 0
\dots
\dots 8
\dots 12
\dots 16
See also \l {skipline-command} {\\skipline}, \l {skipto-command}
{\\skipto} and \l {skipuntil-command} {\\skipuntil}.
\target snippet-command
\section1 \\snippet
The \\snippet command causes a code snippet to be included
verbatim as preformatted text, which may be syntax highlighted.
Each code snippet is referenced by the file that holds it and by
a unique identifier for that file. Snippet files are typically
stored in a \c{snippets} directory inside the documentation
directory (for example, \c{$QTDIR/doc/src/snippets}).
For example, the following documentation references a snippet in a
file residing in a subdirectory of the documentation directory:
\code
\snippet snippets/textdocument-resources/main.cpp Adding a resource
\endcode
The text following the file name is the unique identifier for the
snippet. This is used to delimit the quoted code in the relevant
snippet file, as shown in the following example that corresponds to
the above \c{\snippet} command:
\code
...
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]
...
\endcode
By default, QDoc looks for \c{//!} as a code snippet marker.
For \c{.pro}, \c{.py}, \c{.cmake}, and \c{CMakeLists.txt}
files, \c {#!} is detected. Finally, \c{