Jump to content

Qt Documentation Rules: Difference between revisions

From Qt Wiki
← Older editNewer edit →
VisualWikitext
No edit summary
No edit summary
Line 72: Line 72:
|-
|-
| '''R10''' || '''Avoid ambiguous pronouns''' || QUIP 25, MS Style Guide || Repeat noun when "it" or "this" is unclear
| '''R10''' || '''Avoid ambiguous pronouns''' || QUIP 25, MS Style Guide || Repeat noun when "it" or "this" is unclear
|}
=== Examples ===
{| class="wikitable"
! Rule !! ❌ Incorrect !! ✅ Correct
|-
| R1 || Events are ignored by the item when disabled. || The item ignores events when disabled.
|-
| R2 || In order to enable the feature, you need to set the property. || Set the property to enable the feature.
|-
| R3 || The programmer can use any control. || The developer can use any widget.
|-
| R4 || The function will return true if successful. || The function returns true if successful.
|-
| R5 || The value is returned by this function. || Returns the value.
|-
| R6 || One can configure the settings in the dialog. || You can configure the settings in the dialog.
|-
| R7 || Use QML types, e.g., Rectangle, via the import statement. || Use QML types, such as Rectangle, through the import statement.
|-
| R9 || Set the property; Calling the function; You should verify || Set the property; Call the function; Verify the result
|-
| R10 || The widget and the parent both update. It receives the event first. || The widget and the parent both update. The widget receives the event first.
|}
|}


Line 107: Line 131:
| '''R19''' || '''Signal brief patterns''' || C++ Doc Style, QML Doc Style || "This signal is emitted when...". Brief recommended, not mandatory.
| '''R19''' || '''Signal brief patterns''' || C++ Doc Style, QML Doc Style || "This signal is emitted when...". Brief recommended, not mandatory.
|}
|}
=== API Brief Pattern Examples ===
{| class="wikitable"
! Type !! Pattern !! Example
|-
| Class || The [Class] class provides/is... || \brief The QWidget class is the base class of all user interface objects.
|-
| Function (accessor) || Returns... || \brief Returns the current value of the property.
|-
| Function (mutator) || Sets... || \brief Sets the widget's geometry to the specified rectangle.
|-
| Function (constructor) || Constructs... || \brief Constructs a widget with the given parent.
|-
| Property || This property holds... || \brief This property holds whether the widget is enabled.
|-
| Signal || This signal is emitted when... || \brief This signal is emitted when the button is clicked.
|}
=== Class Documentation Template ===
<pre>
/*!
    \class QWidget
    \brief The QWidget class is the base class of all user interface objects.
    \inmodule QtWidgets
    \since 4.0
    A widget is the atom of the user interface...
*/
</pre>


== Example Documentation (R20-R23) ==
== Example Documentation (R20-R23) ==
Line 139: Line 194:
| '''R27''' || '''Use descriptive phrases''' || QDoc Style Guidelines || Noun phrases, not full sentences
| '''R27''' || '''Use descriptive phrases''' || QDoc Style Guidelines || Noun phrases, not full sentences
|}
|}
=== Alt Text Examples by Content Type ===
{| class="wikitable"
! Image Type !! ❌ Incorrect !! ✅ Correct
|-
| Screenshot || Screenshot of the main window || {Window with toolbar containing dark mode toggle and buttons}
|-
| Control demo || Image showing a button || {Button in various interaction states}
|-
| Custom styling || A customized switch control || {Custom styled switch in on and off states}
|-
| Wireframe || Diagram of page layout || {Page wireframe with header, content area, and footer}
|-
| Example app || Screenshot of example || {Qt logo with three light types and lighting controls}
|-
| Chart/diagram || Bar chart showing data || {Sales increased 25% in Q3}
|}
=== Alt Text Priority Order ===
# '''Option 1 (Recommended):''' Include visible text, labels, or icons from the image
# '''Option 2:''' Context-focused description (purpose, behavior, state)
# '''Option 3:''' Generic visual description
=== Formatting ===
<pre>
// Same line (within 80 columns):
\image qtquickcontrols-button-custom.png {Custom styled button}
// Next line (if exceeds 80 columns), indented to align with filename:
\image qtquickcontrols-switch.png
      {Switch control labeled Switch in off state}
