|
|
              
Categories of DocumentationThere are several types of predefined documentation categories or types:
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 DocumentationQDoc 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. Note: QDoc uses the header files to inform itself about the class and will not properly process QDoc comments in header files. Documenting QML TypesIn 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:
Note: 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 \qmlclass command as its topic command. QML ParserIf 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. 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 \qmlclass 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 \qmlclass command must appear in the QDoc comment for the QML type, and a \qmlproperty command must appear in each QML property QDoc comment. QML ModulesA 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 Elements belong to the QtQuick2 module while there is also a QtQuick1 module for the older types introduced in Qt 4. Modules affect the way Qdoc link and relate the types. The \qmlclass topic command must have an \inqmlmodule context command to relate the type to a 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 related types. 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. The UIComponents example demonstrates proper usage of QDoc commands to document QML types and QML modules. Read-only and Internal QML PropertiesQDoc detects QML properties that are marked as readonly. Note that the property must be initialized with a value. readonly property int sampleReadOnlyProperty: 0 For example, the example TabWidget type has a fictitious read-only property sampleReadOnlyProperty. Its declaration has the readonly identifier and it has an initial value. Properties 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 & OverviewsArticles 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 QtQuick, individual modules, design principles, or tools. To signify that a document is an article, you append the article keyword to the \page command: The writing topic commands section has a listing of the available \page command arguments. Tutorials, How-To's, FAQ'sTutorials, 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. The writing topic commands section has a listing of the available \page command arguments. Code ExamplesExamples 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. 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. For reference, view QDoc's generated page for the Tab Widget example. Note: The example's project file must be the same as the directory name. |
