Jump to content

Qt Documentation Rules: Difference between revisions

From Qt Wiki
Newer edit →
VisualWikitext
A set of rules used by internal editing tools.
 
No edit summary
Line 1: Line 1:
= Qt Documentation Style Rules Quick Reference =


= 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.
This page provides a consolidated reference of language and style rules for Qt documentation, with citations to their authoritative sources.
'''Note:''' These rules are '''prescriptive''' for new and updated documentation. Existing Qt documentation may not fully comply with all rules.


== Sources ==
== Sources ==
{| class="wikitable"
! ID !! Source !! URL
|-
| S1 || Qt Writing Guidelines || https://wiki.qt.io/Qt_Writing_Guidelines
|-
| S2 || QUIP 25 - Documentation Writing Style || https://code.qt.io/cgit/meta/quips.git/plain/quip-0025-Documentation-Writing-Style.rst
|-
| S3 || C++ Documentation Style || https://wiki.qt.io/C%2B%2B_Documentation_Style
|-
| S4 || QML Documentation Style || https://wiki.qt.io/QML_Documentation_Style
|-
| S5 || Qt Examples Guidelines || https://wiki.qt.io/Qt_Examples_Guidelines
|-
| S6 || Writing Example Documentation and Tutorials || https://wiki.qt.io/Writing_Example_Documentation_and_Tutorials
|-
| S7 || Qt Terms and Concepts || https://wiki.qt.io/Qt_Terms_and_Concepts
|-
| S8 || QDoc Style Guidelines || https://wiki.qt.io/QDoc_Style_Guidelines
|-
| S9 || Microsoft Writing Style Guide || https://learn.microsoft.com/en-us/style-guide/welcome/
|-
| S10 || QDoc Manual || https://doc.qt.io/qt-6/qdoc-index.html
|}
== API Documentation Requirements Matrix ==
This matrix shows mandatory vs recommended elements by documentation type (from S3, S4):
{| class="wikitable"
{| class="wikitable"
!ID
! Element !! \brief !! \since !! \inmodule / \inqmlmodule !! Other Requirements
!Source
!URL
|-
|-
|S1
| '''\class''' || '''MANDATORY''' || '''MANDATORY''' || '''MANDATORY''' || —
|Qt Writing Guidelines
|https://wiki.qt.io/Qt_Writing_Guidelines
|-
|-
|S2
| '''\qmltype''' || '''MANDATORY''' || '''MANDATORY''' || '''MANDATORY''' || —
|QUIP 25 - Documentation Writing Style
|https://code.qt.io/cgit/meta/quips.git/plain/quip-0025-Documentation-Writing-Style.rst
|-
|-
|S3
| '''\property''' || '''MANDATORY''' || '''MANDATORY''' || — || —
|C++ Documentation Style
|https://wiki.qt.io/C%2B%2B_Documentation_Style
|-
|-
|S4
| '''\qmlproperty''' || '''MANDATORY''' || Recommended || — || —
|QML Documentation Style
|https://wiki.qt.io/QML_Documentation_Style
|-
|-
|S5
| '''\fn''' (function) || Recommended || '''MANDATORY''' || — || <code>\a</code> params, <code>\c</code> values
|Qt Examples Guidelines
|https://wiki.qt.io/Qt_Examples_Guidelines
|-
|-
|S6
| '''\qmlmethod''' || Recommended || Recommended || — || <code>\a</code> params
|Writing Example Documentation and Tutorials
|https://wiki.qt.io/Writing_Example_Documentation_and_Tutorials
|-
|-
|S7
| '''\fn''' (signal) || Recommended || Recommended || — || —
|Qt Terms and Concepts
|https://wiki.qt.io/Qt_Terms_and_Concepts
|-
|-
|S8
| '''\qmlsignal''' || Recommended || Recommended || — || —
|QDoc Style Guidelines
|https://wiki.qt.io/QDoc_Style_Guidelines
|-
|-
|S9
| '''\enum''' || Recommended || Recommended || — || <code>\value</code> for each value
|Microsoft Writing Style Guide
|https://learn.microsoft.com/en-us/style-guide/welcome/
|-
|-
|S10
| '''\example''' || '''MANDATORY''' || — || — || <code>\title</code>, <code>\examplecategory</code>
|QDoc Manual
|https://doc.qt.io/qt-6/qdoc-index.html
|}
|}