</pre>


== Writing Contexts (R28-R29) ==
== Writing Contexts (R28-R29) ==
Line 200: Line 290:
|-
|-
| versus, vs. || compared to, or, against || —
| versus, vs. || compared to, or, against || —
|}
==== Sentence Examples ====
{| class="wikitable"
! ❌ Incorrect !! ✅ Correct
|-
| Pass parameters via the constructor. || Pass parameters through the constructor.
|-
| Use containers, e.g., QList or QVector. || Use containers, such as QList or QVector.
|-
| The property is read-only, i.e., it cannot be modified. || The property is read-only, that is, it cannot be modified.
|-
| Supports multiple formats (PNG, JPG, etc.). || Supports multiple formats, such as PNG, JPG, and WebP.
|}
|}


Line 377: Line 481:


The <code>page.html#anchor</code> syntax only works for explicit <code>\page</code> pages, not auto-generated type pages.
The <code>page.html#anchor</code> syntax only works for explicit <code>\page</code> pages, not auto-generated type pages.
=== R46 Detail: Link vs Code Formatting ===
{| class="wikitable"
! Situation !! Use !! Example
|-
| Documented public API || <code>\l{}</code> || <code>\l{QWidget::show()}</code>
|-
| Internal/private class || <code>\c{}</code> || <code>\c{QWidgetPrivate::init()}</code>
|-
| Private header type || <code>\c{}</code> || <code>\c{QPlatformWindow}</code>
|-
| External URL || <code>\l{}</code> with <code>\externalpage</code> || <code>\l{CMake Documentation}</code>
|}
=== R50 Detail: QML Value Type Case ===
QML value types use camelCase (lowercase first letter). Object types use PascalCase.
<pre>
// Value types (camelCase):
\l{geoCoordinate::latitude}
\l{webEngineCertificateError::defer()}
// Object types (PascalCase):
\l{ListView::delegate}
\l{WebEngineView::url}
</pre>


== Enforcement Levels ==
== Enforcement Levels ==

Revision as of 13:48, 17 February 2026

Qt Documentation Style Rules Quick Reference

This page provides a consolidated reference of language and style rules for Qt documentation, with citations to their authoritative sources. Use this as a checklist when writing or reviewing Qt documentation.

Note: These rules are prescriptive for new and updated documentation. Existing Qt documentation may not fully comply with all rules.

Sources

The following official sources define Qt documentation standards. When sources conflict, follow the hierarchy: S1 → S2 → S3/S4 → S9.

ID Source URL Purpose
S1 Qt Writing Guidelines https://wiki.qt.io/Qt_Writing_Guidelines Primary coordination document for all Qt documentation standards
S2 QUIP 25 - Documentation Writing Style https://code.qt.io/cgit/meta/quips.git/plain/quip-0025-Documentation-Writing-Style.rst Language, grammar, word choice, and formatting standards
S3 C++ Documentation Style https://wiki.qt.io/C%2B%2B_Documentation_Style Patterns and requirements for C++ API documentation
S4 QML Documentation Style https://wiki.qt.io/QML_Documentation_Style Patterns and requirements for QML API documentation
S5 Qt Examples Guidelines https://wiki.qt.io/Qt_Examples_Guidelines Code quality, screenshots, and build requirements for examples
S6 Writing Example Documentation and Tutorials https://wiki.qt.io/Writing_Example_Documentation_and_Tutorials 11 mandatory elements and tutorial structure
S7 Qt Terms and Concepts https://wiki.qt.io/Qt_Terms_and_Concepts Official Qt terminology and product naming conventions
S8 QDoc Style Guidelines https://wiki.qt.io/QDoc_Style_Guidelines QDoc command formatting and alt text rules
S9 Microsoft Writing Style Guide https://learn.microsoft.com/en-us/style-guide/welcome/ Supplementary reference when Qt sources don't specify
S10 QDoc Manual https://doc.qt.io/qt-6/qdoc-index.html QDoc command syntax (not a style authority)

API Documentation Requirements

Requirements for documenting C++ and QML APIs are defined in the official style guides:

