Jump to content

Qt Documentation Rules: Difference between revisions

From Qt Wiki
← Older editNewer edit →
VisualWikitext
No edit summary
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. 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.
'''Note:''' These rules are '''prescriptive''' for new and updated documentation. Existing Qt documentation may not fully comply with all rules.


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


{| class="wikitable"
{| class="wikitable"
! ID !! Source !! URL
! ID !! Source !! URL !! Purpose
|-
|-
| S1 || Qt Writing Guidelines || https://wiki.qt.io/Qt_Writing_Guidelines
| 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
| 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
| 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
| 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
| 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
| 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
| 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
| 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/
| 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
| S10 || QDoc Manual || https://doc.qt.io/qt-6/qdoc-index.html || QDoc command syntax (not a style authority)
|}
|}


== API Documentation Requirements Matrix ==
== API Documentation Requirements ==


This matrix shows mandatory vs recommended elements by documentation type (from S3, S4):
Requirements for documenting C++ and QML APIs are defined in the official style guides:


{| class="wikitable"
* '''C++ APIs:''' See [[C++ Documentation Style]] for class, function, property, and signal documentation requirements
! Element !! \brief !! \since !! \inmodule / \inqmlmodule !! Other 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
| '''\class''' || '''MANDATORY''' || '''MANDATORY''' || '''MANDATORY''' || —
 
|-
'''Key points:'''
| '''\qmltype''' || '''MANDATORY''' || '''MANDATORY''' || '''MANDATORY''' || —
* Classes and QML types require <code>\brief</code>, <code>\since</code>, and <code>\inmodule</code>/<code>\inqmlmodule</code>
|-
* Properties require <code>\brief</code>
| '''\property''' || '''MANDATORY''' || '''MANDATORY''' || — || —
* Functions and methods should start with an action verb ("Returns...", "Sets...")
|-
| '''\qmlproperty''' || '''MANDATORY''' || Recommended || — || —
|-
| '''\fn''' (function) || Recommended || '''MANDATORY''' || — || <code>\a</code> params, <code>\c</code> values
|-
| '''\qmlmethod''' || Recommended || Recommended || — || <code>\a</code> params
|-
| '''\fn''' (signal) || Recommended || Recommended || — || —
|-
| '''\qmlsignal''' || Recommended || Recommended || — || —
|-
| '''\enum''' || Recommended || Recommended || — || <code>\value</code> for each value
|-
| '''\example''' || '''MANDATORY''' || — || — || <code>\title</code>, <code>\examplecategory</code>
|}


== Core Principles (R1-R10) ==
== 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).


{| class="wikitable"
{| class="wikitable"
! Rule !! Summary !! Sources !! Notes
! 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"
| '''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''' || S2, S9 || Aim for ≤20 words per sentence. "To" not "In order to"
| '''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''' || S2, S1, S7 || Use "widget" not "control", "type" not "component", "developer" not "programmer"
| '''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''' || S2, S1, S9 || "Returns true" not "Will return true"
| '''R4''' || '''Use present tense''' || QUIP 25, Qt Writing Guidelines, MS Style Guide || "Returns true" not "Will return true"
|-
|-
| '''R5''' || '''Use imperative mood for instructions''' || S9, S3, S4 || Briefs: "Returns the value." Descriptions: "This property holds..."
| '''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''' || S2, S1, S9 || In guides/tutorials and tools docs. Not in API reference docs.
| '''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''' || S2, S1, S9 || "for example" not "e.g.", "that is" not "i.e.", "through" not "via"
| '''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''' || S9 || Same word for same concept throughout
| '''R8''' || '''Be consistent''' || MS Style Guide || Same word for same concept throughout
|-
|-
| '''R9''' || '''Use parallel structure''' || S9 || List items use same grammatical form
| '''R9''' || '''Use parallel structure''' || MS Style Guide || List items use same grammatical form
|-
|-
| '''R10''' || '''Avoid ambiguous pronouns''' || S2, S9 || 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
|}
|}