== Core Principles (R1-R10) ==
== Core Principles (R1-R10) ==
{| class="wikitable"
{| class="wikitable"
!Rule
! Rule !! Summary !! Sources !! Notes
!Summary
!Sources
!Notes
|-
|-
|'''R1'''
| '''R1''' || '''Use active voice''' || S2, S1, S9 || Passive acceptable when actor unknown. "The item ignores events" not "Events are ignored by the item"
|'''Use active voice'''
|S2, S1, S9
|Passive acceptable when actor unknown. "The item ignores events" not "Events are ignored by the item"
|-
|-
|'''R2'''
| '''R2''' || '''Be clear and concise''' || S2, S9 || Aim for ≤20 words per sentence. "To" not "In order to"
|'''Be clear and concise'''
|S2, S9
|Aim for ≤20 words per sentence. "To" not "In order to"
|-
|-
|'''R3'''
| '''R3''' || '''Use correct terminology''' || S2, S1, S7 || Use "widget" not "control", "type" not "component", "developer" not "programmer"
|'''Use correct terminology'''
|S2, S1, S7
|Use "widget" not "control", "type" not "component", "developer" not "programmer"
|-
|-
|'''R4'''
| '''R4''' || '''Use present tense''' || S2, S1, S9 || "Returns true" not "Will return true"
|'''Use present tense'''
|S2, S1, S9
|"Returns true" not "Will return true"
|-
|-
|'''R5'''
| '''R5''' || '''Use imperative mood for instructions''' || S9, S3, S4 || Briefs: "Returns the value." Descriptions: "This property holds..."
|'''Use imperative mood for instructions'''
|S9, S3, S4
|Briefs: "Returns the value." Descriptions: "This property holds..."
|-
|-
|'''R6'''
| '''R6''' || '''Use "you" for user instructions''' || S2, S1, S9 || In guides/tutorials and tools docs. Not in API reference docs.
|'''Use "you" for user instructions'''
|S2, S1, S9
|In guides/tutorials only. Not in API docs.
|-
|-
|'''R7'''
| '''R7''' || '''Avoid jargon and Latin terms''' || S2, S1, S9 || "for example" not "e.g.", "that is" not "i.e.", "through" not "via"
|'''Avoid jargon and Latin terms'''
|S2, S1, S9
|"for example" not "e.g.", "that is" not "i.e.", "through" not "via"
|-
|-
|'''R8'''
| '''R8''' || '''Be consistent''' || S9 || Same word for same concept throughout
|'''Be consistent'''
|S9
|Same word for same concept throughout
|-
|-
|'''R9'''
| '''R9''' || '''Use parallel structure''' || S9 || List items use same grammatical form
|'''Use parallel structure'''
|S9
|List items use same grammatical form
|-
|-
|'''R10'''
| '''R10''' || '''Avoid ambiguous pronouns''' || S2, S9 || Repeat noun when "it" or "this" is unclear
|'''Avoid ambiguous pronouns'''
|S2, S9
|Repeat noun when "it" or "this" is unclear
|}
|}


== Grammar Rules (R11-R13) ==
== Grammar Rules (R11-R13) ==
{| class="wikitable"
{| class="wikitable"
!Rule
! Rule !! Summary !! Sources !! Notes
!Summary
!Sources
!Notes
|-
|-
|'''R11'''
| '''R11''' || '''Use serial (Oxford) comma''' || S2, S1 || "name, value, and type" not "name, value and type"
|'''Use serial (Oxford) comma'''
|S2, S1
|"name, value, and type" not "name, value and type"
|-
|-
|'''R12'''
| '''R12''' || '''Use sentence-case for titles''' || S1, S2, S9 || "Getting started with Qt Quick" not "Getting Started With Qt Quick"
|'''Use sentence-case for titles'''
|S1, S2, S9
|"Getting started with Qt Quick" not "Getting Started With Qt Quick"
|-
|-
|'''R13'''
| '''R13''' || '''Numbers: spell out 1-9''' || S2 || Numerals for 10+, dimensions, versions, code values
|'''Numbers: spell out 1-9'''
|S2
|Numerals for 10+, dimensions, versions, code values
|}
|}