Key points:

  • Classes and QML types require 
    \brief
    , 
    \since
    , and 
    \inmodule
    /
    \inqmlmodule
  • Properties require 
    \brief
  • Functions and methods should start with an action verb ("Returns...", "Sets...")

Core Principles (R1-R10)

These fundamental writing principles apply to all Qt documentation. They ensure clarity, consistency, and accessibility for an international audience. Derived primarily from QUIP 25 (S2), Qt Writing Guidelines (S1), and Microsoft Writing Style Guide (S9).

Rule Summary Sources Notes
R1 Use active voice QUIP 25, Qt Writing Guidelines, MS Style Guide Passive acceptable when actor unknown. "The item ignores events" not "Events are ignored by the item"
R2 Be clear and concise QUIP 25, MS Style Guide Aim for ≤20 words per sentence. "To" not "In order to"
R3 Use correct terminology QUIP 25, Qt Writing Guidelines, Qt Terms and Concepts Use "widget" not "control", "type" not "component", "developer" not "programmer"
R4 Use present tense QUIP 25, Qt Writing Guidelines, MS Style Guide "Returns true" not "Will return true"
R5 Use imperative mood for instructions MS Style Guide, C++ Doc Style, QML Doc Style Briefs: "Returns the value." Descriptions: "This property holds..."
R6 Use "you" for user instructions QUIP 25, Qt Writing Guidelines, MS Style Guide In guides/tutorials and tools docs. Not in API reference docs.
R7 Avoid jargon and Latin terms QUIP 25, Qt Writing Guidelines, MS Style Guide "for example" not "e.g.", "that is" not "i.e.", "through" not "via"
R8 Be consistent MS Style Guide Same word for same concept throughout
R9 Use parallel structure MS Style Guide List items use same grammatical form
R10 Avoid ambiguous pronouns QUIP 25, MS Style Guide Repeat noun when "it" or "this" is unclear

Examples

Rule ❌ Incorrect ✅ Correct
R1 Events are ignored by the item when disabled. The item ignores events when disabled.
R2 In order to enable the feature, you need to set the property. Set the property to enable the feature.
R3 The programmer can use any control. The developer can use any widget.
R4 The function will return true if successful. The function returns true if successful.
R5 The value is returned by this function. Returns the value.
R6 One can configure the settings in the dialog. You can configure the settings in the dialog.
R7 Use QML types, e.g., Rectangle, via the import statement. Use QML types, such as Rectangle, through the import statement.
R9 Set the property; Calling the function; You should verify Set the property; Call the function; Verify the result
R10 The widget and the parent both update. It receives the event first. The widget and the parent both update. The widget receives the event first.

Grammar Rules (R11-R13)

These grammar rules ensure consistency in punctuation, capitalization, and number formatting across all Qt documentation. Based on QUIP 25 (S2), Qt Writing Guidelines (S1), and Microsoft Writing Style Guide (S9).

Rule Summary Sources Notes
R11 Use serial (Oxford) comma QUIP 25, Qt Writing Guidelines "name, value, and type" not "name, value and type"
R12 Use sentence-case for titles Qt Writing Guidelines, QUIP 25, MS Style Guide "Getting started with Qt Quick" not "Getting Started With Qt Quick"
R13 Numbers: spell out 1-9 QUIP 25 Numerals for 10+, dimensions, versions, code values

API Documentation (R14-R19)

These rules define the required patterns for documenting C++ and QML APIs. They ensure consistency in how classes, functions, properties, and signals are documented. Based on C++ Documentation Style (S3), QML Documentation Style (S4), and QDoc Manual (S10).

Rule Summary Sources Notes
R14 \brief scope C++ Doc Style, QML Doc Style, QDoc Manual MANDATORY for: \class, \qmltype, \property, \qmlproperty, \example, \page. Recommended for: \fn, \qmlmethod, \qmlsignal, \enum
R15 Briefs end with period C++ Doc Style, QML Doc Style Applies to all briefs that are provided
R16 Class/Type documentation C++ Doc Style, QML Doc Style, QDoc Manual Requires: \class/\qmltype, \brief, \inmodule/\inqmlmodule, \since
R17 Function brief patterns C++ Doc Style, QML Doc Style Start with verb: "Returns...", "Sets...", "Constructs...". Brief recommended, not mandatory.
R18 Property brief patterns C++ Doc Style, QML Doc Style "This property holds...". Brief is mandatory for properties.
R19 Signal brief patterns C++ Doc Style, QML Doc Style "This signal is emitted when...". Brief recommended, not mandatory.

