Categories of Documentation▲
There are several types of predefined documentation categories or types:
-
How-To's
-
Tutorial
-
Overview
-
Article
-
FAQ (Frequently Asked Questions)
-
C++ API Documentation
-
QML Type Documentation
-
Code Example
QDoc has the ability to format a page depending on the type. Further, stylesheets can provide additional control on the display of each category.
API Documentation▲
QDoc excels in the creation of API documentation given a set of source code and documentation in QDoc comments. Specifically, QDoc is aware of Qt's architecture and can validate the existence of Qt C++ class, function, or property documentation. QDoc gives warnings and errors if it cannot associate a documentation with a code entity or if a code entity does not have documentation.
In general, every Qt code entity such as properties, classes, methods, signals, and enumerations have a corresponding topic command. QDoc will associate the documentation to the source using C++ naming rules.
QDoc will parse the header files (typically .h files) to build a tree of the class structures. Then QDoc will parse the source files and documentation files to attach documentation to the class structure. Afterwards, QDoc will generate a page for the class.
QDoc uses the header files to inform itself about the class and will not properly process QDoc comments in header files.
Language Styles▲
To produce quality API documentation, the Qt API references follow a particular language guidelines. While the contents of this page demonstrates how to create API documentation, the style guidelines demonstrate how the reference materials follow a consistent use of language.
Documenting QML Types▲
In the world of QML, there are additional entities we need to document such as QML signals, attached properties, and QML methods. Internally, they use Qt technologies, however, QML API documentation requires different layout and naming conventions from the Qt C++ API documentation.
A list of QML related QDoc commands:
-
\qmltype - creates a QML type documentation
Remember to enable QML parsing by including the *.qml filetype in the fileextension variable.
To document a QML type, start by creating a QDoc comment that uses the \qmltype command as its topic command.
QML Parser▲
If your QML type is defined in a qml file, document it there. If your QML type is represented by a C++ class, document it in the cpp file for that C++ class and include an \instantiates command to specify the name of the C++ class. Don't document a QML type in a cpp file if the QML type is defined in a qml file.
When documenting a QML type in a qml file, place each QDoc comment directly above the entity to which the comment applies. For example, place the QDoc comment containing the \qmltype command (the topic comment) directly above the outer QML type in the qml file. Place the comment for documenting a QML property directly above the property declaration, and so on for QML signal handlers and QML methods. Note that when documenting QML properties in a qml file, you don't normally include the \qmlproperty command as a topic command (which you must do when documenting QML types in cpp files), because the QML parser automatically associates each QDoc comment with the next QML declaration it parses. The same is true for QML signal handler and QML method comments. But it is sometimes useful to include one or more \qmlproperty commands in the comment, e.g. when the property type is another QML type and you want the user to only use certain properties within that other QML type, but not all of them. But when documenting a property that has an alias, place the QDoc comment for it directly above the alias declaration. In these cases, the QDoc comment must contain a \qmlproperty command, because that is the only way QDoc can know the type of the aliased property.
When documenting a QML type in the cpp file of its corresponding C++ class (if it has one), you normally place each QDoc comment directly above the entity it documents. However, QDoc does not use the QML parser to parse these files (the C++ parser is used), so these QML QDoc comments can appear anywhere in the cpp file. Note that QML QDoc comments in cpp files must use the QML topic commands. i.e., the \qmltype command must appear in the QDoc comment for the QML type, and a \qmlproperty command must appear in each QML property QDoc comment.
QML Modules▲
A QML type belongs to a module. The module may include all the related types for a platform or contain a certain version of Qt Quick. For example, the Qt Quick 2 QML types belong to the Qt Quick 2 module while there is also a Qt Quick 1 module for the older types introduced in Qt 4.
QML modules allow grouping QML types. The \qmltype topic command must have an \inqmlmodule context command to relate the type to a QML module. Similarly, a \qmlmodule topic command must exist in a separate .qdoc file to create the overview page for the module. The overview page will list the QML types of the QML module.
The links to the QML types must therefore also contain the module name. For example, if a type called TabWidget is in the UIComponents module, it must be linked as UIComponents::TabWidget.
Read-only and Internal QML Properties▲
QDoc detects QML properties that are marked as readonly. Note that the property must be initialized with a value.
readonly property int sampleReadOnlyProperty: 0Properties and signals that are not meant for the public interface may be marked with the \internal command. QDoc will not publish the documentation in the generated outputs.
Articles & Overviews▲
Articles and overviews are a style of writing best used for providing summary detail on a topic or concept. It may introduce a technology or discuss how a concept may be applied, but without discussing exact steps in too much detail. However, this type of content could provide the entry point for readers to find instructional and reference materials that do, such as tutorials, examples and class documentation. An example of an overview might be a product page, such as a top level discussion of Qt Quick, individual modules, design principles, or tools.
To signify that a document is an article, you append the article keyword to the \page command:
/*!
\page overview-qt-technology.html overview
\title Overview of a Qt Technology
\brief provides a technology never seen before.
*/The writing topic commands section has a listing of the available \page command arguments.
Tutorials, How-To's, FAQ's▲
Tutorials, How-To's, and FAQ's are all instructional material, in that they instruct or prescribe to the reader. Tutorials are content designed to guide the reader along a progressive learning path for a concept or technology. How-To's and FAQ's (Frequently Asked Questions) provide guidance by presenting material in the form of answers to commonly asked topics. How-To's and FAQ's are designed for easy reference and are not necessarily presented in a linear progression.
To create these types, mark the pages by providing a type argument to the \page command. The type argument is the second argument, with the file name being the first.
/*!
\page altruism-faq.html faq
\title Altruism Frequently Asked Questions
\brief All the questions about altruism, answered.
...
*/The writing topic commands section has a listing of the available \page command arguments.
Code Examples▲
Examples are an effective way to demonstrate practical usage of a given technology or concept. When it comes to middleware this is usually in the form of an application using simple code and clear explanations of what the code is doing. Any module, API, project, pattern etc. should have at least one good example.
An example may have an accompanying tutorial. The tutorial instructs and describes the code, while the code example is the code content that users may study. Code examples may have accompanying text that are not in the tutorial.
QDoc will create a page containing the example code with a description using the \example command.
/*!
\title UI Components: Tab Widget Example
\example declarative/ui-components/tabwidget
This example shows how to create a tab widget. It also demonstrates how
\l {Property aliases}{property aliases} and
\l {Introduction to the QML Language#Default Properties}{default properties} can be used to collect and
assemble the child items declared within an \l Item.
\image qml-tabwidget-example.png
*/QDoc will use the directory specified in the input exampledirs variable to find the Qt Project (.pro) file to generate the example files. The generated HTML will have the filename, declarative-ui-components-tabwidget.html. QDoc will also list all of the example code.
The example's project file must be the same as the directory name.