QDoc Style Guidelines

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:

• Use the title of the page, class, or QML type with the \l command and not the HTML file name.
• The space between the command and the left curly bracket is not needed and adds extra whitespace. Example:
  \l{Page Title} is more compact than \l {Page Title}.
• It is best to have the contents within {} in one line as this helps to spot errors and 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.
• \c – code. 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 \c 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 – 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.

• \sa – See Also and creates a link to pages. Use \sa to refer readers to similar topics.
• \note – Note. QDoc renders the parameter in bold. Use this command to refer to special information.
• \warning – 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, the 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 \brief

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 “\brief The <CLASS> class…”.
• For QML API, the brief statement should start with “\brief <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

Table of Contents and Page Navigation

• \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.