== API Documentation (R14-R19) ==
== API Documentation (R14-R19) ==
{| class="wikitable"
{| class="wikitable"
!Rule
! Rule !! Summary !! Sources !! Notes
!Summary
!Sources
!Notes
|-
|-
|'''R14'''
| '''R14''' || '''\brief scope''' || S3, S4, S10 || '''MANDATORY''' for: \class, \qmltype, \property, \qmlproperty, \example, \page. '''Recommended''' for: \fn, \qmlmethod, \qmlsignal, \enum
|'''\brief is mandatory'''
|S3, S4, S10
|QDoc generates warnings if brief is empty
|-
|-
|'''R15'''
| '''R15''' || '''Briefs end with period''' || S3, S4 || Applies to all briefs that are provided
|'''All briefs end with period'''
|S3, S4
|Required punctuation
|-
|-
|'''R16'''
| '''R16''' || '''Class/Type documentation''' || S3, S4, S10 || Requires: \class/\qmltype, \brief, \inmodule/\inqmlmodule, \since
|'''Class documentation requirements'''
|S3, S10
|Requires: \class, \brief, \inmodule, \since. Document in .cpp files.
|-
|-
|'''R17'''
| '''R17''' || '''Function brief patterns''' || S3, S4 || Start with verb: "Returns...", "Sets...", "Constructs...". Brief recommended, not mandatory.
|'''Function briefs start with verb'''
|S3, S4
|"Returns...", "Sets...", "Constructs...", "Destroys..."
|-
|-
|'''R18'''
| '''R18''' || '''Property brief patterns''' || S3, S4 || "This property holds...". Brief is '''mandatory''' for properties.
|'''Property brief patterns'''
|S3, S4
|"This property holds...", "This property describes..."
|-
|-
|'''R19'''
| '''R19''' || '''Signal brief patterns''' || S3, S4 || "This signal is emitted when...". Brief recommended, not mandatory.
|'''Signal brief patterns'''
|S3, S4
|"This signal is emitted when...", "Emitted when..."
|}
|}


== Example Documentation (R20-R23) ==
== Example Documentation (R20-R23) ==
{| class="wikitable"
{| class="wikitable"
!Rule
! Rule !! Summary !! Sources !! Notes
!Summary
!Sources
!Notes
|-
|-
|'''R20'''
| '''R20''' || '''11 mandatory elements''' || S6 || Title, \example, \brief, \examplecategory, image, overview, running instructions, platform notes, main content, references, licenses
|'''11 mandatory elements'''
|S6
|Title, \example, \brief, \examplecategory, image, overview, running instructions, platform notes, main content, references, licenses
|-
|-
|'''R21'''
| '''R21''' || '''Zero warnings''' || S5 || C++ compiler and qmllint must produce no warnings
|'''Zero warnings'''
|S5
|C++ compiler and qmllint must produce no warnings
|-
|-
|'''R22'''
| '''R22''' || '''Screenshot specs''' || S5 || Minimum 440×320 pixels, icons 64×64, high DPI, WebP format
|'''Screenshot specs'''
|S5
|Minimum 440×320 pixels, icons 64×64, high DPI
|-
|-
|'''R23'''
| '''R23''' || '''Title guidelines''' || S5, S6 || Don't repeat "Example" or module name in title
|'''Title guidelines'''
|S5, S6
|Don't repeat "Example" or module name in title
|}
|}


== Alt Text (R24-R27) ==
== Alt Text (R24-R27) ==
{| class="wikitable"
{| class="wikitable"
!Rule
! Rule !! Summary !! Sources !! Notes
!Summary
!Sources
!Notes
|-
|-
|'''R24'''
| '''R24''' || '''Format: capital letter, no period''' || S8, QUIP 21 || {Window with toolbar and buttons}
|'''Format: capital letter, no period'''
|S8, QUIP 21
|{Window with toolbar and buttons}
|-
|-
|'''R25'''
| '''R25''' || '''Priority order''' || S8 || 1. Visible text/labels 2. Context/purpose 3. Visual description
|'''Priority order'''
|S8
|1. Visible text/labels 2. Context/purpose 3. Visual description
|-
|-
|'''R26'''
| '''R26''' || '''Use generic UI terms''' || S8 || "button" not "Button", "dialog" not "Dialog"
|'''Use generic UI terms'''
|S8
|"button" not "Button", "dialog" not "Dialog"
|-
|-
|'''R27'''
| '''R27''' || '''Use descriptive phrases''' || S8 || Noun phrases, not full sentences
|'''Use descriptive phrases'''
|S8
|Noun phrases, not full sentences
|}
|}