API Brief Pattern Examples

Type Pattern Example
Class The [Class] class provides/is... \brief The QWidget class is the base class of all user interface objects.
Function (accessor) Returns... \brief Returns the current value of the property.
Function (mutator) Sets... \brief Sets the widget's geometry to the specified rectangle.
Function (constructor) Constructs... \brief Constructs a widget with the given parent.
Property This property holds... \brief This property holds whether the widget is enabled.
Signal This signal is emitted when... \brief This signal is emitted when the button is clicked.

Class Documentation Template

/*!
    \class QWidget
    \brief The QWidget class is the base class of all user interface objects.
    \inmodule QtWidgets
    \since 4.0

    A widget is the atom of the user interface...
*/

Example Documentation (R20-R23)

These rules define the required elements and quality standards for Qt example documentation. Every example must meet these requirements before being included in Qt releases. Based on Writing Example Documentation and Tutorials (S6) and Qt Examples Guidelines (S5).

Rule Summary Sources Notes
R20 11 mandatory elements Writing Example Documentation Title, \example, \brief, \examplecategory, image, overview, running instructions, platform notes, main content, references, licenses
R21 Zero warnings Qt Examples Guidelines C++ compiler and qmllint must produce no warnings
R22 Screenshot specs Qt Examples Guidelines Minimum 440×320 pixels, icons 64×64, high DPI, WebP format
R23 Title guidelines Qt Examples Guidelines, Writing Example Documentation Don't repeat "Example" or module name in title

Alt Text (R24-R27)

These rules ensure images in Qt documentation are accessible to users with visual impairments. Alt text describes images for screen readers and appears when images fail to load. Based on QDoc Style Guidelines (S8) and QUIP 21.

Rule Summary Sources Notes
R24 Format: capital letter, no period QDoc Style Guidelines, QUIP 21 {Window with toolbar and buttons}
R25 Priority order QDoc Style Guidelines 1. Visible text/labels 2. Context/purpose 3. Visual description
R26 Use generic UI terms QDoc Style Guidelines "button" not "Button", "dialog" not "Dialog"
R27 Use descriptive phrases QDoc Style Guidelines Noun phrases, not full sentences

Alt Text Examples by Content Type

Image Type ❌ Incorrect ✅ Correct
Screenshot Screenshot of the main window {Window with toolbar containing dark mode toggle and buttons}
Control demo Image showing a button {Button in various interaction states}
Custom styling A customized switch control {Custom styled switch in on and off states}
Wireframe Diagram of page layout {Page wireframe with header, content area, and footer}
Example app Screenshot of example {Qt logo with three light types and lighting controls}
Chart/diagram Bar chart showing data {Sales increased 25% in Q3}

Alt Text Priority Order

  1. Option 1 (Recommended): Include visible text, labels, or icons from the image
  2. Option 2: Context-focused description (purpose, behavior, state)
  3. Option 3: Generic visual description

Formatting

// Same line (within 80 columns):
\image qtquickcontrols-button-custom.png {Custom styled button}

// Next line (if exceeds 80 columns), indented to align with filename:
\image qtquickcontrols-switch.png
       {Switch control labeled Switch in off state}

Writing Contexts (R28-R29)

Different types of Qt documentation require different writing styles. API reference documentation is formal and technical, while tutorials are conversational and instructional. These rules help you choose the right style for each context. Based on C++ Documentation Style (S3), QML Documentation Style (S4), Qt Writing Guidelines (S1), and Writing Example Documentation and Tutorials (S6).

Rule Summary Sources Notes
R28 API documentation style C++ Doc Style, QML Doc Style Present tense, imperative briefs, indicative descriptions, no "you"
R28b Tools documentation style Qt Writing Guidelines Present tense, "you" acceptable, UI elements in bold, menu paths with >
R29 User guide/tutorial style Qt Writing Guidelines, Writing Example Documentation Use "you", explain concepts, less jargon

