An error occurred while loading the file. Please try again.
-
Simon Hausmann authored
With a growing number of functions per module, these calls become expensive and are unnecessary. defineFunction in the code generator can simply return the correct index right away. Change-Id: I8ab56a3083bf215674a1b46c502b415be694e465 Reviewed-by:Lars Knoll <lars.knoll@digia.com>
6b2b62e9
/******************************************************************************** Copyright (C) 2016 The Qt Company Ltd.** Contact: https://www.qt.io/licensing/**** This file is part of the documentation of the Qt Toolkit.**** $QT_BEGIN_LICENSE:FDL$** Commercial License Usage** Licensees holding valid commercial Qt licenses may use this file in** accordance with the commercial license agreement provided with the** Software or, alternatively, in accordance with the terms contained in** a written agreement between you and The Qt Company. For licensing terms** and conditions see https://www.qt.io/terms-conditions. For further** information use the contact form at https://www.qt.io/contact-us.**** GNU Free Documentation License Usage** Alternatively, this file may be used under the terms of the GNU Free** Documentation License version 1.3 as published by the Free Software** Foundation and appearing in the file included in the packaging of** this file. Please review the following information to ensure** the GNU Free Documentation License version 1.3 requirements** will be met: https://www.gnu.org/licenses/fdl-1.3.html.** $QT_END_LICENSE$******************************************************************************//*! \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 DITA 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 From Qt 5.11, \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} \endlist7172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140
\li \l{QML Documentation Example}
\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 DITA XML
format. The main distinction between the two outputs is that HTML
documentation needs to have its HTML styling information in the
configuration files. DITA XML documentation does not, and a separate process
can style the documentation in DITA at a later time. DITA XML is 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
141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210
\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. As well, 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 Qt Index Reference
211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280
Documentation projects can link to Qt APIs and other articles by specifying
the path to the \c qt.index file. When qdoc generates the Qt Reference
Documentation, it will also generate an index file, containing the URLs to
the articles. Other projects can use the links in the index file so that
they can link to other articles and API documentation within Qt.
\badcode
indexes = $QT_INSTALL_DOCS/html/qt.index $OTHER_PROJECT/html/qt.index
\endcode
It is possible to specify multiple index files from several projects.
\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.
\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++, QML, and JavaScript.
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.
281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350
\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
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 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 obsolete, then it should be marked obsolete
with the \l{obsolete-command}{\\obsolete} 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
351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420
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 obsolete functions when the documentation is
marked with \l{obsolete-command}{\\obsolete}.
\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 QML Documentation Example
\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
421422423424425426427428429430431432433434435436437438439440441442443444445446447448449450451452453454455456457458459460461462463464465466467468469470471472473474475476477478479480481482483484485486487488489490
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{qmlbasictype-command}{\\qmlbasictype}
\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