== Writing Contexts (R28-R29) ==
== Writing Contexts (R28-R29) ==
{| class="wikitable"
{| class="wikitable"
!Rule
! Rule !! Summary !! Sources !! Notes
!Summary
!Sources
!Notes
|-
|-
|'''R28'''
| '''R28''' || '''API documentation style''' || S3, S4 || Present tense, imperative briefs, indicative descriptions, no "you"
|'''API documentation style'''
|S3, S4
|Present tense, imperative briefs, indicative descriptions, no "you"
|-
|-
|'''R29'''
| '''R28b''' || '''Tools documentation style''' || S1 || Present tense, "you" acceptable, UI elements in bold, menu paths with >
|'''User guide/tutorial style'''
|-
|S1, S6
| '''R29''' || '''User guide/tutorial style''' || S1, S6 || Use "you", explain concepts, less jargon
|Use "you", explain concepts, less jargon
|}
|}


== Common Mistakes (R30-R37) ==
== Common Mistakes (R30-R37) ==
{| class="wikitable"
{| class="wikitable"
!Rule
! Rule !! Mistake !! Correction !! Cross-ref
!Mistake
!Correction
!Cross-ref
|-
|-
|'''R30'''
| '''R30''' || Passive voice || Use active voice || R1
|Passive voice
|Use active voice
|R1
|-
|-
|'''R31'''
| '''R31''' || Future tense || Use present tense || R4
|Future tense
|Use present tense
|R4
|-
|-
|'''R32'''
| '''R32''' || Wordy phrases || Be concise || R2
|Wordy phrases
|Be concise
|R2
|-
|-
|'''R33'''
| '''R33''' || Ambiguous "this" || Be specific || R10
|Ambiguous "this"
|Be specific
|R10
|-
|-
|'''R34'''
| '''R34''' || Inconsistent terms || Pick one term || R8
|Inconsistent terms
|Pick one term
|R8
|-
|-
|'''R35'''
| '''R35''' || Missing \brief on class/type/property || Add \brief || R14
|Missing \brief
|Always include
|R14
|-
|-
|'''R36'''
| '''R36''' || Brief without period || Add period || R15
|Brief without period
|Add period
|R15
|-
|-
|'''R37'''
| '''R37''' || "Neutral voice" || Use "imperative mood" or "indicative mood" || S2
|"Neutral voice"
|Use "imperative mood" or "indicative mood"
|S2
|}
|}


Line 294: Line 180:


=== Latin Terms (Always Avoid) ===
=== Latin Terms (Always Avoid) ===
{| class="wikitable"
{| class="wikitable"
!Instead of
! Instead of !! Use !! Source
!Use
!Source
|-
|-
|e.g.
| e.g. || for example, such as, like || S9
|for example, such as, like
|S9
|-
|-
|i.e.
| i.e. || that is || S9
|that is
|S9
|-
|-
|etc.
| etc. || (be specific, or use "such as" + examples) || S9
|(be specific, or use "such as" + examples)
|S9
|-
|-
|via
| via || through, using, with, by || S2, S9
|through, using, with, by
|S2, S9
|-
|-
|per
| per || according to, for each || —
|according to, for each
|—
|-
|-
|versus, vs.
| versus, vs. || compared to, or, against || —
|compared to, or, against
|—
|}
|}


=== Verbose Phrases ===
=== Verbose Phrases ===
{| class="wikitable"
{| class="wikitable"
!Instead of
! Instead of !! Use !! Source
!Use
!Source
|-
|-
|In order to
| In order to || To || S2, S9
|To
|S2, S9
|-
|-
|It is possible to
| It is possible to || You can / Can || S2
|You can / Can
|S2
|-
|-
|Make use of
| Make use of || Use || S9
|Use
|S9
|-
|-
|At this point in time
| At this point in time || Now || —
|Now
|—
|-
|-
|Due to the fact that
| Due to the fact that || Because || —
|Because
|—
|-
|-
|Is able to
| Is able to || Can || —
|Can
|—
|}
|}


=== Hedging Words (Avoid) ===
=== Hedging Words (Avoid) ===
{| class="wikitable"
{| class="wikitable"
!Avoid
! Avoid !! Reason !! Source
!Reason
!Source
|-
|-
|simply, just
| simply, just || Implies task is trivial || S2
|Implies task is trivial
|S2
|-
|-
|obviously, clearly
| obviously, clearly || Assumes reader knowledge || S2
|Assumes reader knowledge
|S2
|-
|-
|easily
| easily || May not be easy for reader || S2
|May not be easy for reader
|S2
|-
|-
|please
| please || Use only for inconvenient requests || S2
|Use only for inconvenient requests
|S2
|}
|}


