View source for QDoc Style Guidelines

[[Category:Writing Guidelines]]

This page is part of the [[QtWritingGuidelines | 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:

<!-- These blocks are broken, no qdoc commands represented here -->
* '''\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 [[CppDocumentationStyle | C++ Documentation Style]] and [[QMLDocumentationStyle | QML Documentation Style]].

==Linking to other Pages or Sections==

The topic of linking is covered in a separate page: [[QDocLinkingGuidelines | 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'''.