Difference between revisions of "Writing Qt Documentation"

From Qt Wiki
Jump to: navigation, search
 
m (Added some detail around the use of links, and added some hyphenation for clarity in the existing text.)
 
(18 intermediate revisions by 10 users not shown)
Line 1: Line 1:
=Writing Qt Documentation=
+
[[Category:Writing Guidelines]]
  
 
This document contains some documentation style guidelines that have been used when documenting Qt over the past few years.
 
This document contains some documentation style guidelines that have been used when documenting Qt over the past few years.
  
It may be helpful to refer to the online [http://doc.qt.digia.com/qdoc qdoc manual] ''[doc.qt.digia.com]''.
+
It may be helpful to refer to the online [http://doc.qt.io/qt-5/qdoc-index.html qdoc manual].
  
See [[Building Qt Documentation|Building_Qt_Documentation]] for instructions on the usual way to build the Qt documentation.
+
See [[Building_Qt_Documentation]] for instructions on the usual way to build the Qt documentation.
  
See [[Troubleshooting-Qt-Documentation|Troubleshooting Qt Documentation]] for advice on what to look for if your documentation is not processed correctly by qdoc.
+
See [[Troubleshooting Qt Documentation]] for advice on what to look for if your documentation is not processed correctly by qdoc.
  
See [[:Category:Developing Qt::Documentation|Developing Qt Documentation]] ''[qt.io]'' for information about the documentation process.<br /> h2. <span class="caps">API</span> documentation
+
See [http://wiki.qt.io/Category:Developing_Qt::Documentation Developing Qt Documentation] for information about the documentation process.
  
 +
==API documentation==
 
==General==
 
==General==
  
* Write complete sentences for \value items in \enum lists.
+
*Write complete sentences for items in lists.
* Use only real <span class="caps">URL</span>s if absolutely necessary, otherwise use “[http://example.xn--com-9o0a. http://example.com”.] Use \externalpage documents to create fake pages for external documents that you can refer to by title.
+
*Use real URLs if absolutely necessary, otherwise use "http://example.com".  
* Indent using spaces, not tabs.
+
*When creating links to titles outside your project:
 +
**Use the '''\externalpage''' and '''\title''' commands in  your own externalpages.qdoc  file to create targets to use in body of text to improve source code readability and maintenance.
 +
**Check and re-use targets as defined in files in the "\Qt\Docs\'''applicable'''-'''Qt-version'''\global\externalsites" folder where possible to prevent duplication.
 +
*Indent using spaces, not tabs
 +
*Remove trailing spaces on a line
 +
*Wrap lines at 80 characters.
  
 
==Use of language==
 
==Use of language==
  
* Hyphenation is not normally needed nor used.
+
Qt uses the [https://docs.microsoft.com/en-us/style-guide/welcome/ Microsoft Writing Style Guide].
* Shorthand is discouraged.
+
 
** For example, “and” should be used in preference to &amp;” unless there is a very good reason.
+
*Hyphenation is not normally needed nor used.
* Each word in a title (either a page title or a section title) should start with an upper case letter, except for the [http://en.wikipedia.org/wiki/Preposition most common prepositions] ''[en.wikipedia.org]'' (of, to, in, for, with and on) and [http://en.wikipedia.org/wiki/Grammatical_conjunction coordinating conjunctions] ''[en.wikipedia.org]'' (for, and, nor, but, or, yet, and so).
+
*Shorthand is discouraged.
** For example, “Anchor Margins and Offsets” not “Anchor margins and offsets” (lower case is wrong) or “Anchor Margins And Offsets” (“and” should be lower case).
+
**For example, "and" should be used in preference to "&" unless there is a very good reason.
 +
 
 +
For more information, see the following links:
 +
 
 +
*https://docs.microsoft.com/en-us/style-guide/top-10-tips-style-voice
 +
*https://docs.microsoft.com/en-us/style-guide/developer-content/formatting-developer-text-elements
 +
 
 +
===Title case vs. sentence case===
 +
 
 +
Traditionally, title case is used for topic titles and section headings in Qt documentation. However, the Microsoft Writing Style Guide recommends sentence case. Therefore, you should '''follow the existing convention for current documentation'''. That usually means using title case, even for new topics added to the docs for a module (if title case is used for the existing topics).
 +
 
 +
For new documentation sets, such as docs for a new module or tool, you should adopt sentence case from the beginning.
 +
 
 +
====Using title case====
 +
 
 +
Each word in a title (either a page title or a section title) should start with an upper case letter, except for the [http://en.wikipedia.org/wiki/Preposition most common prepositions] (of, to, in, for, with and on) and [http://en.wikipedia.org/wiki/Grammatical_conjunction coordinating conjunctions] (for, and, nor, but, or, yet, and so).
 +
 
 +
For example, "Anchor Margins and Offsets" not "Anchor margins and offsets" (lower case is wrong) or "Anchor Margins And Offsets" ("and" should be lower case).
 +
 
 +
https://titlecaseconverter.com/ can be used to convert titles to title case.
  
 
===Overview/modules===
 
===Overview/modules===
  
* Shows/describes how classes in the module are used together.
+
*Shows/describes how classes in the module are used together.
* Describes the main concepts and features of groups of classes.
+
*Describes the main concepts and features of groups of classes.
  
 
===Class descriptions===
 
===Class descriptions===
  
* Brief overview
+
*Brief overview
* Start the main body of text with something like, “A &lt;plain language name&gt; is a…”
+
*Start the main body of text with something like, "A <plain language name> is a…"
* Alternative classes, e.g.
+
*Alternative classes, e.g.
** <code>QTable</code> / <code>QListView</code>
+
**<pre>QTable / QListView</pre>
** <code>QListBox</code> / <code>QComboBox</code>
+
**<pre>QListBox / QComboBox</pre>
** <code>QDial</code> / <code>QSlider</code> / <code>QSpinBox</code>
+
**<pre>QDial / QSlider / QSpinBox</pre>
* Patterns of use
+
*Patterns of use
** Minimal
+
**Minimal
** Realistic: quotes from snippets in the ''doc'' directory, and examples in the ''qt/examples'' directory
+
**Realistic: quotes from snippets in the ''doc'' directory, and examples in the ''qt/examples'' directory
* Concepts; e.g.
+
*Concepts; e.g.
** <code>QTextEdit</code>: lines vs. paragraphs
+
**<pre>QTextEdit</pre>: lines vs. paragraphs
** In Qt 3, <code>QCanvas</code> is abstract; <code>QCanvasView</code> actually displays the canvas
+
**In Qt 3, <pre>QCanvas</pre> is abstract; <pre>QCanvasView</pre> actually displays the canvas
* Details
+
*Details
** Describes and groups together functions with common features
+
**Describes and groups together functions with common features
  
 
Some examples of Qt documentation:
 
Some examples of Qt documentation:
  
* [http://doc.qt.digia.com/4.6/qstring.html QString] ''[doc.qt.digia.com]'' covers the use cases but is a little too technical at the start.
+
*[http://doc.qt.io/qt-5/qstring.html QString] covers the use cases but is a little too technical at the start.
* [http://doc.qt.digia.com/4.6/qdir.html QDir] ''[doc.qt.digia.com]'' is an example of a newer style where we used titles to split up different use cases.
+
*[http://doc.qt.io/qt-5/qdir.html QDir] is an example of a newer style where we used titles to split up different use cases.
* [http://doc.qt.digia.com/4.6/qmenu.html QMenu] ''[doc.qt.digia.com]'' is brief, but to the point, though it could use some code examples.
+
*[http://doc.qt.io/qt-5/qmenu.html QMenu] is brief, but to the point, though it could use some code examples.
* [http://doc.qt.digia.com/4.6/qdialog.html QDialog] ''[doc.qt.digia.com]'' cover various important concepts but should really address the practicalities of subclassing QDialog to implement your own dialog.
+
*[http://doc.qt.io/qt-5/qdialog.html QDialog] cover various important concepts but should really address the practicalities of subclassing QDialog to implement your own dialog.
* [http://doc.qt.digia.com/4.6/qpushbutton.html QPushButton] ''[doc.qt.digia.com]'' is a reasonable example of documentation for a simple widget.
+
*[http://doc.qt.io/qt-5/qpushbutton.html QPushButton] is a reasonable example of documentation for a simple widget.
* [http://doc.qt.digia.com/4.6/qgraphicsscene.html QGraphicsScene] ''[doc.qt.digia.com]'' is OK but could really use some code examples.
+
*[http://doc.qt.io/qt-5/qgraphicsscene.html QGraphicsScene] is OK but could really use some code examples.
* [http://doc.qt.digia.com/4.6/qpainter.html QPainter] ''[doc.qt.digia.com]'' is quite good at showing what the class does (in the documentation for the functions), but the main description tends to contain lists of functions. A lot of that should have been moved into an overview, in my opinion.
+
*[http://doc.qt.io/qt-5/qpainter.html QPainter] is quite good at showing what the class does (in the documentation for the functions), but the main description tends to contain lists of functions. A lot of that should have been moved into an overview, in my opinion.
  
I’m sure I haven’t found the “best” examples of documentation. These are just a few cases that I didn’t consider to be in need of radical improvement.
+
I'm sure I haven't found the "best" examples of documentation. These are just a few cases that I didn't consider to be in need of radical improvement.
  
The guidelines I learned basically followed the “pyramid” approach of providing a bit of simple information, then some more detailed information, followed by even more complex information about each class.
+
The guidelines I learned basically followed the "pyramid" approach of providing a bit of simple information, then some more detailed information, followed by even more complex information about each class.
  
# Describe what the class is/does.
+
#Describe what the class is/does.
# Refer the reader to other relevant classes or documents describing the concepts.
+
#Refer the reader to other relevant classes or documents describing the concepts.
# Show a simple use case, if possible.
+
#Show a simple use case, if possible.
# Describe the features, beginning with the simplest, most commonly used ones, showing relevant, simple code snippets. Try to group these into categories.
+
#Describe the features, beginning with the simplest, most commonly used ones, showing relevant, simple code snippets. Try to group these into categories.
# Describe more complex features that may involve interaction with other classes.
+
#Describe more complex features that may involve interaction with other classes.
# Discuss subclassing if relevant, and describe what the developer needs to take care of when doing this.
+
#Discuss subclassing if relevant, and describe what the developer needs to take care of when doing this.
# Put links to relevant documents, perhaps in a section of their own, but at least in a see-also line at the end of the detailed description.
+
#Put links to relevant documents, perhaps in a section of their own, but at least in a see-also line at the end of the detailed description.
  
 
There should, of course, be links to functions/methods and other classes throughout. Images are also good to include, either in terms of showing what a widget looks like or to illustrate a concept.
 
There should, of course, be links to functions/methods and other classes throughout. Images are also good to include, either in terms of showing what a widget looks like or to illustrate a concept.
Line 73: Line 98:
 
===Function descriptions===
 
===Function descriptions===
  
* <code>\brief</code> descriptions:
+
*<code>\brief</code> descriptions:
** Property descriptions should start with a lower case letter and have no ending period.
+
**Property descriptions should start with a lower case letter and have no ending period.
** Class descriptions should be complete sentences.
+
**Class descriptions should be complete sentences.
* Constructors should read something like, “Constructs the … with the given \a parent.
+
*Constructors should read something like, "Constructs the … with the given parent."
* Introduce arguments/parameters using the following two phrases:
+
*Introduce arguments/parameters using the following two phrases:
** … is specified by …
+
**… is specified by …
** … in the given …
+
**… in the given …
* '''Do not use'''
+
*'''Do not use'''
** … is given by …
+
**… is given by …
  
 
==Use of parameter names==
 
==Use of parameter names==
  
'''Don’t use natural language phrases that make the operation ambiguous:'''
+
'''Don't use natural language phrases that make the operation ambiguous:'''
 +
 
 +
<code>
 +
void Treasure::setValue(SomeClass *value)
 +
</code>
  
 
Sets the ''value'' of the treasure.
 
Sets the ''value'' of the treasure.
Line 93: Line 122:
 
Sets the value of the treasure to ''value''.
 
Sets the value of the treasure to ''value''.
  
The above use relies on a coincidence between the action on the instance and<br /> the value to use. It could also give the impression that <code>value</code> is<br /> changed in some way.
+
The above use relies on a coincidence between the action on the instance and
 +
the value to use. It could also give the impression that <code>value</code> is
 +
 
 +
changed in some way.
  
 
'''Avoid overspecifying definitions:'''
 
'''Avoid overspecifying definitions:'''
 +
 +
<code>
 +
MyWidget::MyWidget(const QString &name;, QWidget *parent)
 +
</code>
  
 
Constructs a new widget with name ''name'' and parent ''parent''.
 
Constructs a new widget with name ''name'' and parent ''parent''.
Line 103: Line 139:
 
Constructs a new widget with the given ''name'' and ''parent''.
 
Constructs a new widget with the given ''name'' and ''parent''.
  
'''Don’t change commonly used parameter names to suit local documentation requirements:'''
+
'''Don't change commonly used parameter names to suit local documentation requirements:'''
 +
 
 +
<code>
 +
void CanvasItem::setBoundingRect(const QRect &rectangle);
 +
</code>
  
 
Sets the bounding ''rectangle'' of the widget.
 
Sets the bounding ''rectangle'' of the widget.
  
The original <code>rect</code> parameter should not be renamed to ''rectangle''.<br /> Instead we would write something explicit:
+
The original <code>rect</code> parameter should not be renamed to ''rectangle''.
 +
 
 +
Instead we would write something explicit:
  
 
Sets the bounding rectangle of the widget to ''rect''.
 
Sets the bounding rectangle of the widget to ''rect''.
Line 113: Line 155:
 
===Miscellaneous===
 
===Miscellaneous===
  
* Use <code>\omit</code> and <code>\endomit</code> to omit sections from the documentation.
+
*Use <code>\omit</code> and <code>\endomit</code> to omit sections from the documentation.
** Remember that they are still present in the documentation source text.
+
**Remember that they are still present in the documentation source text.
* Use <code>\omitvalue</code> to omit enum values from the documentation, but still allow ''qdoc'' to process them without complaint.
+
*Use <code>\omitvalue</code> to omit enum values from the documentation, but still allow ''qdoc'' to process them without complaint.
  
 
==Style of example code==
 
==Style of example code==
  
See WritingQtExamples for more detailed guidance about writing and documenting examples.
+
See [[Writing Qt Examples]] for more detailed guidance about writing and documenting examples.
  
 
===Objectives===
 
===Objectives===
Line 125: Line 167:
 
Examples should be
 
Examples should be
  
* Simple
+
*Simple
* Bland (not necessarily)
+
*Bland (not necessarily)
* Cover the key concepts
+
*Cover the key concepts
  
 
===In header files===
 
===In header files===
  
* Give parameter names for used parameters.
+
*Give parameter names for used parameters.
* Write declared variables of the same type on separate lines.
+
*Write declared variables of the same type on separate lines.
* No underscores in names.
+
*No underscores in names.
* Only include header files that are absolutely necessary.
+
*Only include header files that are absolutely necessary.
  
 
===In C++ files===
 
===In C++ files===
  
* Order of actions in the constructor:
+
*Order of actions in the constructor:
** Create each widget and set options for it.
+
**Create each widget and set options for it.
** Set the connections.
+
**Set the connections.
** Create layout and insert items.
+
**Create layout and insert items.
** Set the title of top-level widgets with <code>setWindowTitle()</code>.
+
**Set the title of top-level widgets with <code>setWindowTitle()</code>.
  
* Accelerators and translations
+
*Accelerators and translations
** Use translation strings rather than hardcoded accelerator flags; e.g. <code>tr(“Ctrl+Q”)</code> rather than <code><span class="caps">CTRL</span> + Key_Q</code>
+
**Use translation strings rather than hard-coded accelerator flags; e.g. <code>tr("Ctrl+Q")</code> rather than <code>CTRL + Key_Q</code>
** Note that Qt provides [http://doc.qt.digia.com/stable/qkeysequence.html#StandardKey-enum enum values for standard shortcuts] ''[doc.qt.digia.com]'' which should be used in preference
+
**Note that Qt provides [http://doc.qt.io/qt-5/qkeysequence.html#StandardKey-enum enum values for standard shortcuts] which should be used in preference
* Comments:
+
*Comments:
** Introductory comment for each file. What the file is for.
+
**Introductory comment for each file. What the file is for.
** No comments where the purpose of the code is clear.
+
**No comments where the purpose of the code is clear.
** General comments about functions go outside the function in a multiline comment.
+
**General comments about functions go outside the function in a multi-line comment.
** What: the code itself.
+
**What: the code itself.
** Why: reason something is needed high level. (Outside function.)
+
**Why: reason something is needed - high level. (Outside function.)
** How: the way these actions are performed. (Outside function.)
+
**How: the way these actions are performed. (Outside function.)
  
 
===Variable naming===
 
===Variable naming===
Line 159: Line 201:
 
From a commit message made on 2004/05/28 16:08:34:
 
From a commit message made on 2004/05/28 16:08:34:
  
&lt;pre&gt; Renamed some “flag enum” types to be more consistent (i.e. the enum type associated to a flag type through Q_DECLARE_FLAGS).
+
<pre>
 +
Renamed some "flag enum" types to be more consistent (i.e.
 +
the enum type associated to a flag type through Q_DECLARE_FLAGS).
 +
 
 +
Usually, the enum type isn't used directly; only the flags type
 +
is. Still, sometimes we do use it, and then it's important to have
 +
a good name. Also, the documentation shows that name.
  
Usually, the enum type isn’t used directly; only the flags type is. Still, sometimes we do use it, and then it’s important to have a good name. Also, the documentation shows that name. The rule I’ve tried to follow were: 1. If the flags type is a plural (e.g. Options, Actions, Flags), make the enum type a singular (e.g. Option, Action, Flag). 2. Otherwise, make the enum type by appending “Flag” to the flags type (e.g. Alignment is the flags type, AlignmentFlag is the enum type). Notice that “Flag” is a singular. This is because an enum of that type can only store one flag at a time (whereas a variable of the “flags” type can store many). &lt;/pre&gt;
+
The rule I've tried to follow were:
  
===Documentation structure===
+
1. If the flags type is a plural (e.g. Options, Actions, Flags),
 +
make the enum type a singular (e.g. Option, Action, Flag).
  
* Necessary files to build the example.
+
2. Otherwise, make the enum type by appending "Flag" to the
* Overview document (to be converted by ''qdoc'' to some other format).
+
flags type (e.g. Alignment is the flags type, AlignmentFlag
 +
is the enum type).
  
[toc align_right=
+
Notice that "Flag" is a singular. This is because an enum of that
 +
type can only store one flag at a time (whereas a variable of the
 +
"flags" type can store many).
 +
</pre>
  
===Categories:===
+
===Documentation structure===
  
* [[:Category:Developing-Qt|Developing Qt]]
+
*Necessary files to build the example.
** [[:Category:Developing-Qt::Documentation|Documentation]]
+
*Overview document (to be converted by ''qdoc'' to some other format).

Latest revision as of 08:53, 21 June 2022


This document contains some documentation style guidelines that have been used when documenting Qt over the past few years.

It may be helpful to refer to the online qdoc manual.

See Building_Qt_Documentation for instructions on the usual way to build the Qt documentation.

See Troubleshooting Qt Documentation for advice on what to look for if your documentation is not processed correctly by qdoc.

See Developing Qt Documentation for information about the documentation process.

API documentation

General

  • Write complete sentences for items in lists.
  • Use real URLs if absolutely necessary, otherwise use "http://example.com".
  • When creating links to titles outside your project:
    • Use the \externalpage and \title commands in your own externalpages.qdoc file to create targets to use in body of text to improve source code readability and maintenance.
    • Check and re-use targets as defined in files in the "\Qt\Docs\applicable-Qt-version\global\externalsites" folder where possible to prevent duplication.
  • Indent using spaces, not tabs
  • Remove trailing spaces on a line
  • Wrap lines at 80 characters.

Use of language

Qt uses the Microsoft Writing Style Guide.

  • Hyphenation is not normally needed nor used.
  • Shorthand is discouraged.
    • For example, "and" should be used in preference to "&" unless there is a very good reason.

For more information, see the following links:

Title case vs. sentence case

Traditionally, title case is used for topic titles and section headings in Qt documentation. However, the Microsoft Writing Style Guide recommends sentence case. Therefore, you should follow the existing convention for current documentation. That usually means using title case, even for new topics added to the docs for a module (if title case is used for the existing topics).

For new documentation sets, such as docs for a new module or tool, you should adopt sentence case from the beginning.

Using title case

Each word in a title (either a page title or a section title) should start with an upper case letter, except for the most common prepositions (of, to, in, for, with and on) and coordinating conjunctions (for, and, nor, but, or, yet, and so).

For example, "Anchor Margins and Offsets" not "Anchor margins and offsets" (lower case is wrong) or "Anchor Margins And Offsets" ("and" should be lower case).

https://titlecaseconverter.com/ can be used to convert titles to title case.

Overview/modules

  • Shows/describes how classes in the module are used together.
  • Describes the main concepts and features of groups of classes.

Class descriptions

  • Brief overview
  • Start the main body of text with something like, "A <plain language name> is a…"
  • Alternative classes, e.g.
    • QTable / QListView
    • QListBox / QComboBox
    • QDial / QSlider / QSpinBox
  • Patterns of use
    • Minimal
    • Realistic: quotes from snippets in the doc directory, and examples in the qt/examples directory
  • Concepts; e.g.
    • QTextEdit
      : lines vs. paragraphs
    • In Qt 3,
      QCanvas
      is abstract;
      QCanvasView
      actually displays the canvas
  • Details
    • Describes and groups together functions with common features

Some examples of Qt documentation:

  • QString covers the use cases but is a little too technical at the start.
  • QDir is an example of a newer style where we used titles to split up different use cases.
  • QMenu is brief, but to the point, though it could use some code examples.
  • QDialog cover various important concepts but should really address the practicalities of subclassing QDialog to implement your own dialog.
  • QPushButton is a reasonable example of documentation for a simple widget.
  • QGraphicsScene is OK but could really use some code examples.
  • QPainter is quite good at showing what the class does (in the documentation for the functions), but the main description tends to contain lists of functions. A lot of that should have been moved into an overview, in my opinion.

I'm sure I haven't found the "best" examples of documentation. These are just a few cases that I didn't consider to be in need of radical improvement.

The guidelines I learned basically followed the "pyramid" approach of providing a bit of simple information, then some more detailed information, followed by even more complex information about each class.

  1. Describe what the class is/does.
  2. Refer the reader to other relevant classes or documents describing the concepts.
  3. Show a simple use case, if possible.
  4. Describe the features, beginning with the simplest, most commonly used ones, showing relevant, simple code snippets. Try to group these into categories.
  5. Describe more complex features that may involve interaction with other classes.
  6. Discuss subclassing if relevant, and describe what the developer needs to take care of when doing this.
  7. Put links to relevant documents, perhaps in a section of their own, but at least in a see-also line at the end of the detailed description.

There should, of course, be links to functions/methods and other classes throughout. Images are also good to include, either in terms of showing what a widget looks like or to illustrate a concept.

Function descriptions

  • \brief descriptions:
    • Property descriptions should start with a lower case letter and have no ending period.
    • Class descriptions should be complete sentences.
  • Constructors should read something like, "Constructs the … with the given parent."
  • Introduce arguments/parameters using the following two phrases:
    • … is specified by …
    • … in the given …
  • Do not use
    • … is given by …

Use of parameter names

Don't use natural language phrases that make the operation ambiguous:

void Treasure::setValue(SomeClass *value)

Sets the value of the treasure.

It would be better to write something explicit:

Sets the value of the treasure to value.

The above use relies on a coincidence between the action on the instance and the value to use. It could also give the impression that value is

changed in some way.

Avoid overspecifying definitions:

MyWidget::MyWidget(const QString &name;, QWidget *parent)

Constructs a new widget with name name and parent parent.

Maybe something like the following would be acceptable:

Constructs a new widget with the given name and parent.

Don't change commonly used parameter names to suit local documentation requirements:

void CanvasItem::setBoundingRect(const QRect &rectangle);

Sets the bounding rectangle of the widget.

The original rect parameter should not be renamed to rectangle.

Instead we would write something explicit:

Sets the bounding rectangle of the widget to rect.

Miscellaneous

  • Use \omit and \endomit to omit sections from the documentation.
    • Remember that they are still present in the documentation source text.
  • Use \omitvalue to omit enum values from the documentation, but still allow qdoc to process them without complaint.

Style of example code

See Writing Qt Examples for more detailed guidance about writing and documenting examples.

Objectives

Examples should be

  • Simple
  • Bland (not necessarily)
  • Cover the key concepts

In header files

  • Give parameter names for used parameters.
  • Write declared variables of the same type on separate lines.
  • No underscores in names.
  • Only include header files that are absolutely necessary.

In C++ files

  • Order of actions in the constructor:
    • Create each widget and set options for it.
    • Set the connections.
    • Create layout and insert items.
    • Set the title of top-level widgets with setWindowTitle().
  • Accelerators and translations
    • Use translation strings rather than hard-coded accelerator flags; e.g. tr("Ctrl+Q") rather than CTRL + Key_Q
    • Note that Qt provides enum values for standard shortcuts which should be used in preference
  • Comments:
    • Introductory comment for each file. What the file is for.
    • No comments where the purpose of the code is clear.
    • General comments about functions go outside the function in a multi-line comment.
    • What: the code itself.
    • Why: reason something is needed - high level. (Outside function.)
    • How: the way these actions are performed. (Outside function.)

Variable naming

From a commit message made on 2004/05/28 16:08:34:

 Renamed some "flag enum" types to be more consistent (i.e.
 the enum type associated to a flag type through Q_DECLARE_FLAGS).

Usually, the enum type isn't used directly; only the flags type
 is. Still, sometimes we do use it, and then it's important to have
 a good name. Also, the documentation shows that name.

The rule I've tried to follow were:

1. If the flags type is a plural (e.g. Options, Actions, Flags),
 make the enum type a singular (e.g. Option, Action, Flag).

2. Otherwise, make the enum type by appending "Flag" to the
 flags type (e.g. Alignment is the flags type, AlignmentFlag
 is the enum type).

Notice that "Flag" is a singular. This is because an enum of that
 type can only store one flag at a time (whereas a variable of the
 "flags" type can store many).

Documentation structure

  • Necessary files to build the example.
  • Overview document (to be converted by qdoc to some other format).