Jump to content

Enumerated Qt Writing Guidelines

From Qt Wiki

Qt Documentation Style Guidelines Quick Reference

This page provides a quick reference for Qt documentation style guidelines. Guidelines are tagged with source references (S1-S10) for traceability.

Sources

Tier 1 - Qt Official Standards (Highest Authority)

ID Source URL Scope
S1 Qt Writing Guidelines link Primary coordination document
S2 QUIP 25 link Language, grammar, style
S3 C++ Documentation Style link C++ API patterns
S4 QML Documentation Style link QML API patterns
S5 Qt Examples Guidelines link Example code quality
S6 Writing Example Documentation link Example doc patterns
S7 Qt Terms and Concepts link Official terminology
S8 Qt Alt Text Style (internal) Alt text patterns

Tier 2 - Supplementary Reference

ID Source URL Scope
S9 Microsoft Style Guide link Used when Qt sources don't specify

Tool Reference (Syntax Only)

ID Source URL Scope
S10 QDoc Manual link Command syntax, not style authority

When sources conflict: S1 → S2 → S3/S4 → S9

Core Principles (R1-R10)

ID Guideline Example Source Citation
R1 Use active voice "Events will be ignored" → "The item ignores events" S2, S1 S2: "Use active voice whenever possible"; S1: "Use active voice, not passive"
R2 Be concise (≤20 words) "In order to enable" → "To enable" S2 S2: "Keep sentences concise (aim for 20 words or fewer)"
R3 Use correct terminology "developer" not "programmer" S2, S7 S2: "developer (not programmer)"; S7: Qt Terms and Concepts
R4 Use present tense "will return" → "returns" S2 S2: "Use present tense whenever possible"
R5 Imperative mood for instructions "Returns..." "Call this function..." S3, S4 S3: "Begins with action verbs (Constructs, Returns, Sets)"
R6 Use "you" for user instructions "You can configure..." S2, S1 S2: "as though you're speaking to the reader"; S1: "Use the pronoun you"
R7 Avoid Latin terms "e.g." → "for example" S2, S1 S2: "Don't use Latin abbreviations"; S1: "avoid latin abbreviations"
R8 Be consistent Same word for same concept S9 S9: Microsoft Style Guide consistency principles
R9 Use parallel structure List items share grammatical form S1, S9 S1: "Use the same tone or mode"; S9: Lists guidance
R10 Avoid ambiguous pronouns Repeat the noun when unclear S2 S2: "specify what 'this' and 'it' reference"

Grammar Guidelines (R11-R13)

ID Guideline Example Source Citation
R11 Serial (Oxford) comma "name, value, and type" S1 S1: "Use a serial comma, also known as the Oxford comma"
R12 Sentence-case for titles "Getting started with Qt Quick" S1 S1: "Write section titles in sentence-case"
R13 Numbers: spell out 1-9 Numerals for 10+, versions, dimensions S2 S2: "Spell out one through nine; use numerals for 10+"

API Documentation (R14-R19)

ID Guideline Source Citation
R14 
\brief
mandatory for classes, types, properties		 S3, S4 S3: "QDoc generates warnings if omitted"; S4: "Mandatory context commands: \brief"
R15 All briefs end with period S3, S4 S3: "complete sentence terminated with a period"; S4: "Terminate the brief description with a period"
R16 Class requires: 
\class
, 
\brief
, 
\inmodule
, 
\since
 S3 S3: "Must include \brief, \since, and \inmodule context commands"
R17 Function briefs start with verbs S3, S4 S3: "Begins with action verbs (Constructs, Destroys, Returns)"; S4: "Changes, Updates, Returns, Called"
R18 Property briefs: "This property holds..." S3, S4 S3/S4: "This property holds...", "This property describes..."
R19 Signal briefs: "This signal is emitted when..." S3, S4 S3: "This signal is emitted when..."; S4: "Emitted when...", "Triggered when..."

Example Documentation (R20-R23)

ID Guideline Source Citation
R20 11 mandatory elements S6 S6: title, example page, brief, category, image, overview, running instructions, platform notes, main body, references, licenses
R21 Zero warnings from compiler and qmllint S5 S5: "C++ code must compile with same compiler warning flags as Qt"; "Use qmllint for QML"
R22 Screenshots: minimum 440×320 pixels S5 S5: "Screen shots taken with high dpi resolution, minimum image size 440x320"
R23 Titles: avoid repeating "Example" S5, S6 S6: "simple and descriptive"; use "verb-focused language, typically ending in -ing"

Alt Text (R24-R27)

ID Guideline Example Source Citation
R24 Capital letter, no period 
{Window with toolbar}
 S1, S6 S1/S6: "Start capitalized and do not end with a period"
