diff options
Diffstat (limited to 'src/qdoc/qdoc/doc/qdoc-guide/qdoc-guide.qdoc')
| -rw-r--r-- | src/qdoc/qdoc/doc/qdoc-guide/qdoc-guide.qdoc | 670 |
1 files changed, 670 insertions, 0 deletions
diff --git a/src/qdoc/qdoc/doc/qdoc-guide/qdoc-guide.qdoc b/src/qdoc/qdoc/doc/qdoc-guide/qdoc-guide.qdoc new file mode 100644 index 000000000..9bf6aa63a --- /dev/null +++ b/src/qdoc/qdoc/doc/qdoc-guide/qdoc-guide.qdoc @@ -0,0 +1,670 @@ +// Copyright (C) 2020 The Qt Company Ltd. +// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only +/*! + \page qdoc-guide.html + \title Getting Started with QDoc + \nextpage Installing Clang for QDoc + + 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 + \l{writing-topic-commands}{topics} that determine whether a comment is a + class documentation or a property documentation. A comment may also have + \l{writing-markup}{mark up} to enhance the layout and formatting of the + final output. + + There are three essential materials for generating documentation with QDoc: + \list + \li \c QDoc binary + \li \c qdocconf configuration files + \li \c Documentation in \c C++, \c QML, and \c .qdoc files + \endlist + + \note \l{QDoc Manual}{QDoc} requires \l{http://clang.llvm.org}{Clang} + for parsing C++ header and source files, and for parsing the function + signatures in \l {fn-command} {\\fn} commands. See \l {Installing Clang for QDoc} + for details. + + 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 + \l{QDoc Manual}. + \section1 Chapters + + \list 1 + \li \l{Installing Clang for QDoc} + \li \l{Creating QDoc Configuration Files} + \li \l{Writing Documentation} + \li \l{Categories of Documentation} + \list + \li \l{C++ Documentation Style} + \li \l{QML Documentation Style} + \endlist + \li \l{How to Resolve QDoc Warnings} + \endlist + +*/ + +/*! + \page qdoc-guide-conf.html + \title Creating QDoc Configuration Files + \previouspage Installing Clang for QDoc + \nextpage Writing Documentation + To generate documentation, QDoc uses configuration files, with the + \c qdocconf extension, to store configuration settings. + + The \l{The QDoc Configuration File} article covers the various configuration + variables in greater detail. + + \section1 QDoc Configuration Files + QDoc's configuration settings can reside in a single \e qdocconf file, but + can also be in other qdocconf files. The \c {include(<filepath>)} command + allows configuration files to include other configuration files. + + QDoc has two outputs, HTML documentation and documentation in DocBook XML + format. The main distinction between the two outputs is that HTML + documentation needs to have its HTML styling information in the + configuration files. DocBook documentation does not, and a separate process + can style the documentation in DocBook at a later time. DocBook therefore + more flexible in allowing different styles to apply to the same information. + + To run QDoc, the project configuration file is supplied as an argument. + \code + qdoc project.qdocconf + \endcode + + The project configuration contains information that QDoc uses to create the + documentation. + + \section2 Project Information + + QDoc uses the \c project information to generate the documentation. + \code + project = QDoc Project + description = Sample QDoc project + \endcode + + \target qdoc-input-output-dir + \section2 Input and Output Directories + + Specifying the path to the source directories allow QDoc to find sources and + generate documentation. + + \badcode + sourcedirs = <path to source code> + exampledirs = <path to examples directory> + imagedirs = <path to image directory> + + sources.fileextensions = "*.cpp *.qdoc *.mm *.qml" + headers.fileextensions = "*.h *.ch *.h++ *.hh *.hpp *.hxx" + examples.fileextensions = "*.cpp *.h *.js *.xq *.svg *.xml *.ui *.qhp *.qhcp *.qml" + examples.imageextensions = "*.png *.jpeg *.jpg *.gif *.mng" + \endcode + + QDoc will process headers and sources from the ones specified in the + \c fileextensions variable. + + Likewise, QDoc needs the path to the output directory. The \c outputformats + variable determines the type of documentation. These variables should be + in separate configuration files to modularize the documentation build. + \badcode + outputdir = $SAMPLE_PROJECT/doc/html + outputformats = HTML + \endcode + + QDoc can resolve the paths relative to the qdocconf file as well as + environment variables. + + \note During each QDoc run, the output directory is deleted. + \section2 Extra Files + + QDoc will output generated documentation into the directory specified in + the \l{Input and Output Directories}{output} directory. It is also possible + to specify extra files that QDoc should export. + + \badcode + HTML.extraimages = extraImage.png \ + extraImage2.png + \endcode + + The \c extraImage.png and the \c extraImage2.png files will be copied to the + HTML output directory. + + \section2 Qt Help Framework Configuration + + QDoc will also export a \e {Qt Help Project} file, in a \c qhp file. + The qhp file is then used by the \c qhelpgenerator to package the + documentation into a \c qch file. Qt Creator and Qt Assistant reads the qch + file to display the documentation. + + The \l {Creating Help Project Files} article covers the configuration + options. + + \section2 HTML Configuration + + QDoc has an HTML generator that will export a set of documentation into + HTML files using various configuration settings. QDoc will place the + generated documentation into the directory specified by the \c outputdir + variable. + + \badcode + outputformats = HTML + outputdir = <path to output directory> + \endcode + + QDoc needs to know where the styles and templates for generating HTML + are located. Typically, the templates directory contains a \c scripts, + \c images, and a \c style directory, containing scripts and CSS files. + + The main configuration variables are: + \badcode + HTML.postheader + HTML.postpostheader + HTML.postheader + HTML.footer + + HTML.headerstyles + HTML.stylesheets = template/style/style.css \ + template/style/style1.css + + HTML.scripts = template/scripts/script.js + \endcode + + The \c{HTML.headerstyles} variable inserts the style information into the + HTML file and the \c{HTML.stylesheets} specifies which files QDoc should + copy into the output directory. In addition, QDoc will embed the string + in the \c postheader, \c footer, and related variables into each HTML file. + + The \l {Format-specific Configuration Variables} article outlines the usage + of each variable. + + \section2 QDoc Index Files + + Documentation projects can link to targets in other projects by specifying + a set of dependencies, or a set of direct paths to index file(s) this + project depends on. When QDoc generates documentation for a project, + it will also generate an \c .index file containing URLs to each linkable + entity in the project. Other projects can then define a dependency to the + index file in order to link to the documentation within that project. + + \b {See also}: \l {depends-variable}{depends} and + \l {indexes-variable}{indexes}. + + \section1 Macros and Other Configurations + + Macros for substituting HTML characters exist and are helpful for generating + specific HTML-valid characters. + + \badcode + macro.pi.HTML = "Π" + \endcode + The snippet code will replace any instances of \c{\\pi} with \c Π in the + HTML file, which will appear as the Greek \pi symbol when viewed in + browsers. + + \b {See also:} \l {macro-variable}{macro}. + + \section2 QML Additions + + QDoc is able to parse QML files for QDoc comments. QDoc will parse files + with the QML extension, \c{.qml}, if the extension type is included in the + \l{Input and Output Directories}{fileextensions} variable. + + Also, the generated HTML files can have a prefix and a suffix following the + QML module name, specified in the QDoc configuration file. + \badcode + outputprefixes = QML + outputprefixes.QML = uicomponents- + outputsuffixes = QML + outputsuffixes.QML = -tp + \endcode + + \b {See also}: \l {outputprefixes-variable}{outputprefixes}, + \l {outputsuffixes-variable}{outputsuffixes}. + +*/ + +/*! + \page qdoc-guide-writing.html + \title Writing Documentation + \previouspage Creating QDoc Configuration Files + \nextpage Categories of Documentation + + \section1 QDoc Comments + + Documentation is contained within QDoc \e comments, delimited by + \beginqdoc and \endqdoc comments. Note that these are valid comments + in C++ and QML. + + Within a QDoc comment, \c {//!} 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 + \l{Input and Output Directories}{configuration} file. + + \section1 QDoc Commands + + QDoc uses \e commands to retrieve information about the documentation. \c + Topic commands determine the type of documentation element, the \c context + commands provide hints and information about a topic, and \c markup commands + provide information on how QDoc should format a piece of documentation. + + \target writing-topic-commands + \section2 QDoc Topics + Each QDoc comment must have a \e topic type. A topic distinguishes it from + other topics. To specify a topic type, use one of the several + \l{Topic Commands}{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 \l{page-command}{\\page} command and the filename is the + argument. + + Example of topic commands: + \list + \li \l{enum-command}{\\enum} - for enumeration documentation + \li \l{class-command}{\\class} - for C++ class documentation + \li \l{qmltype-command}{\\qmltype} - for QML type documentation + \li \l{page-command}{\\page} - for creating a page. + \endlist + + A QDoc comment can contain multiple topic commands in the same category, with + some restrictions. This way, it's possible to write a single comment that + documents all overloads of a function (using multiple \l {fn-command}{\\fn} + commands), or all properties in a QML property group (using + \l {qmlproperty-command}{\\qmlproperty} commands) in one go. + + If a QDoc comment contains multiple topic commands, it's possible to + provide additional \e {context commands} for individual topics in + follow-up comments: + + \badcode * + /\1! + \qmlproperty string Type::element.name + \qmlproperty int Type::element.id + + \brief Holds the element name and id. + \1/ + + /\1! + \qmlproperty int Type::element.id + \readonly + \1/ + \endcode + + Here, the follow-up comment marks the \e element.id property as read-only, + while \e element.name remains writable. + + \note A follow-up comment cannot contain any additional text, only + \l {writing-context}{context commands} that document the context of + the item. + + The \l{page-command}{\\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: + \list + \li \c howto + \li \c overview + \li \c tutorial + \li \c faq + \li \c attribution - used for documenting license attributions + \li \c article - \e default when there is no type + \endlist + + \snippet examples/samples.qdocinc sample-faq + + The \l{Topic Commands} page has information on all of the available topic + commands. + + \target writing-context + \section2 Topic Contexts + + Context commands give QDoc a hint about the \e context of the topic. For + example, if a C++ function is deprecated, then it should be marked as such + with the \l{deprecated-command}{\\deprecated} command. Likewise, + \l{nextpage-command}{page navigation} and \l{title-command}{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 \l{group-command}{\\group} command and the + members have the \l{ingroup-command}{\\ingroup} command. The group name is + supplied as an argument. + + The \l{Context Commands} page has a listing of all the available context + commands. + + \target writing-markup + \section2 Documentation Markup + + QDoc can do \e markup of text similar to other markup or + documentation tools. QDoc can mark a section of text in \b{bold}, + when the text is marked up with the \l{b-command}{\\b} command. + + \code + \b{This} text will be in \b{bold}. + \endcode + + The \l{Markup Commands} page has a full listing of the available markup + commands. + + \section1 Anatomy of Documentation + + Essentially, for QDoc to create a page, there must be some essential + ingredients present. + + \list + \li Assign a topic to a QDoc comment - A comment could be a page, a + property documentation, a class documentation, or any of the available + \l{Topic Commands}{topic commands}. + + \li Give the topic a context - QDoc can associate certain topics to other + pages such as associating deprecated functions when the documentation is + marked with \l{deprecated-command}{\\deprecated}. + + \li Mark sections of the document with + \l{Markup Commands}{markup commands} - QDoc can create layouts and + format the documentation for the documentation. + \endlist + + In Qt, the \l{QVector3D} class was documented with the following QDoc + comment: + \snippet examples/samples.qdocinc qvector3d-class + + It has a constructor, \l{QVector3D::QVector3D()}, which was documented with + the following QDoc comment: + \snippet examples/samples.qdocinc qvector3d-function + + 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 \l{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 \l{page-command}{\\page} command. The first + argument is the HTML file that QDoc will create. The topic is supplemented + with context commands, the \l{title-command}{\\title} and + \l{nextpage-command}{\\nextpage} commands. There are several other + QDoc commands such as the \l{list-command}{\\list} command. + \snippet examples/samples.qdocinc sample-page + + The section on \l{QDoc Topics}{topic commands} gives an overview on several + other topic types. + + +*/ + +/*! + \page qdoc-categories.html + \title Categories of Documentation + \previouspage Writing Documentation + \nextpage How to Resolve QDoc Warnings + \brief Describes the different types such as How-To's, Tutorials, Overviews, + Examples, and Class Documentation. + + There are several types of predefined documentation \e categories or + \e types: + \list + \li How-To's + \li Tutorial + \li Overview + \li Article + \li FAQ (Frequently Asked Questions) + \li C++ API Documentation + \li QML Type Documentation + \li Code Example + \endlist + + QDoc has the ability to format a page depending on the type. Further, + stylesheets can provide additional control on the display of each category. + + \section1 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 + \l{qdoc-topics}{topic command}. QDoc will associate the documentation to the + source using C++ naming rules. + + QDoc will parse the header files (typically \c .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. + + \section2 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. + + \list + \li \l{C++ Documentation Style} + \li \l{QML Documentation Style} + \endlist + + \keyword qml-documentation + \section2 Documenting QML Types + + In the world of \l{Qt Quick}{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: + \list + \li \l{qmlattachedproperty-command}{\\qmlattachedproperty} + \li \l{qmlattachedsignal-command}{\\qmlattachedsignal} + \li \l{qmlvaluetype-command}{\\qmlvaluetype} + \li \l{qmltype-command}{\\qmltype} - creates a QML type documentation + \li \l{qmlmethod-command}{\\qmlmethod} + \li \l{qmlproperty-command}{\\qmlproperty} + \li \l{qmlsignal-command}{\\qmlsignal} + \li \l{inherits-command}{\\inherits} + \li \l{qmlmodule-command}{\\qmlmodule} + \li \l{inqmlmodule-command}{\\inqmlmodule} + \li \l{instantiates-command}{\\instantiates} + + \endlist + + \note Remember to enable QML parsing by including the \c{*.qml} filetype in + the \l{qdoc-input-output-dir}{fileextension} variable. + + To document a QML type, start by creating a QDoc comment that uses the + \l{qmltype-command} {\\qmltype} command as its topic command. + + \section3 QML Parser + + If your QML type is defined in a \e qml file, document it there. + If your QML type is represented by a C++ class, document it in the + \e cpp file for that C++ class and include an + \l{instantiates-command}{\\instantiates} command to specify the + name of the C++ class. Don't document a QML type in a \e{cpp} file + if the QML type is defined in a \e{qml} file. + + When documenting a QML type in a \e{qml} file, place each QDoc + comment directly above the entity to which the comment applies. + For example, place the QDoc comment containing the \e{\\qmltype} + command (the topic comment) directly above the outer QML type in + the \e{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 \e{qml} file, you don't normally include the + \e{\\qmlproperty} command as a topic command (which you must do + when documenting QML types in \e{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 \e{\\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 \e must contain a \e{\\qmlproperty} + command, because that is the only way QDoc can know the type of + the aliased property. + + When documenting a QML type in the \e 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 + \e{cpp} file. Note that QML QDoc comments in \e cpp files \e must + use the QML topic commands. i.e., the \l{qmltype-command} + {\\qmltype} command \e must appear in the QDoc comment for the + QML type, and a \l{qmlproperty-command} {\\qmlproperty} command \e + must appear in each QML property QDoc comment. + + \section3 QML Modules + + A QML type belongs to a \e module. The module + may include all the related types for a platform or contain a certain + version of \l{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 \l{qmltype-command} + {\\qmltype} topic command must have an \l{inqmlmodule-command} + {\\inqmlmodule} context command to relate the type to a QML + module. Similarly, a \l{qmlmodule-command}{\\qmlmodule} topic + command must exist in a separate \c{.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 \c TabWidget is in the \c UIComponents + module, it must be linked as \c {UIComponents::TabWidget}. + + \section3 Read-only and Internal QML Properties + + QDoc detects QML properties that are marked as \c readonly. Note that the + property must be initialized with a value. + + \badcode + readonly property int sampleReadOnlyProperty: 0 + \endcode + + Properties and signals that are not meant for the public interface may + be marked with the \l{internal-command}{\\internal} command. QDoc will not + publish the documentation in the generated outputs. + + \section1 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: + + \snippet examples/samples.qdocinc sample-overview + + The \l{writing-topic-commands}{writing topic commands} section has a listing + of the available \\page command arguments. + + \section1 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 (\e{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 \c type argument to the + \l{page-command}{\\page} command. The \c type argument is the second + argument, with the file name being the first. + \snippet examples/samples.qdocinc sample-faq + + The \l{writing-topic-commands}{writing topic commands} section has a listing + of the available \\page command arguments. + + \section1 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 \l{example-command}{\\example} command. + + \snippet examples/samples.qdocinc sample-example + + QDoc will use the directory specified in the input + \l{Input and Output Directories}{exampledirs} variable to find the Qt + Project (\c .pro) file to generate the example files. The generated HTML + will have the filename, \c {declarative-ui-components-tabwidget.html}. QDoc + will also list all of the example code. + + \note The example's project file must be the same as the + directory name. +*/ + + +/*! + \page qdoc-guide-clang.html + \title Installing Clang for QDoc + \previouspage Getting Started with QDoc + \nextpage Creating QDoc Configuration Files + + QDoc uses Clang when parsing C++ files as well as function signatures in + \l {fn-command} {\\fn} commands. Clang is part of + \l {https://llvm.org/}{the LLVM Compiler Infrastructure Project}. + If you're going to build QDoc from source, you must install + \l{http://clang.llvm.org}{Clang 15.0} or later. + + You can get Clang through various channels: + + \list + \li Qt provides the + \l{http://download.qt.io/development_releases/prebuilt/libclang/qt} + {prebuilt Clang packages} that are used for the Qt binaries in the + online installer. These let you link LLVM/Clang libraries statically, + but only support Release builds on Windows. + \li Linux distributions often provide a package called \e libclang-dev or + \e libclang-devel. Qt's build system instructs CMake to look for + \e {ClangConfig.cmake}, so make sure you install the package that + provides this file if you want to build QDoc. Running QDoc requires + only \e libclang. + \li On macOS, you can also use Homebrew's + \l{https://formulae.brew.sh/formula/llvm}{llvm formula}. + \endlist + + \note the prebuilt binaries from \l{http://releases.llvm.org/download.html} + cannot be used, as they miss certain components required by QDoc. + + If you install Clang in a custom location you need to tell CMake where + to find it. This can be done by specifying your LLVM installation path + using the \c LLVM_INSTALL_DIR environment variable when configuring Qt. + Alternatively, you can add the installation path to the \c CMAKE_PREFIX_PATH + CMake cache variable. +*/ |