=== Terminology ===
=== Terminology ===
{| class="wikitable"
{| class="wikitable"
!Instead of
! Instead of !! Use !! Source
!Use
!Source
|-
|-
|programmer
| programmer || developer || S2
|developer
|S2
|-
|-
|since, as (for causation)
| since, as (for causation) || because || S2, S9
|because
|S2, S9
|-
|-
|utilize
| utilize || use || S9
|use
|S9
|}
|}


== QDoc Formatting (R39-R41) ==
== QDoc Formatting (R39-R41) ==
{| class="wikitable"
{| class="wikitable"
!Rule
! Rule !! Summary !! Sources !! Notes
!Summary
!Sources
!Notes
|-
|-
|'''R39'''
| '''R39''' || '''No space before curly brace''' || S8 || <code>\l{QWidget}</code> not <code>\l {QWidget}</code>. Note: QDoc Manual examples show spaces, but S8 wiki takes precedence.
|'''No space before curly brace'''
|S8
|<code>\l{QWidget}</code>not<code>\l {QWidget}</code>. Note: QDoc Manual examples show spaces, but S8 wiki takes precedence.
|-
|-
|'''R40'''
| '''R40''' || '''80-column line length''' || Qt Coding Style, S8 || For documentation comments and .qdoc files
|'''80-column line length'''
|Qt Coding Style, S8
|For documentation comments and .qdoc files
|-
|-
|'''R41'''
| '''R41''' || '''\sa targets must match page titles''' || Qt Doc Team practice || Verify targets resolve to actual pages
|'''\sa targets must match page titles'''
|}
|Qt Doc Team practice
 
|Verify targets resolve to actual pages
== UI and Tools Documentation (R42-R44) ==
 
{| class="wikitable"
! Rule !! Summary !! Sources !! Notes
|-
| '''R42''' || '''UI element markup''' || S1, Qt Creator docs || Bold for UI elements: '''File''' > '''New Project'''. In QDoc: <code>\uicontrol{element}</code>
|-
| '''R43''' || '''Keyboard shortcut formatting''' || Qt Creator docs || <code>Ctrl+B</code>, sequential: <code>Ctrl+K, Ctrl+D</code>, platform: <code>Ctrl+O</code> (<code>Cmd+O</code> on macOS)
|-
| '''R44''' || '''Menu path formatting''' || Qt Creator docs || Go to '''File''' > '''New Project''' > '''Qt Quick Application'''
|}
|}


== Qt Product and Module Names (R3 Detail) ==
== Qt Product and Module Names (R3 Detail) ==
Per [[Qt Terms and Concepts|S7]]:
 
Per [[Qt_Terms_and_Concepts|S7]]:
 
{| class="wikitable"
{| class="wikitable"
!Correct
! Correct !! Incorrect !! Notes
!Incorrect
!Notes
|-
|-
|Qt GUI
| Qt GUI || Qt Gui, Qt gui || Acronyms all caps
|Qt Gui, Qt gui
|Acronyms all caps
|-
|-
|Qt SQL
| Qt SQL || Qt Sql || Acronym all caps
|Qt Sql
|Acronym all caps
|-
|-
|Qt SVG
| Qt SVG || Qt Svg || Acronym all caps
|Qt Svg
|Acronym all caps
|-
|-
|Qt XML
| Qt XML || Qt Xml || Acronym all caps
|Qt Xml
|Acronym all caps
|-
|-
|Qt Quick
| Qt Quick || QtQuick (in prose) || Two words in prose
|QtQuick (in prose)
|Two words in prose
|-
|-
|Qt Add-Ons
| Qt Add-Ons || Qt Addon, Qt Addons || Hyphenated
|Qt Addon, Qt Addons
|Hyphenated
|-
|-
|Qt D-Bus
| Qt D-Bus || Qt DBus, Qt DBUS || Hyphenated
|Qt DBus, Qt DBUS
|Hyphenated
|-
|-
|Qt Creator
| Qt Creator || QtCreator || Two words
|QtCreator
|Two words
|-
|-
|QDoc
| QDoc || Qdoc, qdoc || CamelCase
|Qdoc, qdoc
|CamelCase
|}
|}


