Use the macro variable to create your own simple QDoc commands.

Macros are useful for:

  • Including recurring text, such as formatted text snippets, into documentation.
  • Pulling in information, such as version strings, from the build system into .documentation.
  • Maintaining a single location for strings that are likely to change in the future, such as product names.
  • Making sure that a term or product name is used consistently.
  • Styling the generated documentation by using HTML and DocBook elements, such as forced line breaks and special characters.
  • Using tabs to show examples of content for different programming languages, operating systems, or tools, for example.

Global Macros

For a set of predefined global macros that you can use in all documentation projects and their current values, see /qtbase/doc/global/macros.qdocconf and /qtbase/doc/global/htmltabs.qdocconf. They have macros that include:

Qt Online Installer copies the macros files to your Qt installation folder, so you can use the macros even if you build the documentation using QDoc from an installed Qt (as opposed to building QDoc yourself from sources).

Note: The values of the global macros might change between Qt versions, so the macros might be extended differently depending on the Qt version that you use to build the documentation.

Adding Macros

You can add macros for a particular documentation project in the .qdocconf file of the project or any .qdocconf file that you include into it. If the macro could be useful in more than one documentation project, add it to the global macros file.

For more information about the macro syntax and options, see macro.

Using Macros

You can use macros in the same way as the built-in QDoc commands in:

  • Code source files, in documentation comments (.cpp, .qml)
  • Documentation source files (.qdoc, .qdocinc)

For example:

\QOI copies the macros files to your Qt installation folder.

Obsolete Macros

The global macros file contains the following obsolete macros for compatibility with older documentation sets.

Don't UseUse
\returnWrite Returns or returns.

See also macro and Unknown macro.

© 2024 The Qt Company Ltd. Documentation contributions included herein are the copyrights of their respective owners. The documentation provided herein is licensed under the terms of the GNU Free Documentation License version 1.3 as published by the Free Software Foundation. Qt and respective logos are trademarks of The Qt Company Ltd. in Finland and/or other countries worldwide. All other trademarks are property of their respective owners.