Introduction to QDoc

QDoc is a tool used by Qt Developers to generate documentation for software projects. It works by extracting QDoc comments from project source files and then formatting these comments as HTML pages or DocBook XML documents. QDoc finds QDoc comments in .cpp files and in .qdoc files. QDoc does not look for QDoc comments in .h files. A QDoc comment always begins with an exclamation mark (!)). For example:

/*!
    \class QObject
    \brief The QObject class is the base class of all Qt objects.

    \ingroup objectmodel

    \reentrant

    QObject is the heart of the Qt \l{Object Model}. The
    central feature in this model is a very powerful mechanism
    for seamless object communication called \l{signals and
    slots}. You can connect a signal to a slot with connect()
    and destroy the connection with disconnect(). To avoid
    never ending notification loops you can temporarily block
    signals with blockSignals(). The protected functions
    connectNotify() and disconnectNotify() make it possible to
    track connections.

    QObjects organize themselves in \l {Object Trees &
    Ownership} {object trees}. When you create a QObject with
    another object as parent, the object will automatically
    add itself to the parent's \c children() list. The parent
    takes ownership of the object. It will automatically
    delete its children in its destructor. You can look for an
    object by name and optionally type using findChild() or
    findChildren().

    Every object has an objectName() and its class name can be
    found via the corresponding metaObject() (see
    QMetaObject::className()). You can determine whether the
    object's class inherits another class in the QObject
    inheritance hierarchy by using the \c inherits() function.

....
*/

From the QDoc comment above, QDoc generates the HTML QObject class reference page.

This manual explains how to use the QDoc commands in QDoc comments to embed good documentation in your source files. It also explains how to make a QDoc configuration file, which you will pass to QDoc on the command line.

Running QDoc

The name of the QDoc program is qdoc. To run QDoc from the command line, give it the name of a configuration file:

$ ../../bin/qdoc ./config.qdocconf

QDoc recognizes the .qdocconf suffix as a QDoc configuration file. The configuration file is where you tell QDoc where to find the project source files, header files, and .qdoc files. It is also where you tell QDoc what kind of output to generate (HTML, DocBook XML...), and where to put the generated documentation. The configuration file also contains other information for QDoc.

See The QDoc Configuration File for instructions on how to set up a QDoc configuration file.

How QDoc Works

QDoc begins by reading the configuration file you specified on the command line. It stores all the variables from the configuration file for later use. One of the first variables it uses is outputformats. This variable tells QDoc which output generators it will run. The default value is HTML, so if you don't set outputformats in your configuration file, QDoc will generate HTML output. That's usually what you will want anyway, but you can also specify DocBook to get DocBook output instead.

Next, QDoc uses the values of the headerdirs variable and/or the headers variable to find and parse all the header files for your project. QDoc does not scan header files for QDoc comments. It parses the header files to build a master tree of all the items that should be documented, in other words, the items that QDoc should find QDoc comments for.

After parsing all the header files and building the master tree of items to be documented, QDoc uses the value of the sourcedirs variable and/or the value of the sources variable to find and parse all the .cpp and .qdoc files for your project. These are the files QDoc scans for QDoc comments. Remember that a QDoc comment begins with an exclamation mark: /*! .

For each QDoc comment it finds, it searches the master tree for the item where the documentation belongs. Then it interprets the QDoc commands in the comment and stores the interpreted commands and the comment text in the tree node for the item.

Finally, QDoc traverses the master tree. For each node, if the node has stored documentation, QDoc calls the output generator specified by the outputformats variable to format and write the documentation in the directory specified in the configuration file in the outputdir variable.

Command Types

QDoc interprets three types of commands:

• Topic Commands
• Context Commands
• Markup Commands

Topic commands identify the element you are documenting, for example a C++ class, function, type, or an extra page of text that doesn't map to an underlying C++ element.

Context commands tell QDoc how the element being documented relates to other documented elements, for example, next and previous page links, inclusion in page groups, or library modules. Context commands can also provide information about the documented element that QDoc can't get from the source files, for example, whether the element is thread-safe, whether it is an overloaded or reimplemented function, or whether it has been deprecated.

Markup commands tell QDoc how text and image elements in the document should be rendered, or about the document's outline structure.

Qt uses QDoc to generate its documentation set into HTML and DocBook XML formats. QDoc uses a set of configuration files to generate documentation from QDoc comments. The comments have types called topics that determine whether a comment is a class documentation or a property documentation. A comment may also have mark up to enhance the layout and formatting of the final output.

There are three essential materials for generating documentation with QDoc:

• QDoc binary
• qdocconf configuration files
• Documentation in C++, QML, and .qdoc files

This section intends to cover the basic necessities for creating a documentation set. Additionally, the guide presents special considerations and options to documenting non-C++ API documentation as well as QML documentation. Finally, the guide will provide a sample project documentation and an example of a QML type documentation.

For specific QDoc information, consult the QDoc Manual.

Chapters

1. Installing Clang for QDoc
2. Creating QDoc Configuration Files
3. Writing Documentation
4. Categories of Documentation
   • C++ Documentation Style
   • QML Documentation Style
5. How to Resolve QDoc Warnings