Documentation Style for Examples

En Ar Bg De El Es Fa Fi Fr Hi Hu It Ja Kn Ko Ms Nl Pl Pt Ru Sq Th Tr Uk Zh

This page is part of the Qt Writing Guidelines. See also:

1. Integrating Examples - QDoc configuration
2. Qt6/Example-Guideline - Writing example code

Example Documentation and Tutorials

Qt 6 examples have an accompanying documentation. This documentation should describe the example's themes and which Qt modules or tools are used. An accompanying image is important to show UI related elements and the expected output should be clear.

A tutorial goes beyond a description, outlining particular steps and highlighting the important parts of the example. The tutorial should walk through the code and gloss over topics related to Qt. Notes and other information should supplement the walk-through, giving insight and reason for the particular code.

Essentially, the minimum example documentation should contain:

1. Example page - QDoc's \example command creates the example page. The \example command specifies the directory.
2. Title - QDoc's \title command. The title should be simple and descriptive
3. Brief description - \brief command and a small description of the example's theme
4. Example category - label the example documentation with \examplecategory to assign it to a membership. For example Connectivity, Desktop, and so on.
5. Main body - one or several paragraphs that describe the example's themes and expected behavior
6. Running instruction - describe where to find the example (see Sample Text: Running Instruction section)
7. References - add links to related documentation, overview, or other supplementary material
8. Licenses - add the Commercial/BSD 3 clause license.
9. Image - especially useful for GUI related examples. Qt Creator can show these images as thumbnails.

The minimum tutorial fulfills the minimum example documentation, and the following:

1. Code snippets - show and analyze the code in a granular (line-by-line) or holistic (the principle and goal) way.
2. Step-by-step instruction - show the progression from start to finish. A similar style is meal recipes, but do not follow strictly.
3. Insight - provide insight to the code structure and Qt usage. A possible reason may be code security, scalability, usability, and so on.
4. Verb-focused title - Emphasize the action or verb in the title. Use the gerund, typically ending in -ing. For example, drawing, integrating, handling, processing, and so on.

The sections below provide sample text for the requirements for example documentation and tutorial

Sample Text: Running Instruction

Example documentation and tutorials should outline the requirements and steps for building and running the example. Ideally, Qt Creator can open and launch the example, but some examples may need additional tools or environment.

We aim for consistency and the following text is appropriate to inform about running examples from within Qt Creator. Feel free to modify and adapt to the specific example.

At the bottom of your example documentation (same area as the \page command), add:

\include examples-run.qdocinc

This will include the text (taken from qtbase/doc/global):

\section1 Running the Example

To run the example from {Qt Creator Manual}{Qt Creator}, open the Welcome
mode and select the example from Examples. For more information, visit
{Qt Creator: Building and Running an Example}{Building and Running an Example}.

Sample Text: Licenses

For example code, use the Commercial/BSD 3 clause license:

// Copyright (C) 2024 The Qt Company Ltd.
// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR BSD-3-Clause

The example documentation and tutorial can be under a specific Commercial/GFDL 1.3 documentation license:

// Copyright (C) 2024 The Qt Company Ltd.
// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only