diff options
Diffstat (limited to 'src/tools/qdoc/doc')
| -rw-r--r-- | src/tools/qdoc/doc/images/link-to-qquickitem.png | bin | 0 -> 46571 bytes | |||
| -rw-r--r-- | src/tools/qdoc/doc/images/links-to-broken-links.png | bin | 0 -> 16569 bytes | |||
| -rw-r--r-- | src/tools/qdoc/doc/images/links-to-links.png | bin | 0 -> 10042 bytes | |||
| -rw-r--r-- | src/tools/qdoc/doc/images/qa-table.png | bin | 0 -> 7057 bytes | |||
| -rw-r--r-- | src/tools/qdoc/doc/qa-pages.qdoc | 109 | ||||
| -rw-r--r-- | src/tools/qdoc/doc/qdoc-manual-intro.qdoc | 149 | ||||
| -rw-r--r-- | src/tools/qdoc/doc/qdoc-manual-markupcmds.qdoc | 103 | ||||
| -rw-r--r-- | src/tools/qdoc/doc/qdoc-manual-qdocconf.qdoc | 9 | ||||
| -rw-r--r-- | src/tools/qdoc/doc/qdoc-manual.qdoc | 1 |
9 files changed, 363 insertions, 8 deletions
diff --git a/src/tools/qdoc/doc/images/link-to-qquickitem.png b/src/tools/qdoc/doc/images/link-to-qquickitem.png Binary files differnew file mode 100644 index 0000000000..00e03c3717 --- /dev/null +++ b/src/tools/qdoc/doc/images/link-to-qquickitem.png diff --git a/src/tools/qdoc/doc/images/links-to-broken-links.png b/src/tools/qdoc/doc/images/links-to-broken-links.png Binary files differnew file mode 100644 index 0000000000..775143bd4a --- /dev/null +++ b/src/tools/qdoc/doc/images/links-to-broken-links.png diff --git a/src/tools/qdoc/doc/images/links-to-links.png b/src/tools/qdoc/doc/images/links-to-links.png Binary files differnew file mode 100644 index 0000000000..9d2cc2fae5 --- /dev/null +++ b/src/tools/qdoc/doc/images/links-to-links.png diff --git a/src/tools/qdoc/doc/images/qa-table.png b/src/tools/qdoc/doc/images/qa-table.png Binary files differnew file mode 100644 index 0000000000..5818739fac --- /dev/null +++ b/src/tools/qdoc/doc/images/qa-table.png diff --git a/src/tools/qdoc/doc/qa-pages.qdoc b/src/tools/qdoc/doc/qa-pages.qdoc new file mode 100644 index 0000000000..d392877ecb --- /dev/null +++ b/src/tools/qdoc/doc/qa-pages.qdoc @@ -0,0 +1,109 @@ +/**************************************************************************** +** +** Copyright (C) 2013 Digia Plc and/or its subsidiary(-ies). +** Contact: http://www.qt-project.org/legal +** +** 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 Digia. For licensing terms and +** conditions see http://qt.digia.com/licensing. For further information +** use the contact form at http://qt.digia.com/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: http://www.gnu.org/copyleft/fdl.html. +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \page 28-qdoc-qa-pages.html + \previouspage Generating DITA XML Output + \contentspage QDoc Manual + \nextpage QDoc Manual + + \title QA Pages + + qdoc can generate some extra HTML pages that can be useful for + debugging qdoc documentation. These \e QA pages make it easier for + those who write documentation to find links that either go to the + wrong targets or don't go anywhere at all. + + \section2 Generating the QA Pages + + Add \c {-write-qa-pages} to the command line to tell qdoc to + generate the QA pages. If this option is not provided, the QA + pages will not be generated, and previolusly generated QA pages + will be deleted. + + \section2 Finding the Module's Main QA Page + + The main QA page for a module is not linked into the module's + generated documentation, but it is located in the same output + directory. To find the top-level QA page for module \e {xxx}, set + your browser to the qdoc output directory for module \e {xxx}. + Several files whose names begin with \e {aaa} appear at the top of + the list. These are the QA pages for module \e{xxx}. The file + names begin with \e {aaa} to ensure that they are easy to find at + the top of the directory. + + For module \e{xxx}, find the file \e{aaa-xxx-qa-page.html}. This + is the top-level QA page for module \e{xxx}. Load that file into + the browser. The top-level QA page shows a table that contains + links to several QA sub-pages. + + For example, the main QA page for QtCore is \c{aaa-qtcore-qa-page.html}. + This was the table for QtCore at one point: + + \image qa-table.png + + Each table entry shows the number of links from QtCore to some + other module, except for the last entry, which shows the number of + broken links in QtCore. Click the \b qtquick entry to load the QA + subpage showing the links from QtCore to QtQuick. + + \section2 Links To Links Page + + Clicking the \b qtquick table entry on the main QA page for QtCore + loads the QA subpage showing a table containing all the links from + QtCore to QtQuick. The table contains all the links constructed + with the \l {l-command} {\\l command}, as well as the autolinks. + + \image links-to-links.png + + At the time this table was generated, there were six links from + QtCore to QtQuick. The first column of each table entry contains + a link to some link in QtCore. The link text as it appears in + QtCore is shown. The second and third columns contain the source + file name and line number for where qdoc saw the link in a qdoc + comment. + + \note The line number will normally refer to the first line of the + comment where qdoc saw the link. + + Clicking on a link in the table takes you to that link in the + documentation. There the link will be marked with three red + asterisks. For example, clicking on the link in the fifth table + entry takes you here: + + \image link-to-qquickitem.png + + The link is marked with three red asterisks. Now you can click on + the actual link to check that it goes to the correct place. In + this case, the link should go to the reference page for the + QQuickItem class. You can check each link in the table this + way. If you find a link that goes to the wrong place, use the + source file name and line number to find the link, and fix the + problem using the square bracket notation for the \l {l-command} + {\\l command}. + + */ diff --git a/src/tools/qdoc/doc/qdoc-manual-intro.qdoc b/src/tools/qdoc/doc/qdoc-manual-intro.qdoc index 636cd6980e..3b7dda30f3 100644 --- a/src/tools/qdoc/doc/qdoc-manual-intro.qdoc +++ b/src/tools/qdoc/doc/qdoc-manual-intro.qdoc @@ -89,8 +89,8 @@ \section1 Running QDoc - The current name of the QDoc program is \c {qdoc}. To run qdoc - from the command line, give it the name of a configuration file: + The name of the QDoc program is \c {qdoc}. To run qdoc from the + command line, give it the name of a configuration file: \quotation \c {$ ../../bin/qdoc ./config.qdocconf} @@ -107,6 +107,151 @@ See \l{The QDoc Configuration File} for instructions on how to set up a QDoc configuration file. + \section2 Running QDoc in Single Execution Mode + + Beginning with Qt 5.5, a new way to run QDoc is available that + reduces the time it takes to generate the Qt5 documentation by as + much as 90%. The new way to run QDoc is \e{single execution} mode. + Single execution mode is not currently available in the Qt5 build + system, which still uses the \e {standard} mode. Single execution + mode is only available when you run QDoc yourself, which you will + want to do often as you document your module and integrate your + documentation with the other Qt modules. + + To run QDoc in single execution mode, add \c {-single-exec} to the + command line and pass QDoc a master \c qdocconf file that is + simply a list of file paths for qdocconf files of all the Qt5 + modules. For example: + + \code + /Users/me/qt5/qtbase/bin/qdoc -outputdir /Users/me/qt5/qtbase/doc -installdir /Users/me/qt5/qtbase/doc /Users/me/qt5/master.qdocconf -single-exec + \endcode + + The qdocconf file, \c {master.qdocconf}, just lists the qdocconf files for all the Qt5 modules to be processed: + + \badcode + /Users/me/qt5/qtbase/src/corelib/doc/qtcore.qdocconf + /Users/me/qt5/qtbase/src/network/doc/qtnetwork.qdocconf + /Users/me/qt5/qtbase/src/sql/doc/qtsql.qdocconf + /Users/me/qt5/qtbase/src/xml/doc/qtxml.qdocconf + /Users/me/qt5/qtbase/src/testlib/doc/qttestlib.qdocconf + /Users/me/qt5/qtbase/src/concurrent/doc/qtconcurrent.qdocconf + /Users/me/qt5/qtbase/src/gui/doc/qtgui.qdocconf + /Users/me/qt5/qtbase/src/platformheaders/doc/qtplatformheaders.qdocconf + /Users/me/qt5/qtbase/src/widgets/doc/qtwidgets.qdocconf + /Users/me/qt5/qtbase/src/opengl/doc/qtopengl.qdocconf + /Users/me/qt5/qtbase/src/printsupport/doc/qtprintsupport.qdocconf + /Users/me/qt5/qtbase/src/tools/qdoc/doc/config/qdoc.qdocconf + /Users/me/qt5/qtbase/qmake/doc/qmake.qdocconf + /Users/me/qt5/qtsvg/src/svg/doc/qtsvg.qdocconf + /Users/me/qt5/qtxmlpatterns/src/xmlpatterns/doc/qtxmlpatterns.qdocconf + /Users/me/qt5/qtdeclarative/src/qml/doc/qtqml.qdocconf + /Users/me/qt5/qtdeclarative/src/quick/doc/qtquick.qdocconf + /Users/me/qt5/qtquickcontrols/src/controls/doc/qtquickcontrols.qdocconf + /Users/me/qt5/qtquickcontrols/src/layouts/doc/qtquicklayouts.qdocconf + /Users/me/qt5/qtquickcontrols/src/dialogs/doc/qtquickdialogs.qdocconf + /Users/me/qt5/qtmultimedia/src/multimedia/doc/qtmultimedia.qdocconf + /Users/me/qt5/qtmultimedia/src/multimediawidgets/doc/qtmultimediawidgets.qdocconf + /Users/me/qt5/qtactiveqt/src/activeqt/doc/activeqt.qdocconf + /Users/me/qt5/qtsensors/src/sensors/doc/qtsensors.qdocconf + /Users/me/qt5/qtwebkit/Source/qtwebkit.qdocconf + /Users/me/qt5/qttools/src/assistant/help/doc/qthelp.qdocconf + /Users/me/qt5/qttools/src/assistant/assistant/doc/qtassistant.qdocconf + /Users/me/qt5/qttools/src/designer/src/uitools/doc/qtuitools.qdocconf + /Users/me/qt5/qttools/src/designer/src/designer/doc/qtdesigner.qdocconf + /Users/me/qt5/qttools/src/linguist/linguist/doc/qtlinguist.qdocconf + /Users/me/qt5/qtwebkit-examples/doc/qtwebkitexamples.qdocconf + /Users/me/qt5/qtimageformats/src/imageformats/doc/qtimageformats.qdocconf + /Users/me/qt5/qtgraphicaleffects/src/effects/doc/qtgraphicaleffects.qdocconf + /Users/me/qt5/qtscript/src/script/doc/qtscript.qdocconf + /Users/me/qt5/qtscript/src/scripttools/doc/qtscripttools.qdocconf + /Users/me/qt5/qtserialport/src/serialport/doc/qtserialport.qdocconf + /Users/me/qt5/qtdoc/doc/config/qtdoc.qdocconf + \endcode + + \section3 Why Standard Mode Is Slow + + Currently, the Qt5 build system does not use QDoc's \e {single + execution} mode for generating the Qt5 documentation. It runs QDoc + in the \e {standard} mode. The standard mode was came about + because it was the easiest way to get convert the Qt4 QDoc to + handle the modularization of Qt in Qt5. In Qt4, QDoc ran once over + all the Qt4 sources to generate the HTML documentation for Qt. + While generating the Qt documentation, Qt4 QDoc also generated an + \e {index file} for Qt. That index file was meant to be used as + input to subsequent QDoc runs for generating HTML documentation + for other software libraries/products that were based on Qt. The + Qt index file allowed QDoc to link documentation written for those + other libraries/products to the Qt4 documentation. + + When Qt5 came along, Qt was divided into modules. Since then, + many new modules have been added to Qt. As of version 5.5, there + are over 40 separate modules in Qt5, each with its own + documentation that links to (depends on) the documentation of + other Qt modules. + + In \e {standard mode}, QDoc runs twice for each module. The first + QDoc run for a particular Qt module, parses all the module's + source files and then uses the information to generate the + module's index file. It is called the \e{prepare phase} because + it \e prepares the module's index file. The second QDoc run for + the module also parses all the module's source files and then + generates the module's documentation pages. This is called the \e + {generate phase} because it generates the module's documentation. + + The module's documentation will likely contain HTML links to the + documentation of one or more of the other Qt modules. For example, + most Qt5 modules contain links to documentation in QtCore. When a + Qt module contains links into the documentation of other Qt + module's, that module is said to depend on those other Qt modules. + Hence when QDoc runs the \e {generate phase} for that module, it + must also load the index files for those modules so it can create + those thinks. + + Hence, when the Qt build system generates the Qt documentation, it + first runs QDoc once for each module to perform the \e {prepare + phase} to generate all the index files. Then it runs QDoc once for + each module to perform the \e {generate phase}, where it uses the + dependent index files to generate the module's documentation, + including any cross-module links it finds. Each execution of + QDoc, both \e {prepare phase} and \e {generate phase}, parses + all the source files that are included in the module, and in the + \e {generate phase} also parses the index files for the dependent + modules. Nothing is retained or retainable between QDoc runs. + + \section3 Why Single Execution Mode Is Much Faster + + As the name implies, single execution mode uses a single QDoc + process to generate all the Qt5 documentation. The single QDoc + process still performs a \e{prepare phase} for each module and + then a \e{generate phase} for each module, but there are a few + differences. It begins by reading the master qdocconf file. Then + it reads each qdocconf file in the master list and performs the + \e{prepare phase} for each module. During the \e{prepare phase}, + all the source files for the module are parsed to build a syntax + tree for the module. The module's index file is then generated, + although QDoc will not re-read the index files in the \e{generate + phase}. The important difference here is that the module's syntax + tree is retained after the index file is generated, so that after + the \e{prepare phase} has been run for all the modules, QDoc still + has all the syntax trees it built. + + QDoc then processes each module again for the \e{generate phase}. + But now QDoc doesn't need to re-parse each module's source files, + because the module's syntax tree is still in memory. Nor does QDoc + need to re-read the index files for the dependent modules, again + because it still has the syntax trees for those modules in memry. + It remains only to traverse each module's syntax tree to generate + the documentation pages. + + Hence, QDoc parses each source file once and only once and doesn't + need to read index files. This is what makes single execution mode + much faster than the standard mode. It is anticipated that the Qt + build system will eventually run QDoc in single execution mode. + However, changes to the master qdocconf file might be required, so + the method described above for running QDoc in single execution + mode might have to change, watch this space for updates. + \section1 How QDoc Works QDoc begins by reading the configuration file you specified on the diff --git a/src/tools/qdoc/doc/qdoc-manual-markupcmds.qdoc b/src/tools/qdoc/doc/qdoc-manual-markupcmds.qdoc index 7825fc3a91..bcad595f72 100644 --- a/src/tools/qdoc/doc/qdoc-manual-markupcmds.qdoc +++ b/src/tools/qdoc/doc/qdoc-manual-markupcmds.qdoc @@ -1771,9 +1771,15 @@ different kinds of targets. The command's general syntax is: \code - \l {link target} {link text} + \l [ link criteria ] { link target } { link text } \endcode + ...where the \c {link criteria} in square brackets are optional + but may be required when the \c {link target} is ambiguous. See + \l {Fixing Ambiguous Links} below. + + Here is an example using the \\l command to link to an external page: + \code / *! Read the \l {http://qt-project.org/doc/qt-5.0/} @@ -1877,6 +1883,101 @@ \l {QWidget::} {sizeHint()} \endquotation + \section2 Fixing Ambiguous Links + + Because of the modularization of Qt beginning with Qt 5.0, The + possibility that qdoc will have to deal with ambiguous links has + increased. An ambiguous link is one that has a matching target in + more than one Qt module, e.g. the same section title can appear in + more than one Qt module, or the name of a C++ class in one module + can also be the name of a QML type in another module. A real + example in Qt5 is the name Qt itself. Qt is the name of both a C++ + namespace in QtCore and a QML type in QtQml. + + Suppose we want to link to the \l {Qt} {Qt C++ namespace}. At the + time qdoc generated this HTML page, that link was correct. Does + it still go to the C++ namespace? Qdoc generated that link from + this link command: + + \list + \li \c {\l {Qt} {Qt C++ namespace}} + \endlist + + Now suppose we want to link to the \l [QML] {Qt} {Qt QML type}. + At the time qdoc generated this HTML page, that link was also + correct, but we had to use this link command: + + \list + \li \c {\l [QML] {Qt} {Qt QML type}} + \endlist + + The \e {QML} in \e {square brackets} tells qdoc to accept a + matching target only if the traget is on a QML page. Qdoc actually + finds the C++ namespace target first, but since that target is on + a C++ page, qdoc ignores it and keeps looking until it finds the + same target on a QML page. + + Without the guidance in the \e{\\l command} in the optional \e + {square bracket} argument, qdoc links to the first matching target + it finds. qdoc can't warn that the link was ambiguous in such + cases because it doesn't know that another matching target exists. + + \section2 What arguments can appear in square brackets? + + A link command with square bracket argument has the following syntax: + \list + \c {\l [QML|CPP|DOC|QtModuleName] {link target} {link text}} + \endlist + + The \e {square bracket} argument is only allowed in the \c {\\l + (link)} command. The example above shows how \c QML is used as the + \e {square brackets} argument to force qdoc to match a QML target. + Most often, this will be a QML type, but it can also be a QML + member function of property. + + In the example, qdoc didn't need a \e {square bracket} argument to + find the Qt C++ namespace page, because that one was the first + matching target qdoc found anyway. However, to force qdoc to find + a C++ target when a matching QML target gets in the way, \c CPP + can be used as the \e {square bracket} argument. For example: + + \list + \li \c {\l [CPP] {Qt} {Qt C++ namespace}} + \endlist + + ...will force qdoc to ignore the Qt QML type and continue + searching until it matches the Qt C++ namespace. + + If the link target is neither a C++ nor a QML entity, \c {DOC} can + be used as the \e {square bracket} argument to prevent qdoc from + matching either of those. At this writing, there were no cases of + ambiguous links where using \c {DOC} was required. + + Often, the documentor knows which Qt module the link target is + in. When the module name is known, use the module name as the \e + {square bracket} argument. In the example above, if we know that + the QML type named Qt is located in the QtQml module, we can write + the link command like this: + + \list + \li \c {\l [QtQml] {Qt} {Qt QML type}} + \endlist + + When a module name is used as the \e {square bracket} argument, + qdoc will search for link the target in that module only. This + makes searching for link targets more efficient. + + Finally, the module name and entity type arguments can be + combined, separated by a blank, so something like this is also + allowed: + + \list + \li \c {\l [CPP QtQml] {Window} {C++ class Window}} + \endlist + + As of this writing, there were no cases where combining the two + was required. + See also \l {sa-command} {\\sa}, \l {target-command} {\\target}, and \l {keyword-command} {\\keyword}. diff --git a/src/tools/qdoc/doc/qdoc-manual-qdocconf.qdoc b/src/tools/qdoc/doc/qdoc-manual-qdocconf.qdoc index cf1f7b2426..da381f1326 100644 --- a/src/tools/qdoc/doc/qdoc-manual-qdocconf.qdoc +++ b/src/tools/qdoc/doc/qdoc-manual-qdocconf.qdoc @@ -204,7 +204,6 @@ QT_.*_LIB \ QT_COMPAT \ QT3_SUPPORT \ - Q_WS_.* \ Q_OS_.* \ Q_BYTE_ORDER \ __cplusplus @@ -214,14 +213,14 @@ symbols to be defined. For example: \code - #ifdef Q_WS_WIN + #ifdef Q_OS_WIN HDC getDC() const; void releaseDC(HDC) const; #endif \endcode - Since the Q_WS_.* regular expression (specified using the \c - defines variable) matches Q_WS_WIN, QDoc will process the code + Since the Q_OS_.* regular expression (specified using the \c + defines variable) matches Q_OS_WIN, QDoc will process the code within #ifdef and #endif in our example. You can also define preprocessor symbols manually on the command @@ -1531,7 +1530,7 @@ \page 21-3-qt-dita-xml-output.html \previouspage minimum.qdocconf \contentspage QDoc Manual - \nextpage QDoc Manual + \nextpage QA Pages \title Generating DITA XML Output diff --git a/src/tools/qdoc/doc/qdoc-manual.qdoc b/src/tools/qdoc/doc/qdoc-manual.qdoc index 485faba70f..e6f335097a 100644 --- a/src/tools/qdoc/doc/qdoc-manual.qdoc +++ b/src/tools/qdoc/doc/qdoc-manual.qdoc @@ -70,6 +70,7 @@ \li \l {minimum.qdocconf} \li \l {Generating DITA XML Output} \endlist + \li \l {QA Pages} \endlist */ |
