Miscellaneous
These commands provide miscellaneous functions connected to the visual appearance of the documentation, and to the process of generating the documentation.
\annotatedlist
The \annotatedlist command expands to a list of the members of a group, each member listed with its brief text. Below is an example from the Qt Reference Documentation:
/*!
...
\section1 Drag and Drop Classes
These classes deal with drag and drop and the necessary mime type
encoding and decoding.
\annotatedlist draganddrop
*/
This generates a list of all the C++ classes and/or QML types in the draganddrop group. A C++ class or QML type in the draganddrop group will have \ingroup draganddrop in its \class or \qmltype comment.
The group members are sorted in ascending order, based on user-visible name or title. Since QDoc 6.8, \annotatedlist and \generatelist support also custom sorting.
See also \generatelist and Sorting group members.
\qtcmakepackage
Use the \qtcmakepackage command to add CMake package information to classes and namespaces. This information will then appear in a table at the top of the class or namespace documentation page. For example:
/*!
\namespace Foo
\inheaderfile Bar
\qtcmakepackage Baz
\brief A namespace.
...
*/
QDoc will output this as
Foo Namespace
A namespace. More...
Header: #include <Bar> CMake: find_package(Qt6 REQUIRED COMPONENTS Baz)
\qtcmaketargetitem
Use the \qtcmaketargetitem command to override the item part of the CMake target_link_libraries information that's added to classes and namespaces. The command must be used in conjunction with the \module and \qtcmakepackage} commands.
See also \module and \qtcmakepackage}
\generatelist
The \generatelist command expands to a list of links to the documentation entities grouped with an \ingroup command or entities that match one of the arguments listed below. An example from the Qt Reference Documentation:
/*!
\page classes.html
\title All Classes
For a shorter list that only includes the most
frequently used classes, see \l{Qt's Main Classes}.
\generatelist classes Q
*/
This generates the All Classes page. The command accepts the following arguments:
<group-name>
With a group name as the only argument, QDoc lists all entities that use the \ingroup <group-name> command.
Sorting group members
When generating a list of group members, they are sorted in ascending order, based on user-visible name or title. Since QDoc 6.8, the default sort order can be modified:
\generatelist [descending] changelogs
Assuming the changelogs group consists of pages detailing changes in different versions, this generates the list in descending order (newest version first).
Sort key
Since QDoc 6.8, a custom sort key can be assigned to one or more group members using the \meta command:
\meta sortkey {sort key}
Sorting (ascending or descending) is then done based on these key(s), rather than user-visible titles.
Note: Any group member with a sort key is listed before members without a key (in the default ascending order). This allows raising individual group member(s) to the top of the list.
annotatedclasses
The annotatedclasses argument provides a table containing the names of all the classes, and a description of each class. Each class name is a link to the class's reference documentation. For example:
| QDial | Rounded range control (like a speedometer or potentiometer) |
| QDialog | The base class of dialog windows |
| QDir | Access to directory structures and their contents |
A C++ class is documented with the \class command. The annotation for the class is taken from the argument of the class comment's \brief command.
annotatedexamples
The annotatedexamples argument provides a complete list of all examples as a set of tables containing the titles of all the examples, and a description of each example. Each title is a link to the example's documentation.
A separate table for each module (that has documented examples) is generated, provided that the module has defined a navigation.landingpage configuration variable. The landingpage variable is used as a title for a header that precedes each table.
annotatedattributions
The annotatedattributions argument provides a complete list of all attributions as a set of tables containing the titles of all the attributions, and a description of each attribution. Each title is a link to the attribution's page.
A separate table for each module (that has attributions) is generated, provided that the module has defined a navigation.landingpage configuration variable. The landingpage variable is used as a title for a header that precedes each table.
classes <prefix>
The classes argument provides a complete alphabetical list of the classes. The second argument, <prefix>, is the common prefix for the class names. The class names will be sorted on the character that follows the common prefix. e.g. The common prefix for the Qt classes is Q. The common prefix argument is optional. If no common prefix is provided, the class names will be sorted on their first character.
Each class name becomes a link to the class's reference documentation. This command is used to generate the All Classes page this way:
/*!
\page classes.html
\title All Classes
\ingroup classlists
\brief Alphabetical list of classes.
This is a list of all Qt classes. For classes that
have been deprecated, see the \l{Obsolete Classes}
list.
\generatelist classes Q
*/
A C++ class is documented with the \class command.
classesbymodule
When this argument is used, a second argument is required, which specifies the module whose classes are to be listed. QDoc generates a table containing those classes. Each class is listed with the text of its \brief command.
For example, this command can be used on a module page as follows:
/*!
\page phonon-module.html
\module Phonon
\title Phonon Module
\ingroup modules
\brief Contains namespaces and classes for multimedia functionality.
\generatelist{classesbymodule Phonon}
...
*/
Each class that is a member of the specified module must be marked with the \inmodule command in its \class comment.
qmltypesbymodule
Similar to classesbymodule argument, but used for listing the QML types (excluding QML value types) from the QML module specified with the second argument.
Note: Support for this argument was introduced in QDoc 5.6.
qmlvaluetypesbymodule
Similar to qmltypesbymodule argument, but lists QML value types instead.
Note: Support for this argument was introduced in QDoc 6.7.
functionindex
The functionindex argument provides a complete alphabetical list of all the documented member functions. It is normally used only to generate the Qt function index page this way:
/*!
\page functions.html
\title All Functions
\ingroup funclists
\brief All documented Qt functions listed alphabetically with a
link to where each one is declared.
This is the list of all documented member functions and global
functions in the Qt API. Each function has a link to the
class or header file where it is declared and documented.
\generatelist functionindex
*/
legalese
The legalese argument tells QDoc to generate a list of licenses in the current documentation project. Each license is identified using the \legalese command.
overviews
The overviews argument is used to tell QDoc to generate a list by concatenating the contents of all the \group pages. Qt uses it to generate the overviews page this way:
/*!
\page overviews.html
\title All Overviews and HOWTOs
\generatelist overviews
*/
attributions
The attributions argument is used to tell QDoc to generate a list of attributions in the documentation.
related
The related argument is used in combination with the \group and \ingroup commands to list all the overviews related to a specified group. For example, the page for the Programming with Qt page is generated this way:
/*!
\group qt-basic-concepts
\title Programming with Qt
\brief The basic architecture of the Qt cross-platform application and UI framework.
Qt is a cross-platform application and UI framework for
writing web-enabled applications for desktop, mobile, and
embedded operating systems. This page contains links to
articles and overviews explaining key components and
techniuqes used in Qt development.
\generatelist {related}
*/
Each page listed on this group page contains the command:
\ingroup qt-basic-concepts
See also \annotatedlist.
\if
The \if command and the corresponding \endif command enclose parts of a QDoc comment that only will be included if the condition specified by the command's argument is true.
The command reads the rest of the line and parses it as an C++ #if statement.
/*!
\if defined(opensourceedition)
\note This edition is for the development of
\l{Qt Open Source Edition} {Free and Open Source}
software only; see \l{Qt Commercial Editions}.
\endif
*/
This QDoc comment will only be rendered if the opensourceedition preprocessor symbol is defined, and specified in the defines variable in the configuration file to make QDoc process the code within #ifdef and #endif:
defines = opensourceedition
You can also define the preprocessor symbol manually on the command line. For more information see the documentation of the defines variable.
See also \endif, \else, defines and falsehoods.
\endif
The \endif command and the corresponding \if command enclose parts of a QDoc comment that will be included if the condition specified by the \if command's argument is true.
For more information, see the documentation of the \if command.
See also \if, \else, defines and falsehoods.
\else
The \else command specifies an alternative if the condition in the \if command is false.
The \else command can only be used within \if...\endif commands, but is useful when there is only two alternatives.
\include
The \include command sends all or part of the file specified by its first argument to the QDoc input stream to be processed as a QDoc comment snippet.
The command is useful when some snippet of commands or text is to be used in multiple places in the documentation. Use the \include command wherever you want to insert a snippet into the documentation. The file containing the snippet to include, must be located under the path(s) listed in the sourcedirs or exampledirs QDoc configuration variable. It can be either any source file parsed by QDoc (or even the same one where \include command is used), or any other text file. To store snippets in a separate file that is not meant to be parsed by QDoc, use a file extension that is not listed in sources.fileextensions; for example, .qdocinc.
The command can have one or more arguments. The first argument is always a file name. The contents of the file must be QDoc input, in other words, a sequence of QDoc commands and text, but without the enclosing QDoc comment /*! ... */ delimiters. If you want to include the entire named file, leave the second argument empty. If you want to include only part of the file, see the two argument form below. Here is an example of the one argument form:
/*!
\page corefeatures.html
\title Core Features
\include examples/signalandslots.qdocinc
\include examples/objectmodel.qdocinc
\include examples/layoutmanagement.qdocinc
*/
\include filename snippet-identifier
It is a waste of time to make a separate .qdocinc file for every QDoc include snippet you want to use in multiple places in the documentation, especially given that you probably have to put the copyright/license notice in every one of these files. If you have multiple snippets to be included, you can put them all in a single file and surround each one with:
//! [snippet-id1] QDoc commands and text... //! [snippet-id1] //! [snippet-id2] More QDoc commands and text... //! [snippet-id2]
Then you can use the two-argument form of the command:
\include examples/signalandslots.qdocinc snippet-id2 \include examples/objectmodel.qdocinc another-snippet-id
The sequence of QDoc commands and text found between the two tags with the same name as the second argument is sent to the QDoc input stream. You can even have nested snippets.
Note: Snippet identifiers work also within documentation comment (/*! .. */) blocks, so it's not necessary to use a separate .qdocinc file. When processing a comment block, QDoc removes any //! comment lines from the generated output.
Extra arguments
Since QDoc 6.3, any further arguments passed to the \include command are used for injecting strings into the included content. To inject a string to a specific location in the content, add a backslash followed by a digit (1..9). The digits correspond with the order of the argument list. Enclose arguments in curly braces to ensure that QDoc renders the entire argument, including possible whitespace characters, as you expect.
Important: Each additional argument (including the snippet ID) must be enclosed in braces. If you want to include the entire file, use an empty snippet ID: {}.
For example, given the following snippet in a file includes.qdocinc:
//! [usage]
To enable \e{\1}, select \uicontrol {\2} > \uicontrol Enable.
//! [usage]
Then, the following \include line:
\include includes.qdocinc {usage} {detailed output} {Verbose}
Renders
To enable detailed output, select Verbose > Enable.
\meta
The \meta command is used for adding metadata to documentation. The command has two arguments: the first argument is the name of the metadata attribute, and the second argument is the value for the attribute. Each argument should be enclosed in curly brackets, as shown in this example:
/*!
\example demos/coffee
\title Coffee Machine
\brief A Qt Quick application with a state-based custom user interface.
\meta {tags} {quick,embedded,states,touch}
\meta {category} {Application Examples}
*/
A number of metadata attributes have a specific purpose:
Example Metadata
Another use for \meta command is to include metadata (tags) in \example documentation. By default, QDoc generates example tags based on the example's \title and module name. These tags are displayed in Qt Creator's Welcome mode, helping users navigate the list of examples.
Additional tags can be created with \meta {tag} {tag1} or \meta {tags} {tag1,[tag2,...]}. For example:
/*!
\example helloworld
\title Hello World Example
\meta {tags} {tutorial,basic}
*/
This would result in the following tags: tutorial,basic,hello,world. Common words such as example are ignored.
Excluding Examples
Marking an example broken will exclude it from the generated manifest file, effectively removing it from Qt Creator's Welcome mode.
\meta {tag} {broken}
Example Install Paths
The \meta command combined with an argument installpath specifies the location of an installed example. This value overrides the one that is set using the examplesinstallpath configuration variable.
/*!
\example helloworld
\title Hello World Example
\meta {installpath} {tutorials}
*/
See also examplesinstallpath.
Status
A status argument for the \meta command adds a custom status description for a \class or a \qmltype. This description will then appear in a table at the top of the type reference page.
/*!
\class QNativeInterface::QAndroidApplication
\meta {status} {Android-specific}
*/
See also status-related commands.
\noautolist
The \noautolist command indicates that the annotated list of C++ classes or QML types, which is automatically generated at the bottom of the C++ or QML module page should be omitted, because the classes or types have been listed manually. This command can also be used with the \group command to omit the list of group members, when they are listed manually.
The command must stand on its own line. See Qt Quick Controls QML Types for an example. The page is generated from qtquickcontrols2-qmlmodule.qdoc. There you will find a QDoc comment containing the \qmlmodule command for the QtQuick.Controls module. The same comment contains a \noautolist command to disable automatic list generation, and a \generatelist to list the QML types in a specific section of the document.
This command was introduced in QDoc 5.6.
Since Qt 5.10, this command can be applied also to \example documentation, where it causes the automatically generated list of files and images belonging to an example project to be omitted.
\omit
The \omit command and the corresponding \endomit command delimit parts of the documentation that you want QDoc to skip. For example:
/*!
\table
\row
\li Basic Widgets
\li Basic GUI widgets such as buttons, comboboxes
and scrollbars.
\omit
\row
\li Component Model
\li Interfaces and helper classes for the Qt
Component Model.
\endomit
\row
\li Database Classes
\li Database related classes, e.g. for SQL databases.
\endtable
*/
\raw (avoid!)
The \raw command and the corresponding \endraw command delimit a block of raw mark-up language code.
Warning: Avoid using this command if possible. If you are trying to generate special table or list behavior, try to get the behavior you want using the \span and \div commands in your \table or \list.
The command takes an argument specifying the code's format.
QDoc generates the given code only when generating the format that was specified by the user.
For example, "\raw HTML" will only generate code when QDoc generates HTML documentation.
Note: You can often achieve the intended purpose by using QDoc commands, while reducing the chance of mistakes or content becoming unmaintained.
\sincelist
The \sincelist command expands to a detailed breakdown of new inclusions to the documented API in a specified version. Example usage:
/*!
\page newclasses68.html
\title New Classes and Functions in 6.8
\brief A comprehensive list of new classes and functions in 6.8.
\sincelist 6.8
*/
\sincelist takes a single argument, a version string. The generated output includes all functionality that is marked with a \since command or a since clause matching the version string.
\unicode
The \unicode command allows you to insert an arbitrary Unicode character in the document.
The command takes an argument specifying the character as an integer. By default, base 10 is assumed, unless a '0x' or '0' prefix is specified (for base 16 and 8, respectively).