|
|
              
Writing DocumentationQDoc CommentsDocumentation is contained within qdoc comments, delimited by 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 CommandsQDoc 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 TopicsEach 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:
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:
The Topic Commands page has information on all of the available topic commands. Topic ContextsContext 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 MarkupQDoc 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. \b{This} text will be in \b{bold}.
The Markup Commands page has a full listing of the available markup commands. Anatomy of DocumentationEssentially, for QDoc to create a page, there must be some essential ingredients present.
In Qt, the QVector3D class was documented with the following QDoc comment: It has a constructor, QVector3D::QVector3D(), which was documented with the following QDoc comment: The different comments may reside in different files and QDoc will collect them depending on their topic and their context. The resulting documentation from the snippets are generated into the QVector3D class documentation. Note that if the documentation immediately precedes the function or class in the source code, then it does not need to have a topic. QDoc will assume that the documentation above the code is the documentation for that code. An article is created using \page command. The first argument is the HTML file that QDoc will create. The topic is supplemented with context commands, the \title and \nextpage commands. There are several other QDoc commands such as the \list command. The section on topic commands gives an overview on several other topic types. |