Common Mistakes (R30-R37)

This quick reference lists the most frequent documentation errors and their corrections. Use this as a checklist when reviewing documentation. Each mistake references the rule that explains the correct approach.

Rule Mistake Correction Cross-ref
R30 Passive voice Use active voice R1
R31 Future tense Use present tense R4
R32 Wordy phrases Be concise R2
R33 Ambiguous "this" Be specific R10
R34 Inconsistent terms Pick one term R8
R35 Missing \brief on class/type/property Add \brief R14
R36 Brief without period Add period R15
R37 "Neutral voice" Use "imperative mood" or "indicative mood" QUIP 25

Common Substitutions (R38)

This section lists words and phrases to avoid in Qt documentation, along with their preferred alternatives. These substitutions improve clarity and accessibility for international readers. Based on QUIP 25 (S2) and Microsoft Writing Style Guide (S9).

Latin Terms (Always Avoid)

Latin abbreviations are not universally understood. Replace them with plain English equivalents.

Instead of Use Source
e.g. for example, such as, like MS Style Guide
i.e. that is MS Style Guide
etc. (be specific, or use "such as" + examples) MS Style Guide
via through, using, with, by QUIP 25, MS Style Guide
per according to, for each —
versus, vs. compared to, or, against —

Sentence Examples

❌ Incorrect ✅ Correct
Pass parameters via the constructor. Pass parameters through the constructor.
Use containers, e.g., QList or QVector. Use containers, such as QList or QVector.
The property is read-only, i.e., it cannot be modified. The property is read-only, that is, it cannot be modified.
Supports multiple formats (PNG, JPG, etc.). Supports multiple formats, such as PNG, JPG, and WebP.

Verbose Phrases

Replace wordy phrases with concise alternatives to improve readability.

Instead of Use Source
In order to To QUIP 25, MS Style Guide
It is possible to You can / Can QUIP 25
Make use of Use MS Style Guide
At this point in time Now —
Due to the fact that Because —
Is able to Can —

Hedging Words (Avoid)

These words can be condescending or assume reader knowledge. Avoid them in most contexts.

Avoid Reason Source
simply, just Implies task is trivial QUIP 25
obviously, clearly Assumes reader knowledge QUIP 25
easily May not be easy for reader QUIP 25
please Use only for inconvenient requests QUIP 25

Terminology

Use Qt's preferred terminology for consistency across all documentation.

Instead of Use Source
programmer developer QUIP 25
since, as (for causation) because QUIP 25, MS Style Guide
utilize use MS Style Guide

QDoc Formatting (R39-R41)

These rules cover QDoc-specific formatting conventions, including command syntax and line length limits. Based on QDoc Style Guidelines (S8) and Qt Coding Style.

Rule Summary Sources Enforcement
R39 No space before curly brace QDoc Style Guidelines Recommended for compact text. 
\l{QWidget}
preferred over 
\l {QWidget}
. Not strictly enforced.
R40 80-column line length Qt Coding Style, QDoc Style Guidelines CI-enforced. For documentation comments and .qdoc files.
R41 \sa targets must match page titles Qt Doc Team practice Required. Verify targets resolve to actual pages.

UI and Tools Documentation (R42-R44)

These rules apply specifically to documentation for Qt tools like Qt Creator and Qt Design Studio. They cover how to format UI elements, keyboard shortcuts, and menu paths. Based on Qt Writing Guidelines (S1) and Qt Creator documentation conventions.

Rule Summary Sources Notes
R42 UI element markup Qt Writing Guidelines, Qt Creator docs Bold for UI elements: File > New Project. In QDoc: 
\uicontrol{element}
R43 Keyboard shortcut formatting Qt Creator docs 
Ctrl+B
, sequential: 
Ctrl+K, Ctrl+D
, platform: 
Ctrl+O
(
Cmd+O
on macOS)
R44 Menu path formatting Qt Creator docs Go to File > New Project > Qt Quick Application

Qt Product and Module Names (R3 Detail)

