Latest revision as of 12:19, 25 February 2026

Qt Documentation Style Rules Quick Reference

Note: This page is WORK IN PROGRESS, to test whether we can harmonize our guidelines. This is not official but it is based on the various Qt guidelines.

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:

C++ APIs: See C++ Documentation Style for class, function, property, and signal documentation requirements
QML APIs: See QML Documentation Style for QML type, property, method, and signal documentation requirements
Examples: See Writing Example Documentation and Tutorials for the 11 mandatory elements

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. API patterns typically don't require "you".
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 (guides)	One can configure the settings in the dialog.	You can configure the settings in the dialog.
R6 (API)	You must call this function to update.	Call this function to update the view.
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

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

// 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