QDoc Style Guidelines
This page is part of the Qt Writing Guidelines. Though there are exceptions, following the guidelines ensures consistency across modules and Qt tools.
QDoc Commands and Whitespace
Here are some basic guidelines for using QDoc commands:
- When providing a link, use the title of the page, class, or QML type with the command. Don't use the HTML file name.
- The space between the command and the left curly bracket is not needed and adds extra whitespace. For example:
\l{Page Title} vs. \l {Page Title}
- It is best to have the contents within {} on one line as this helps to spot errors and is easier to search.
- Documentation comments within .cpp or code files should follow the consistency and column width set by the surrounding code. It is set to 80 columns for Qt code (though exceptions exist).
Markup and Code Blocks
Marked up text notifies the reader that the text is special, either they are code or special keywords.
- \b{bold}. Use bold to highlight special words. Limit the use of bold as it can attract too much attention.
- \e{emphasis}. Emphasized words are typically rendered in italics, therefore, follow the regular American rules for emphasis or italicization. For example, use this command for special keywords followed by its definition.
- \code ... \endcode. See paragraph below about the use of code blocks.
These QDoc commands are for writing code to be typed by the developer:
- \c - the parameter for the command is displayed as monospace font, indicating it is code, return value, or a value used directly by the developer.
- \code and \endcode - content within the two commands are for writing code samples and is displayed in monospace font bound by a box. Syntax highlighting is enabled.
- \qml and \endqml - for valid (and parseable) QML code. QDoc may give warnings if the code is not parseable. Syntax highlighting is enabled.
- \badcode and \endcode - Use this for command-line code or code outside of Qt (neither C++, JavaScript, nor QML). QDoc does not try to parse and highlight the code. Syntax highlighting disabled.
These commands render their arguments in a specific way.
- \sa - See Also and creates a link to pages. Use to refer readers to similar topics.
- \note - QDoc renders the parameter in a box. Use this command to refer to special information.
- \warning - Similar to \note, but use this command for information that can cause errors or warnings.
UI Texts
Use \uicontrol to display UI texts. UI texts are displayed to the end-user, for example, File in the file menu for many desktop applications. They are commonly used to direct the reader to click or read a particular text within their application. QDoc renders the text in bold.
\gui is also a valid command for UI text. However, it is deprecated and \uicontrol is recommended because its name and usage are closer to other documentation tools.
Brief Description with
The brief description is displayed in the API pages and in annotated lists.
- Due to compatibility reasons, the brief statement for C++ API should start with "The <CLASS> class…".
- For QML API, the brief statement should start with "<VERB>…"
- For other pages, follow the style for QML brief descriptions.
- Always terminate the brief with a period ..
For more information, visit C++ Documentation Style and QML Documentation Style.
Linking to other Pages or Sections
The topic of linking is covered in a separate page: QDoc Linking Guidelines
- \nextpage and \previouspage are for creating navigation links for a page. They should be written after the \title command but before the \brief command.
- Qt documentation hosted online and in Qt Creator is set up to utilize only \section1, \section2, and \section3 as pages' CSS only support three section levels.
- Projects not displayed within the Qt website may set the HTML.tocdepth variable in their respective QDoc HTML templates. For Qt 5, it is set to HTML.tocdepth = 2.