== Grammar Rules (R11-R13) ==
== 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).


{| class="wikitable"
{| class="wikitable"
! Rule !! Summary !! Sources !! Notes
! Rule !! Summary !! Sources !! Notes
|-
|-
| '''R11''' || '''Use serial (Oxford) comma''' || S2, S1 || "name, value, and type" not "name, value and type"
| '''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''' || S1, S2, S9 || "Getting started with Qt Quick" not "Getting Started With Qt Quick"
| '''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''' || S2 || Numerals for 10+, dimensions, versions, code values
| '''R13''' || '''Numbers: spell out 1-9''' || QUIP 25 || Numerals for 10+, dimensions, versions, code values
|}
|}


== API Documentation (R14-R19) ==
== 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).


{| class="wikitable"
{| class="wikitable"
! Rule !! Summary !! Sources !! Notes
! Rule !! Summary !! Sources !! Notes
|-
|-
| '''R14''' || '''\brief scope''' || S3, S4, S10 || '''MANDATORY''' for: \class, \qmltype, \property, \qmlproperty, \example, \page. '''Recommended''' for: \fn, \qmlmethod, \qmlsignal, \enum
| '''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''' || S3, S4 || Applies to all briefs that are provided
| '''R15''' || '''Briefs end with period''' || C++ Doc Style, QML Doc Style || Applies to all briefs that are provided
|-
|-
| '''R16''' || '''Class/Type documentation''' || S3, S4, S10 || Requires: \class/\qmltype, \brief, \inmodule/\inqmlmodule, \since
| '''R16''' || '''Class/Type documentation''' || C++ Doc Style, QML Doc Style, QDoc Manual || Requires: \class/\qmltype, \brief, \inmodule/\inqmlmodule, \since
|-
|-
| '''R17''' || '''Function brief patterns''' || S3, S4 || Start with verb: "Returns...", "Sets...", "Constructs...". Brief recommended, not mandatory.
| '''R17''' || '''Function brief patterns''' || C++ Doc Style, QML Doc Style || Start with verb: "Returns...", "Sets...", "Constructs...". Brief recommended, not mandatory.
|-
|-
| '''R18''' || '''Property brief patterns''' || S3, S4 || "This property holds...". Brief is '''mandatory''' for properties.
| '''R18''' || '''Property brief patterns''' || C++ Doc Style, QML Doc Style || "This property holds...". Brief is '''mandatory''' for properties.
|-
|-
| '''R19''' || '''Signal brief patterns''' || S3, S4 || "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.
|}
|}


== Example Documentation (R20-R23) ==
== 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).


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


== Alt Text (R24-R27) ==
== 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.


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


== Writing Contexts (R28-R29) ==
== 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).


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


== Common Mistakes (R30-R37) ==
== 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.


{| class="wikitable"
{| class="wikitable"
Line 174: Line 175:
| '''R36''' || Brief without period || Add period || R15
| '''R36''' || Brief without period || Add period || R15
|-
|-
| '''R37''' || "Neutral voice" || Use "imperative mood" or "indicative mood" || S2
| '''R37''' || "Neutral voice" || Use "imperative mood" or "indicative mood" || QUIP 25
|}
|}


== Common Substitutions (R38) ==
== 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 Terms (Always Avoid) ===
Latin abbreviations are not universally understood. Replace them with plain English equivalents.


