QDoc Comments▲

Documentation is contained within QDoc comments, delimited by /*! and */ comments. Note that these are valid comments in C++, QML, and JavaScript.

Within a QDoc comment, //! is used as a single-line documentation comment; the comment itself and anything after it, until a newline, is omitted from the generated output.

QDoc will parse C++ and QML files to look for qdoc comments. To explicitly omit a certain file type, omit it from the configuration file.

QDoc Commands▲

QDoc uses commands to retrieve information about the documentation. Topic commands determine the type of documentation element, the context commands provide hints and information about a topic, and markup commands provide information on how QDoc should format a piece of documentation.

 

QDoc Topics▲

Each qdoc comment must have a topic type. A topic distinguishes it from other topics. To specify a topic type, use one of the several topic commands.

QDoc will collect similar topics and create a page for each one. For example, all the enumerations, properties, functions, and class description of a particular C++ class will reside in one page. A generic page is specified using the \page command and the filename is the argument.

Example of topic commands:

  • \enum - for enumeration documentation

  • \class - for C++ class documentation

  • \qmltype - for QML type documentation

  • \page - for creating a page.

The \page command is for creating articles that are not part of source documentation. The command can also accept two arguments: the file name of the article and the documentation type. The possible types are:

  • howto

  • overview

  • tutorial

  • faq

  • article - default when there is no type

 
Sélectionnez
/*!
    \page altruism-faq.html faq
    \title Altruism Frequently Asked Questions

    \brief All the questions about altruism, answered.

    ...
*/

The Topic Commands page has information on all of the available topic commands.

 

Topic Contexts▲

Context commands give QDoc a hint about the context of the topic. For example, if a C++ function is obsolete, then it should be marked obsolete with the \obsolete command. Likewise, page navigation and page title give extra page information to QDoc.

QDoc will create additional links or pages for these contexts. For example, a group is created using the \group command and the members have the \ingroup command. The group name is supplied as an argument.

The Context Commands page has a listing of all the available context commands.

 

Documentation Markup▲

QDoc can do markup of text similar to other markup or documentation tools. QDoc can mark a section of text in bold, when the text is marked up with the \b command.

 
Sélectionnez
\b{This} text will be in \b{bold}.

The Markup Commands page has a full listing of the available markup commands.

Anatomy of Documentation▲

Essentially, for QDoc to create a page, there must be some essential ingredients present.

  • Assign a topic to a QDoc comment - A comment could be a page, a property documentation, a class documentation, or any of the available