== Compound Words (R3 Detail) ==
== Compound Words (R3 Detail) ==
{| class="wikitable"
{| class="wikitable"
!Correct
! Correct !! Incorrect
!Incorrect
|-
| checkbox || check box
|-
| filename || file name
|-
| namespace || name space
|-
| runtime || run time, run-time
|-
|-
|checkbox
| framerate || frame rate
|check box
|-
|-
|filename
| toolchain || tool chain
|file name
|-
|-
|namespace
| codebase || code base
|name space
|-
|-
|runtime
| standalone || stand-alone
|run time, run-time
|}
 
== Tools-Specific Terminology (R3 Detail) ==
 
{| class="wikitable"
! Term !! Correct Usage !! Context
|-
|-
|framerate
| kit || kit (not "configuration set") || Qt Creator
|frame rate
|-
|-
|toolchain
| toolchain || toolchain (not "tool chain") || All
|tool chain
|-
|-
|codebase
| build system || build system (not "buildsystem") || All
|code base
|-
|-
|standalone
| mode || Edit mode, Design mode, Debug mode || Qt Creator, Qt Design Studio
|stand-alone
|}
|}


== Notes ==
== Notes ==


* These rules are '''prescriptive''' for new and updated documentation
* Existing Qt documentation may not fully comply with all rules
* When sources conflict, follow hierarchy: S1 → S2 → S3/S4 → S9
* When sources conflict, follow hierarchy: S1 → S2 → S3/S4 → S9
* QDoc Manual (S10) is authoritative for '''syntax''' only, not style
* QDoc Manual (S10) 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
[[Category:Documentation]]

Revision as of 12: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.

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

Sources

ID Source URL
S1 Qt Writing Guidelines https://wiki.qt.io/Qt_Writing_Guidelines
S2 QUIP 25 - Documentation Writing Style https://code.qt.io/cgit/meta/quips.git/plain/quip-0025-Documentation-Writing-Style.rst
S3 C++ Documentation Style https://wiki.qt.io/C%2B%2B_Documentation_Style
S4 QML Documentation Style https://wiki.qt.io/QML_Documentation_Style
S5 Qt Examples Guidelines https://wiki.qt.io/Qt_Examples_Guidelines
S6 Writing Example Documentation and Tutorials https://wiki.qt.io/Writing_Example_Documentation_and_Tutorials
S7 Qt Terms and Concepts https://wiki.qt.io/Qt_Terms_and_Concepts
S8 QDoc Style Guidelines https://wiki.qt.io/QDoc_Style_Guidelines
S9 Microsoft Writing Style Guide https://learn.microsoft.com/en-us/style-guide/welcome/
S10 QDoc Manual https://doc.qt.io/qt-6/qdoc-index.html

API Documentation Requirements Matrix

This matrix shows mandatory vs recommended elements by documentation type (from S3, S4):

Element \brief \since \inmodule / \inqmlmodule Other Requirements
\class MANDATORY MANDATORY MANDATORY —
\qmltype MANDATORY MANDATORY MANDATORY —
\property MANDATORY MANDATORY — —
\qmlproperty MANDATORY Recommended — —
\fn (function) Recommended MANDATORY — 
\a
params, 
\c
values
\qmlmethod Recommended Recommended — 
\a
params
\fn (signal) Recommended Recommended — —
\qmlsignal Recommended Recommended — —
\enum Recommended Recommended — 
\value
for each value
\example MANDATORY — — 
\title
, 
\examplecategory

Core Principles (R1-R10)

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

Grammar Rules (R11-R13)

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

API Documentation (R14-R19)

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

Example Documentation (R20-R23)

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

Alt Text (R24-R27)

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

Writing Contexts (R28-R29)

Rule Summary Sources Notes
R28 API documentation style S3, S4 Present tense, imperative briefs, indicative descriptions, no "you"
R28b Tools documentation style S1 Present tense, "you" acceptable, UI elements in bold, menu paths with >
R29 User guide/tutorial style S1, S6 Use "you", explain concepts, less jargon

Common Mistakes (R30-R37)

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" S2

Common Substitutions (R38)

Latin Terms (Always Avoid)

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

Verbose Phrases

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

Hedging Words (Avoid)

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

Terminology

Instead of Use Source
programmer developer S2
since, as (for causation) because S2, S9
utilize use S9

QDoc Formatting (R39-R41)

Rule Summary Sources Notes
R39 No space before curly brace S8 
\l{QWidget}
not 
\l {QWidget}
. Note: QDoc Manual examples show spaces, but S8 wiki takes precedence.
R40 80-column line length Qt Coding Style, S8 For documentation comments and .qdoc files
R41 \sa targets must match page titles Qt Doc Team practice Verify targets resolve to actual pages

UI and Tools Documentation (R42-R44)

Rule Summary Sources Notes
R42 UI element markup S1, 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)

Per 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)

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)

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

Notes

  • When sources conflict, follow hierarchy: S1 → S2 → S3/S4 → S9
  • QDoc Manual (S10) 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=45632"