Qt wiki will be updated on October 12th 2023 starting at 11:30 AM (EEST) and the maintenance will last around 2-3 hours. During the maintenance the site will be unavailable.
QDoc Style Guidelines
| This article may require cleanup to meet the Qt Wiki's quality standards. Reason: Content needs to be reviewed, Importscript broke QDoc command representation Please improve this article if you can. Remove the {{cleanup}} tag and add this page to Updated pages list after it's clean. |
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:
- Use the title of the page, class, or QML type with the command and not 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:
- the parameter for the command is displayed as monospace font, indicating it is code, return value, or a value used directly by the developer. and - content within the two commands are for writing code samples and is displayed in monospace font bound by a box. Syntax highlighting is enabled.
- and - for valid (and parseable) QML code. QDoc may give warnings if the code is not parseable. Syntax highlighting is enabled.
- and - Syntax highlighting disabled. Use this for command-line code or code outside of Qt (neither C+, JavaScript, nor QML).. QDoc will not attempt to parse and highlight the code.
These commands render their arguments in a specific way.
- - See Also and creates a link to pages. Use to refer readers to similar topics.
- Note. QDoc renders the parameter in bold. 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
- and are for creating navigation links for a page. They should be written after the command but before the 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.