R25 Priority: visible text → context → visual S8 S8: Qt Alt Text Style priority order
R26 Generic UI terms, lowercase "button" not "Button" S8 S8: Generic UI terminology guidelines
R27 Descriptive noun phrases "Dialog for entering details" S8 S8: Phrase structure guidelines

Writing Contexts (R28-R29)

ID Context Style Source Citation
R28 API documentation Imperative briefs, indicative descriptions S3, S4 S3/S4: Brief patterns and documentation structure
R28b Tools documentation "you" acceptable, bold UI elements S1 S1: 
\uicontrol
for UI text; menu path formatting
R29 User guides/tutorials Use "you", explain concepts S2, S6 S2: "as though you're speaking to the reader"; S6: tutorial structure

Common Mistakes (R30-R37)

ID Mistake Fix Source
R30 Passive voice Use active (R1) S2, S1
R31 Future tense Use present (R4) S2
R32 Wordy phrases Be concise (R2) S2
R33 Ambiguous "this" Be specific (R10) S2
R34 Inconsistent terms Pick one (R8) S9
R35 Missing 
\brief
Add 
\brief
(R14)		 S3, S4
R36 No period in brief Add period (R15) S3, S4
R37 "Neutral voice" Use "imperative/indicative mood" S3, S4

Common Substitutions (R38)

Latin Terms (Always Avoid) - S2, S1

S2: "Don't use Latin abbreviations"; S1: "avoid latin abbreviations"

Instead of Use
e.g. for example, such as, like
i.e. that is
etc. (be specific, or use "such as" + examples)
via through, using, with, by

Verbose Phrases - S2

S2: "Keep sentences concise"

Instead of Use
In order to To
It is possible to You can / Can
Make use of Use
Due to the fact that Because

Terminology - S2

Instead of Use Citation
programmer developer S2: "developer (not programmer)"
since / as (causation) because S1: "Use because instead of since or as"

QDoc Formatting (R39-R41)

ID Guideline Source Citation
R39 Prefer no space before curly brace S10 S10: QDoc parser accepts both; no-space preferred for compactness
R40 80-column line length S1 Qt Coding Style: 80-column limit; CI-enforced
R41 
\sa
targets must match page titles		 S10 S10: Link resolution requires exact title match

UI and Tools Documentation (R42-R44)

ID Guideline Example Source Citation
R42 Bold UI elements 
\uicontrol{File}
 S1 S1: "use \uicontrol for UI text in bold"
R43 Keyboard shortcuts 
Ctrl+B
(
Cmd+B
on macOS)		 S1 Qt Creator/Design Studio conventions
R44 Menu paths with > Edit > Preferences S1 Qt Creator/Design Studio conventions

Linking Style and Syntax (R45-R50)

ID Guideline Example Source
R45 Basic link syntax 
\l{target}
, 
\l{target}{text}
 S10
R46 
\l{}
for public APIs; 
\c{}
for internal		 S10
R47 Section links: 
TypeName#Section
 
\l{QColor#The HSV Color Model}
 S10
R48 External links: 
\externalpage
with 
\title
 S10
R49 QML cross-module: use 
::
separator		 
\l{QtQuick.Controls::ToolTip}
 S10
R50 QML value types: camelCase 
\l{geoCoordinate::latitude}
 S10

QML Abstraction (R51-R51b)

ID Guideline Source Citation
R51 Use generic QML types in 
\qmlmethod
 S4 QML describes QML interface, not C++ implementation
R51b QML docs link to QML targets, not C++ S4 Exception: enums, architecture explanations

R51 Return Type Mapping

C++ Return Type QML Return Type 
QObject *
 
object
QVariant
 
var
QString
 
string

QList<...>
 
list

Structured Content (R52-R56)

ID Guideline Source Citation
R52 List length: 2-7 items S9 S9: Microsoft Style Guide lists guidance
R53 List punctuation: periods for complete sentences only S9 S9: Microsoft Style Guide lists guidance
R54 Introduce lists/tables with context S9 S9: Microsoft Style Guide lists/tables guidance
R55 Never leave table cells blank S9 S9: Microsoft Style Guide tables guidance
R56 Table headers must be specific S9 S9: Microsoft Style Guide tables guidance

Exceptions (R57)

ID Guideline Source
R57 Legal/boilerplate text exempt from style review Industry practice

Quick Checklist

  • Active voice (R1) - S2, S1
  • Present tense (R4) - S2
  • No Latin terms (R7, R38) - S2, S1
  • \brief
    ends with period (R14, R15) - S3, S4
  • \since
    for C++ APIs (R16) - S3
  • Lines ≤80 columns (R40) - S1
  • Link targets verified (R45-R50) - S10

Last updated: February 2026

Total guidelines: 58 (R1-R57, R28b, R51b)

Retrieved from "https://wiki.qt.io/index.php?title=Enumerated_Qt_Writing_Guidelines&oldid=45648"