{| class="wikitable"
{| class="wikitable"
! Instead of !! Use !! Source
! Instead of !! Use !! Source
|-
|-
| e.g. || for example, such as, like || S9
| e.g. || for example, such as, like || MS Style Guide
|-
|-
| i.e. || that is || S9
| i.e. || that is || MS Style Guide
|-
|-
| etc. || (be specific, or use "such as" + examples) || S9
| etc. || (be specific, or use "such as" + examples) || MS Style Guide
|-
|-
| via || through, using, with, by || S2, S9
| via || through, using, with, by || QUIP 25, MS Style Guide
|-
|-
| per || according to, for each || —
| per || according to, for each || —
Line 198: Line 203:


=== Verbose Phrases ===
=== Verbose Phrases ===
Replace wordy phrases with concise alternatives to improve readability.


{| class="wikitable"
{| class="wikitable"
! Instead of !! Use !! Source
! Instead of !! Use !! Source
|-
|-
| In order to || To || S2, S9
| In order to || To || QUIP 25, MS Style Guide
|-
|-
| It is possible to || You can / Can || S2
| It is possible to || You can / Can || QUIP 25
|-
|-
| Make use of || Use || S9
| Make use of || Use || MS Style Guide
|-
|-
| At this point in time || Now || —
| At this point in time || Now || —
Line 216: Line 223:


=== Hedging Words (Avoid) ===
=== Hedging Words (Avoid) ===
These words can be condescending or assume reader knowledge. Avoid them in most contexts.


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


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


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


== QDoc Formatting (R39-R41) ==
== 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.


{| class="wikitable"
{| class="wikitable"
! Rule !! Summary !! Sources !! Notes
! Rule !! Summary !! Sources !! Enforcement
|-
|-
| '''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.
| '''R39''' || '''No space before curly brace''' || QDoc Style Guidelines || '''Recommended''' for compact text. <code>\l{QWidget}</code> preferred over <code>\l {QWidget}</code>. Not strictly enforced.
|-
|-
| '''R40''' || '''80-column line length''' || Qt Coding Style, S8 || For documentation comments and .qdoc files
| '''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 || Verify targets resolve to actual pages
| '''R41''' || '''\sa targets must match page titles''' || Qt Doc Team practice || '''Required.''' Verify targets resolve to actual pages.
|}
|}


== UI and Tools Documentation (R42-R44) ==
== 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.


{| class="wikitable"
{| class="wikitable"
! Rule !! Summary !! Sources !! Notes
! 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>
| '''R42''' || '''UI element markup''' || Qt Writing Guidelines, 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)
| '''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)
Line 267: Line 282:
== Qt Product and Module Names (R3 Detail) ==
== Qt Product and Module Names (R3 Detail) ==


Per [[Qt_Terms_and_Concepts|S7]]:
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).


{| class="wikitable"
{| class="wikitable"
Line 292: Line 307:


== Compound Words (R3 Detail) ==
== Compound Words (R3 Detail) ==
Qt documentation uses specific compound word conventions. Use these spellings consistently.


{| class="wikitable"
{| class="wikitable"
Line 314: Line 331:


== Tools-Specific Terminology (R3 Detail) ==
== Tools-Specific Terminology (R3 Detail) ==
Qt Creator and Qt Design Studio use specific terminology that should be used consistently in tools documentation.


{| class="wikitable"
{| class="wikitable"
Line 325: Line 344:
|-
|-
| mode || Edit mode, Design mode, Debug mode || Qt Creator, Qt Design Studio
| mode || Edit mode, Design mode, Debug mode || Qt Creator, Qt Design Studio
|}
== Enforcement Levels ==
Rules have different enforcement levels. Understanding these helps prioritize compliance efforts.
{| class="wikitable"
! 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 ==
== Notes ==


* When sources conflict, follow hierarchy: S1 → S2 → S3/S4 → S9
* When sources conflict, follow hierarchy: Qt Writing Guidelines → QUIP 25 → C++/QML Doc Style → MS Style Guide
* QDoc Manual (S10) is authoritative for '''syntax''' only, not style
* QDoc Manual is authoritative for '''syntax''' only, not style
* \brief is '''mandatory''' only for classes, QML types, properties, and examples
* \brief is '''mandatory''' only for classes, QML types, properties, and examples
* \brief is '''recommended''' (not mandatory) for functions, signals, enums, and methods
* \brief is '''recommended''' (not mandatory) for functions, signals, enums, and methods


[[Category:Documentation]]
[[Category:Documentation]]

Revision as of 13:04, 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

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.

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

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 —

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

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=45633"