Official Qt product and module names must use correct capitalization and spelling. This ensures consistency and brand accuracy across all documentation. Per Qt Terms and Concepts (S7).

Correct Incorrect Notes
Qt GUI Qt Gui, Qt gui Acronyms all caps
Qt SQL Qt Sql Acronym all caps
Qt SVG Qt Svg Acronym all caps
Qt XML Qt Xml Acronym all caps
Qt Quick QtQuick (in prose) Two words in prose
Qt Add-Ons Qt Addon, Qt Addons Hyphenated
Qt D-Bus Qt DBus, Qt DBUS Hyphenated
Qt Creator QtCreator Two words
QDoc Qdoc, qdoc CamelCase

Compound Words (R3 Detail)

Qt documentation uses specific compound word conventions. Use these spellings consistently.

Correct Incorrect
checkbox check box
filename file name
namespace name space
runtime run time, run-time
framerate frame rate
toolchain tool chain
codebase code base
standalone stand-alone

Tools-Specific Terminology (R3 Detail)

Qt Creator and Qt Design Studio use specific terminology that should be used consistently in tools documentation.

Term Correct Usage Context
kit kit (not "configuration set") Qt Creator
toolchain toolchain (not "tool chain") All
build system build system (not "buildsystem") All
mode Edit mode, Design mode, Debug mode Qt Creator, Qt Design Studio

Linking Style and Syntax (R45-R50)

These rules cover how to write links in Qt documentation. Links connect documentation pages and enable navigation. For detailed diagnostics and link resolution debugging, see the QDoc Manual.

Rule Summary Sources Notes
R45 Basic link syntax QDoc Manual 
\l{target}
, 
\l{target}{text}
, 
\l[QML]{target}
R46 Link vs code formatting Qt Doc Team Use 
\l{}
for documented/public APIs; 
\c{}
for undocumented/internal
R47 Section links within type docs Qt Doc Team Use 
TypeName#Section Title
NOT 
page.html#anchor
R48 External page links QDoc Manual 
\externalpage
with 
\title
must match exactly
R49 QML cross-module links QDoc Manual Use 
::
separator: 
{QtQuick.Controls::ToolTip}
R50 QML value type case Qt Doc Team Value types use camelCase: 
geoCoordinate
not 
GeoCoordinate

R47 Detail: Section Links

When linking to a section within a C++ class or QML type documentation page, use the 

TypeName#Section Title

syntax: 

✅ \l{QColor#The HSV Color Model}
✅ \l{ListView#Reusing Items}
❌ \l{qcolor.html#the-hsv-color-model}

The 

page.html#anchor

syntax only works for explicit 

\page

pages, not auto-generated type pages.

R46 Detail: Link vs Code Formatting

Situation Use Example
Documented public API 
\l{}
 
\l{QWidget::show()}
Internal/private class 
\c{}
 
\c{QWidgetPrivate::init()}
Private header type 
\c{}
 
\c{QPlatformWindow}
External URL 
\l{}
with 
\externalpage
 
\l{CMake Documentation}

R50 Detail: QML Value Type Case

QML value types use camelCase (lowercase first letter). Object types use PascalCase. 

// Value types (camelCase):
\l{geoCoordinate::latitude}
\l{webEngineCertificateError::defer()}

// Object types (PascalCase):
\l{ListView::delegate}
\l{WebEngineView::url}

Enforcement Levels

Rules have different enforcement levels. Understanding these helps prioritize compliance efforts.

Level Meaning Examples
CI-enforced Checked automatically by CI; will fail builds R40 (80-column)
Required Must be followed; causes warnings or broken docs R14 (mandatory \brief), R41 (\sa targets)
Recommended Should be followed; not strictly enforced R39 (no space before brace)

Notes

  • When sources conflict, follow hierarchy: Qt Writing Guidelines → QUIP 25 → C++/QML Doc Style → MS Style Guide
  • QDoc Manual is authoritative for syntax only, not style
  • \brief is mandatory only for classes, QML types, properties, and examples
  • \brief is recommended (not mandatory) for functions, signals, enums, and methods
Retrieved from "https://wiki.qt.io/index.php?title=Qt_Documentation_Rules&oldid=45635"