1berry/qtbase
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Doc: Fix various issues in QDoc Manual

Browse Source 
- Fix QDoc warnings for broken links
    - Use \badcode for code snippets that are not C++ or QML code
    - Remove/update obsolete information

Change-Id: Ie5ce6ec588709059fc7ba7b47e0cc8ad5385c42f
Reviewed-by: Martin Smith <martin.smith@digia.com>
This commit is contained in:
Topi Reinio 2015-07-24 13:56:41 +02:00 committed by Topi Reiniö
parent 3714c9b3fe
commit d337a8d306
7 changed files with 147 additions and 170 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

7
src/tools/qdoc/doc/examples/examples.qdoc
View File

@ -89,10 +89,9 @@
\title UI Components \title UI Components
\brief Basic set of UI components \brief Basic set of UI components
This is a listing of a list of UI components implemented by QML types. These This is a listing of a list of UI components implemented by QML types.
These files are available for general import and they are based off the
files are available for general import and they are based off the \l{Qt \e {Qt Quick Code Samples}.
Quick Code Samples}.
This module is part of the \l{componentset}{UIComponents} example. This module is part of the \l{componentset}{UIComponents} example.
*/ */

37
src/tools/qdoc/doc/qdoc-guide/qdoc-guide.qdoc
View File

@ -112,7 +112,7 @@
Specifying the path to the source directories allow QDoc to find sources and Specifying the path to the source directories allow QDoc to find sources and
generate documentation. generate documentation.
\code \badcode
sourcedirs = <path to source code> sourcedirs = <path to source code>
exampledirs = <path to examples directory> exampledirs = <path to examples directory>
imagedirs = <path to image directory> imagedirs = <path to image directory>
@ -129,7 +129,7 @@
Likewise, QDoc needs the path to the output directory. The \c outputformats Likewise, QDoc needs the path to the output directory. The \c outputformats
variable determines the type of documentation. These variables should be variable determines the type of documentation. These variables should be
in separate configuration files to modularize the documentation build. in separate configuration files to modularize the documentation build.
\code \badcode
outputdir = $SAMPLE_PROJECT/doc/html outputdir = $SAMPLE_PROJECT/doc/html
outputformats = HTML outputformats = HTML
\endcode \endcode
@ -144,8 +144,8 @@
the \l{Input and Output Directories}{output} directory. It is also possible the \l{Input and Output Directories}{output} directory. It is also possible
to specify extra files that QDoc should export. to specify extra files that QDoc should export.
\code \badcode
extraimages.HTML = extraImage.png \ HTML.extraimages = extraImage.png \
extraImage2.png extraImage2.png
\endcode \endcode
@ -169,7 +169,7 @@
generated documentation into the directory specified by the \c outputdir generated documentation into the directory specified by the \c outputdir
variable. variable.
\code \badcode
outputformats = HTML outputformats = HTML
outputdir = <path to output directory> outputdir = <path to output directory>
\endcode \endcode
@ -178,12 +178,12 @@
are located. Typically, the templates directory contains a \c scripts, are located. Typically, the templates directory contains a \c scripts,
\c images, and a \c style directory, containing scripts and CSS files. \c images, and a \c style directory, containing scripts and CSS files.
\code \badcode
HTML.templatedir = <path to templates> HTML.templatedir = <path to templates>
\endcode \endcode
The main configuration variables are: The main configuration variables are:
\code \badcode
HTML.postheader HTML.postheader
HTML.postpostheader HTML.postpostheader
HTML.postheader HTML.postheader
@ -210,7 +210,7 @@
documentation, QDoc does not need HTML style templates for generating documentation, QDoc does not need HTML style templates for generating
documentation in DITA XML format. documentation in DITA XML format.
\code \badcode
outputformats = DITAXML outputformats = DITAXML
outputdir outputdir
\endcode \endcode
@ -222,7 +222,7 @@
the articles. Other projects can use the links in the index file so that 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. they can link to other articles and API documentation within Qt.
\code \badcode
indexes = $QT_INSTALL_DOCS/html/qt.index $OTHER_PROJECT/html/qt.index indexes = $QT_INSTALL_DOCS/html/qt.index $OTHER_PROJECT/html/qt.index
\endcode \endcode
It is possible to specify multiple index files from several projects. It is possible to specify multiple index files from several projects.
@ -232,7 +232,7 @@
Macros for substituting HTML characters exist and are helpful for generating Macros for substituting HTML characters exist and are helpful for generating
specific HTML-valid characters. specific HTML-valid characters.
\code \badcode
macro.pi.HTML = "&Pi;" macro.pi.HTML = "&Pi;"
\endcode \endcode
The snippet code will replace any instances of \c{\\pi} with \c &Pi; in the The snippet code will replace any instances of \c{\\pi} with \c &Pi; in the
@ -245,18 +245,17 @@
with the QML extension, \c{.qml}, if the extension type is included in the with the QML extension, \c{.qml}, if the extension type is included in the
\l{Input and Output Directories}{fileextensions} variable. \l{Input and Output Directories}{fileextensions} variable.
Also, the generated HTML files can have a prefix, specified in the QDoc Also, the generated HTML files can have a prefix and a suffix following the
configuration file. QML module name, specified in the QDoc configuration file.
\code \badcode
outputprefixes = QML outputprefixes = QML
outputprefixes.QML = uicomponents- outputprefixes.QML = uicomponents-
outputsuffixes = QML
outputsuffixes.QML = -tp
\endcode \endcode
The outputprefixes will, for example, prefix QML type HTML filenames.
\code \b {See also}: \l {outputprefixes-variable}{outputprefixes},
files: \l {outputsuffixes-variable}{outputsuffixes}.
uicomponents-button.html
uicomponents-scrollbar.html
\endcode
*/ */

4
src/tools/qdoc/doc/qdoc-manual-contextcmds.qdoc
View File

@ -77,7 +77,7 @@
\page 15-qdoc-commands-navigation.html \page 15-qdoc-commands-navigation.html
\previouspage Context Commands \previouspage Context Commands
\contentspage QDoc Manual \contentspage QDoc Manual
\nextpage Reporting Status \nextpage Status
\title Document Navigation \title Document Navigation
@ -522,7 +522,7 @@
/*! /*!
\page 17-qdoc-commands-thread.html \page 17-qdoc-commands-thread.html
\previouspage Reporting Status \previouspage Status
\contentspage QDoc Manual \contentspage QDoc Manual
\nextpage Relating Things \nextpage Relating Things

129
src/tools/qdoc/doc/qdoc-manual-qdocconf.qdoc
View File

@ -69,14 +69,14 @@
you to use special characters like '=' and ' \" ' within the value you to use special characters like '=' and ' \" ' within the value
string, for example: string, for example:
\code \badcode
HTML.postheader = "<a href=\"index.html\">Home</a>" HTML.postheader = "<a href=\"index.html\">Home</a>"
\endcode \endcode
If an entry spans many lines, use a backslash at the end of every If an entry spans many lines, use a backslash at the end of every
line but the last: line but the last:
\code \badcode
sourcedirs = kernel \ sourcedirs = kernel \
tools \ tools \
widgets widgets
@ -163,7 +163,7 @@
The general syntax is \tt {alias.\e{original-command-name} = \e The general syntax is \tt {alias.\e{original-command-name} = \e
temporary-command-name}. temporary-command-name}.
\code \badcode
alias.e = i alias.e = i
\endcode \endcode
@ -200,7 +200,7 @@
for details). By default, no symbol is defined, meaning that code for details). By default, no symbol is defined, meaning that code
protected with #ifdef...#endif will be ignored. protected with #ifdef...#endif will be ignored.
\code \badcode
defines = Q_QDOC \ defines = Q_QDOC \
QT_.*_SUPPORT \ QT_.*_SUPPORT \
QT_.*_LIB \ QT_.*_LIB \
@ -228,7 +228,7 @@
You can also define preprocessor symbols manually on the command You can also define preprocessor symbols manually on the command
line using the -D option. For example: line using the -D option. For example:
\code \badcode
currentdirectory$ qdoc -Dconsoleedition qtgui.qdocconf currentdirectory$ qdoc -Dconsoleedition qtgui.qdocconf
\endcode \endcode
@ -251,7 +251,7 @@
The \c edition variable is always used with a particular edition The \c edition variable is always used with a particular edition
name to define the modules for that edition: name to define the modules for that edition:
\code \badcode
edition.Console = QtCore QtNetwork QtSql QtXml edition.Console = QtCore QtNetwork QtSql QtXml
edition.Desktop = QtCore QtGui QtNetwork QtOpenGL QtSql QtXml \ edition.Desktop = QtCore QtGui QtNetwork QtOpenGL QtSql QtXml \
QtDesigner QtAssistant Qt3Support QAxContainer \ QtDesigner QtAssistant Qt3Support QAxContainer \
@ -265,7 +265,7 @@
{generatelist} command is used to generate a list of classes for {generatelist} command is used to generate a list of classes for
this edition: this edition:
\code \badcode
\generatelist{classesbyedition Console} \generatelist{classesbyedition Console}
\endcode \endcode
@ -288,7 +288,7 @@
and accept the first matching file it finds. It will only search and accept the first matching file it finds. It will only search
in the specified directories, \e not in subdirectories. in the specified directories, \e not in subdirectories.
\code \badcode
exampledirs = $QTDIR/doc/src \ exampledirs = $QTDIR/doc/src \
$QTDIR/examples \ $QTDIR/examples \
$QTDIR \ $QTDIR \
@ -299,7 +299,7 @@
When processing When processing
\code \badcode
\quotefromfile widgets/calculator/calculator.cpp \quotefromfile widgets/calculator/calculator.cpp
\endcode \endcode
@ -308,13 +308,13 @@
there isn't, it will search in the \c exampledirs variable, and there isn't, it will search in the \c exampledirs variable, and
first see if there exists a file called first see if there exists a file called
\code \badcode
$QTDIR/doc/src/widgets/calculator/calculator.cpp $QTDIR/doc/src/widgets/calculator/calculator.cpp
\endcode \endcode
If it doesn't, QDoc will continue looking for a file called If it doesn't, QDoc will continue looking for a file called
\code \badcode
$QTDIR/examples/widgets/calculator/calculator.cpp $QTDIR/examples/widgets/calculator/calculator.cpp
\endcode \endcode
@ -345,7 +345,7 @@
exampledirs} command. But note that if you know the file is listed exampledirs} command. But note that if you know the file is listed
in the \c examples variable, you don't need to specify its path: in the \c examples variable, you don't need to specify its path:
\code \badcode
\quotefromfile calculator.cpp \quotefromfile calculator.cpp
\endcode \endcode
@ -364,7 +364,7 @@
The extensions are given as standard wildcard expressions. You The extensions are given as standard wildcard expressions. You
can add a file extension to the filter using '+='. For example: can add a file extension to the filter using '+='. For example:
\code \badcode
examples.fileextensions += *.qrc examples.fileextensions += *.qrc
\endcode \endcode
@ -380,7 +380,7 @@
For example: For example:
\code \badcode
sourcedirs = src/corelib sourcedirs = src/corelib
excludedirs = src/corelib/tmp excludedirs = src/corelib/tmp
\endcode \endcode
@ -397,7 +397,7 @@
The \c excludefiles variable allows you to specify individual files The \c excludefiles variable allows you to specify individual files
that should \e{not} be processed by qdoc. that should \e{not} be processed by qdoc.
\code \badcode
excludefiles += $QT_CORE_SOURCES/../../src/widgets/kernel/qwidget.h \ excludefiles += $QT_CORE_SOURCES/../../src/widgets/kernel/qwidget.h \
$QT_CORE_SOURCES/../../src/widgets/kernel/qwidget.cpp $QT_CORE_SOURCES/../../src/widgets/kernel/qwidget.cpp
\endcode \endcode
@ -429,7 +429,7 @@
reason, these images are specified using the \c extraimages reason, these images are specified using the \c extraimages
variable: variable:
\code \badcode
extraimages.HTML = qt-logo extraimages.HTML = qt-logo
\endcode \endcode
@ -470,7 +470,7 @@
preprocessor symbol is specified within the \c falsehoods variable preprocessor symbol is specified within the \c falsehoods variable
entry: entry:
\code \badcode
falsehoods = NOTYET falsehoods = NOTYET
\endcode \endcode
@ -496,7 +496,7 @@
the header files associated with the \c .cpp source files used in the header files associated with the \c .cpp source files used in
the documentation. the documentation.
\code \badcode
headerdirs = $QTDIR/src \ headerdirs = $QTDIR/src \
$QTDIR/extensions/activeqt \ $QTDIR/extensions/activeqt \
$QTDIR/extensions/motif \ $QTDIR/extensions/motif \
@ -538,7 +538,7 @@
files in addition to those located in the directories specified by files in addition to those located in the directories specified by
the \l {headerdirs} {\c headerdirs} variable. the \l {headerdirs} {\c headerdirs} variable.
\code \badcode
headers = $QTDIR/src/gui/widgets/qlineedit.h \ headers = $QTDIR/src/gui/widgets/qlineedit.h \
$QTDIR/src/gui/widgets/qpushbutton.h $QTDIR/src/gui/widgets/qpushbutton.h
\endcode \endcode
@ -568,7 +568,7 @@
The extensions are given as standard wildcard expressions. You The extensions are given as standard wildcard expressions. You
can add a file extension to the filter using '+='. For example: can add a file extension to the filter using '+='. For example:
\code \badcode
header.fileextensions += *.H header.fileextensions += *.H
\endcode \endcode
@ -592,7 +592,7 @@
and accept the first matching file it finds. It will only search and accept the first matching file it finds. It will only search
in the specified directories, \e not in subdirectories. in the specified directories, \e not in subdirectories.
\code \badcode
imagedirs = $QTDIR/doc/src/images \ imagedirs = $QTDIR/doc/src/images \
$QTDIR/examples $QTDIR/examples
@ -601,7 +601,7 @@
When processing When processing
\code \badcode
\image calculator-example.png \image calculator-example.png
\endcode \endcode
@ -610,13 +610,13 @@
variable. If there isn't, it will search in the \c imagedirs variable. If there isn't, it will search in the \c imagedirs
variable for: variable for:
\code \badcode
$QTDIR/doc/src/images/calculator-example.png $QTDIR/doc/src/images/calculator-example.png
\endcode \endcode
If the file doesn't exist, QDoc will look for a file called If the file doesn't exist, QDoc will look for a file called
\code \badcode
$QTDIR/examples/calculator-example.png $QTDIR/examples/calculator-example.png
\endcode \endcode
@ -638,7 +638,7 @@
files in addition to those located in the directories specified by files in addition to those located in the directories specified by
the \l {imagedirs} {\c imagedirs} variable. the \l {imagedirs} {\c imagedirs} variable.
\code \badcode
images = $QTDIR/doc/src/images/calculator-example.png images = $QTDIR/doc/src/images/calculator-example.png
\endcode \endcode
@ -662,7 +662,7 @@
The idea is to enable different image format for different output The idea is to enable different image format for different output
format. format.
\code \badcode
images.fileextensions.HTML = *.png images.fileextensions.HTML = *.png
images.fileextensions.LOUT = *.eps images.fileextensions.LOUT = *.eps
\endcode \endcode
@ -681,7 +681,7 @@
You can add a file extension to the filter using '+='. For You can add a file extension to the filter using '+='. For
example: example:
\code \badcode
images.fileextensions.HTML += *.eps images.fileextensions.HTML += *.eps
\endcode \endcode
@ -698,7 +698,7 @@
specified. However, a possible example of a language variable specified. However, a possible example of a language variable
statement: statement:
\code \badcode
language = Cpp language = Cpp
\endcode \endcode
@ -717,7 +717,7 @@
appending \c {.DITAXML} to the macro name, the macro is only used appending \c {.DITAXML} to the macro name, the macro is only used
when generating DITA XML. when generating DITA XML.
\code \badcode
macro.gui = "\\b" macro.gui = "\\b"
macro.raisedaster.HTML = "<sup>*</sup>" macro.raisedaster.HTML = "<sup>*</sup>"
\endcode \endcode
@ -743,7 +743,7 @@
The \c naturallanguage variable specifies the natural language The \c naturallanguage variable specifies the natural language
used for the documentation generated by qdoc. used for the documentation generated by qdoc.
\code \badcode
naturallanguage = zh-Hans naturallanguage = zh-Hans
\endcode \endcode
@ -766,7 +766,7 @@
The \c outputdir variable specifies the directory where QDoc will The \c outputdir variable specifies the directory where QDoc will
put the generated documentation. put the generated documentation.
\code \badcode
outputdir = $QTDIR/doc/html outputdir = $QTDIR/doc/html
\endcode \endcode
@ -774,7 +774,7 @@
$QTDIR/doc/html. For example, the documentation of the QWidget $QTDIR/doc/html. For example, the documentation of the QWidget
class is located in class is located in
\code \badcode
$QTDIR/doc/html/qwidget.html $QTDIR/doc/html/qwidget.html
\endcode \endcode
@ -789,7 +789,7 @@
The \c outputencoding variable specifies the encoding used for the The \c outputencoding variable specifies the encoding used for the
documentation generated by qdoc. documentation generated by qdoc.
\code \badcode
outputencoding = UTF-8 outputencoding = UTF-8
\endcode \endcode
@ -874,7 +874,7 @@
The \c sourcedirs variable specifies the directories containing The \c sourcedirs variable specifies the directories containing
the \c .cpp or \c .qdoc files used in the documentation. the \c .cpp or \c .qdoc files used in the documentation.
\code \badcode
sourcedirs += .. \ sourcedirs += .. \
../../../examples/gui/doc/src ../../../examples/gui/doc/src
\endcode \endcode
@ -910,7 +910,7 @@
The \c sourceencoding variable specifies the encoding used for the The \c sourceencoding variable specifies the encoding used for the
source code and documentation. source code and documentation.
\code \badcode
sourceencoding = UTF-8 sourceencoding = UTF-8
\endcode \endcode
@ -935,7 +935,7 @@
files in addition to those located in the directories specified by files in addition to those located in the directories specified by
the \l {sourcedirs-variable} {sourcedirs} variable. the \l {sourcedirs-variable} {sourcedirs} variable.
\code \badcode
sources = $QTDIR/src/gui/widgets/qlineedit.cpp \ sources = $QTDIR/src/gui/widgets/qlineedit.cpp \
$QTDIR/src/gui/widgets/qpushbutton.cpp $QTDIR/src/gui/widgets/qpushbutton.cpp
\endcode \endcode
@ -964,7 +964,7 @@
The extensions are given as standard wildcard expressions. You The extensions are given as standard wildcard expressions. You
can add a file extension to the filter using '+='. For example: can add a file extension to the filter using '+='. For example:
\code \badcode
sources.fileextensions += *.CC sources.fileextensions += *.CC
\endcode \endcode
@ -981,7 +981,7 @@
output. The warnings are specified using standard wildcard output. The warnings are specified using standard wildcard
expressions. expressions.
\code \badcode
spurious = "Cannot find .*" \ spurious = "Cannot find .*" \
"Missing .*" "Missing .*"
\endcode \endcode
@ -990,8 +990,8 @@
will not be part of the output when running QDoc. For example will not be part of the output when running QDoc. For example
would the following warning be omitted from the output: would the following warning be omitted from the output:
\code \badcode
qt-4.0/src/opengl/qgl_mac.cpp:156: Missing parameter name src/opengl/qgl_mac.cpp:156: Missing parameter name
\endcode \endcode
\target syntaxhighlighting \target syntaxhighlighting
@ -1001,7 +1001,7 @@
perform syntax highlighting on source code quoted in the perform syntax highlighting on source code quoted in the
documentation it generates. documentation it generates.
\code \badcode
syntaxhighlighting = true syntaxhighlighting = true
\endcode \endcode
@ -1013,7 +1013,7 @@
The \c tabsize variable defines the size of a tab character. The \c tabsize variable defines the size of a tab character.
\code \badcode
tabsize = 4 tabsize = 4
\endcode \endcode
@ -1032,8 +1032,8 @@
The \c version variable specifies the version number of the The \c version variable specifies the version number of the
documented software. documented software.
\code \badcode
version = 4.0.1 version = 5.6.0
\endcode \endcode
When a version number is specified (using the \tt{\l version} or When a version number is specified (using the \tt{\l version} or
@ -1052,13 +1052,13 @@
The \c versionsym variable specifies a C++ preprocessor symbol The \c versionsym variable specifies a C++ preprocessor symbol
that defines the version number of the documented software. that defines the version number of the documented software.
\code \badcode
versionsym = QT_VERSION_STR versionsym = QT_VERSION_STR
\endcode \endcode
QT_VERSION_STR is defined in qglobal.h as follows QT_VERSION_STR is defined in qglobal.h as follows
\code \badcode
#define QT_VERSION_STR "4.0.1" #define QT_VERSION_STR "4.0.1"
\endcode \endcode
@ -1226,7 +1226,7 @@
Cpp.ignoredirectives} variables, non-standard constructs Cpp.ignoredirectives} variables, non-standard constructs
(typically macros) can result in erroneous documentation. (typically macros) can result in erroneous documentation.
\code \badcode
Cpp.ignoredirectives = Q_DECLARE_INTERFACE \ Cpp.ignoredirectives = Q_DECLARE_INTERFACE \
Q_DECLARE_OPERATORS_FOR_FLAGS \ Q_DECLARE_OPERATORS_FOR_FLAGS \
Q_DECLARE_PRIVATE \ Q_DECLARE_PRIVATE \
@ -1280,7 +1280,7 @@
In \l qtgui.qdocconf: In \l qtgui.qdocconf:
\code \badcode
Cpp.ignoretokens = QAXFACTORY_EXPORT \ Cpp.ignoretokens = QAXFACTORY_EXPORT \
QM_EXPORT_CANVAS \ QM_EXPORT_CANVAS \
... ...
@ -1343,15 +1343,12 @@
quotation marks. Note that if the value spans several lines, each quotation marks. Note that if the value spans several lines, each
line needs to be enclosed by quotation marks. line needs to be enclosed by quotation marks.
\code \badcode
HTML.footer = "<p /><address><hr /><div align=\"center\">\n" \ HTML.footer = "<p /><address><hr /><div align=\"center\">\n" \
... ...
"</tr></table></div></address>" "</tr></table></div></address>"
\endcode \endcode
The complete variable entry provides the standard footer of the
\l {http://doc.qt.digia.com/4.0/index.html} {Qt Reference Documentation}.
\target HTML.postheader-variable \target HTML.postheader-variable
\section1 HTML.postheader \section1 HTML.postheader
@ -1365,7 +1362,7 @@
marks. Note that if the value spans several lines, each line needs marks. Note that if the value spans several lines, each line needs
to be enclosed by quotation marks. to be enclosed by quotation marks.
\code \badcode
HTML.postheader = "<table border=\"0\"..." \ HTML.postheader = "<table border=\"0\"..." \
... ...
"<img src=\"images/qt-logo.png\" \ "<img src=\"images/qt-logo.png\" \
@ -1389,7 +1386,7 @@
marks. Note that if the value spans several lines, each line needs marks. Note that if the value spans several lines, each line needs
to be enclosed by quotation marks. to be enclosed by quotation marks.
\code \badcode
HTML.style = "h3.fn,span.fn" \ HTML.style = "h3.fn,span.fn" \
"{ margin-left: 1cm; text-indent: -1cm; }\n" \ "{ margin-left: 1cm; text-indent: -1cm; }\n" \
"a:link { color: #004faf; text-decoration: none }\n" \ "a:link { color: #004faf; text-decoration: none }\n" \
@ -1400,10 +1397,6 @@
"body { background: #ffffff; color: black; }" "body { background: #ffffff; color: black; }"
\endcode \endcode
provides the HTML style for the \l
{http://doc.qt.digia.com/4.0/index.html} {Qt Reference
Documentation}.
\target HTML.stylesheets-variable \target HTML.stylesheets-variable
\section1 HTML.stylesheets \section1 HTML.stylesheets
@ -1415,7 +1408,7 @@
has been generated. Typically, it is only necessary to define a has been generated. Typically, it is only necessary to define a
single stylesheet for any set of documentation; for example: single stylesheet for any set of documentation; for example:
\code \badcode
HTML.stylesheets = classic.css HTML.stylesheets = classic.css
\endcode \endcode
@ -1464,7 +1457,7 @@
Reference documentation, you need to specify the associated index Reference documentation, you need to specify the associated index
file: file:
\code \badcode
indexes = $QTDIR/doc/html/qt.index indexes = $QTDIR/doc/html/qt.index
\endcode \endcode
@ -1479,7 +1472,7 @@
The project's name is used to form a file name for the associated The project's name is used to form a file name for the associated
project's \e index file. project's \e index file.
\code \badcode
project = QtCreator project = QtCreator
\endcode \endcode
@ -1499,7 +1492,7 @@
the base URL when constructing links to classes, functions, and the base URL when constructing links to classes, functions, and
other things listed in the index. other things listed in the index.
\code \badcode
project = Qt project = Qt
description = Qt Reference Documentation description = Qt Reference Documentation
url = http://doc.qt.io/qt-4.8/ url = http://doc.qt.io/qt-4.8/
@ -1522,7 +1515,7 @@
For example, \l qtgui.qdocconf (the configuration file for Qt) For example, \l qtgui.qdocconf (the configuration file for Qt)
contains the following variable definitions: contains the following variable definitions:
\code \badcode
project = Qt project = Qt
description = Qt Reference Documentation description = Qt Reference Documentation
url = http://doc.qt.io/qt-4.8/ url = http://doc.qt.io/qt-4.8/
@ -1554,7 +1547,7 @@
A manifest file has the following structure: A manifest file has the following structure:
\code \badcode
<?xml version="1.0" encoding="UTF-8"?> <?xml version="1.0" encoding="UTF-8"?>
<instructionals module="QtGui"> <instructionals module="QtGui">
<examples> <examples>
@ -1596,7 +1589,7 @@
Example: Example:
\code \badcode
manifestmeta.filters = highlighted sql webkit global manifestmeta.filters = highlighted sql webkit global
manifestmeta.highlighted.names = "QtGui/Analog Clock Window Example" \ manifestmeta.highlighted.names = "QtGui/Analog Clock Window Example" \
@ -1632,7 +1625,7 @@
In your configuration file, set your \c {outputformats} variable In your configuration file, set your \c {outputformats} variable
to \c {DITAXML}, and send the output to an appropriate directory: to \c {DITAXML}, and send the output to an appropriate directory:
\code \badcode
outputdir = $QTDIR/doc/ditaxml outputdir = $QTDIR/doc/ditaxml
outputformats = DITAXML outputformats = DITAXML
\endcode \endcode
@ -1640,7 +1633,7 @@
And include these macros in your configuration file to prevent And include these macros in your configuration file to prevent
QDoc from doing some escaping that doesn't validate in XML: QDoc from doing some escaping that doesn't validate in XML:
\code \badcode
macro.aacute.DITAXML = "&aacute;" macro.aacute.DITAXML = "&aacute;"
macro.Aring.DITAXML = "&Aring;" macro.Aring.DITAXML = "&Aring;"
macro.aring.DITAXML = "&aring;" macro.aring.DITAXML = "&aring;"
@ -1664,7 +1657,7 @@
You can also set default values for some of the tags in the DITA You can also set default values for some of the tags in the DITA
\c {<prolog>} and \c {<metadata>} elements: \c {<prolog>} and \c {<metadata>} elements:
\code \badcode
dita.metadata.default.author = Qt Development Frameworks dita.metadata.default.author = Qt Development Frameworks
dita.metadata.default.permissions = all dita.metadata.default.permissions = all
dita.metadata.default.publisher = Qt Project dita.metadata.default.publisher = Qt Project

2
src/tools/qdoc/doc/qdoc-manual.qdoc
View File

@ -39,7 +39,7 @@
\li \l {Context Commands} \li \l {Context Commands}
\list \list
\li \l {Document Navigation} \li \l {Document Navigation}
\li \l {Reporting Status} \li \l {Status}
\li \l {Thread Support} \li \l {Thread Support}
\li \l {Relating Things} \li \l {Relating Things}
\li \l {Grouping Things} \li \l {Grouping Things}

25
src/tools/qdoc/doc/qdoc-minimum-qdocconf.qdoc
View File

@ -27,7 +27,7 @@
/*! /*!
\page qdoc-minimum-qdocconf.html \page qdoc-minimum-qdocconf.html
\target minimal-qdocconf \target minimal-qdocconf
\title A minimal qdocconf file \title A Minimal qdocconf File
\brief Describes a minimal .qdocconf file \brief Describes a minimal .qdocconf file
@ -37,8 +37,8 @@ will discuss every statement in the qdocconf file.
Each line from the qdocconf file is first quoted. Below each statement you will Each line from the qdocconf file is first quoted. Below each statement you will
find the meaning. find the meaning.
\code \badcode
#include(compat.qdocconf) include(compat.qdocconf)
outputdir = html outputdir = html
headerdirs = . headerdirs = .
sourcedirs = . sourcedirs = .
@ -46,10 +46,10 @@ find the meaning.
imagedirs = ./images imagedirs = ./images
\endcode \endcode
\title Notes \b Notes:
\code \badcode
#include(compat.qdocconf) include(compat.qdocconf)
\endcode \endcode
For compatibility with older versions of Qt, it is recommended For compatibility with older versions of Qt, it is recommended
@ -61,32 +61,29 @@ to include compat.qdocconf.
QDoc will put the documentation generated in the html directory. QDoc will put the documentation generated in the html directory.
\code \badcode
headerdirs = . headerdirs = .
\endcode \endcode
The header file associated with the \e .cpp source files can be found in the The header file associated with the \e .cpp source files can be found in the
current directory. current directory.
\code \badcode
sourcedirs = . sourcedirs = .
\endcode \endcode
The current directory is the directory containing the source files: the \e .cpp The current directory is the directory containing the source files: the \e .cpp
and \e .qdoc files used in the documentation. and \e .qdoc files used in the documentation.
\code \badcode
exampledirs = . exampledirs = .
\endcode \endcode
The source code of the example files can be found in the current directory. The source code of the example files can be found in the current directory.
\code \badcode
imagedirs = ./images imagedirs = ./images
\endcode \endcode
The image files can be found in the underlying directory "images". The image files can be found in the underlying directory \c images.
\note Please take care with this minimal qdocconf file. Using it in the wrong directory
could cause qdoc to include a large number of files.
*/ */

113
src/tools/qdoc/doc/qtgui-qdocconf.qdoc
View File

@ -30,20 +30,20 @@
\page qtgui-qdocconf.html \page qtgui-qdocconf.html
\title qtgui.qdocconf with Comments \title qtgui.qdocconf with Comments
\brief A walkthrough of a typical qdocconf file \brief A walkthrough of a typical qdocconf file.
This document goes through a typical Qt 5 qdocconf file. The contents is taken from This document goes through a typical Qt 5 qdocconf file. The contents is taken from
Qt GUI's \e qtgui.qdocconf file. Qt GUI's \e qtgui.qdocconf file.
Below you will find the full contents of qtgui.qdocconf. The subsequent section will discuss Below you will find the full contents of \c qtgui.qdocconf. The subsequent section will discuss
every statement in the qdocconf file. every statement in the qdocconf file.
\code \badcode
include($QT_INSTALL_DOCS/global/qt-module-defaults.qdocconf) include($QT_INSTALL_DOCS/global/qt-module-defaults.qdocconf)
project = QtGui project = QtGui
description = Qt GUI Reference Documentation description = Qt GUI Reference Documentation
url = http://doc.qt.io/qt-$QT_VER/qtgui-index.html url = http://doc.qt.io/qt-5
version = $QT_VERSION version = $QT_VERSION
examplesinstallpath = gui examplesinstallpath = gui
@ -95,20 +95,20 @@ every statement in the qdocconf file.
\title Qtgui.qdocconf with notes \title Qtgui.qdocconf with notes
\code \badcode
include($QT_INSTALL_DOCS/global/qt-module-defaults.qdocconf) include($QT_INSTALL_DOCS/global/qt-module-defaults.qdocconf)
\endcode \endcode
QDoc inherits the default templates, macros, and settings from the directory QDoc inherits the default templates, macros, and settings from the directory
specified from the \c $QT_INSTALL_DOCS variable. \c qmake prints the value of specified from the \c $QT_INSTALL_DOCS variable. \c qmake prints the value of
the variable. the variable.
\code \badcode
qmake -query qmake -query
\endcode \endcode
\sa include \b {See also}: \l {include}.
\code \badcode
project = QtGui project = QtGui
\endcode \endcode
@ -116,22 +116,22 @@ The \c project variable sets the name of the QDoc build. This name is also
used to form the index file, which, in this case, will be \e qtgui.index. The used to form the index file, which, in this case, will be \e qtgui.index. The
name of the index file doesn't adopt the uppercase letters of the project name. name of the index file doesn't adopt the uppercase letters of the project name.
\sa project \b {See also}: \l {project}.
\code \badcode
description = Qt GUI Reference Documentation description = Qt GUI Reference Documentation
\endcode \endcode
A short description of the project concerned. A short description of the project concerned.
\code \badcode
url = http://doc.qt.io/qt-$QT_VER/qtgui-index.html url = http://doc.qt.io/qt-5
\endcode \endcode
The \c url variable holds the base url of the project. The \c url variable holds the base url of the project.
The URL is stored in the generated index file for the project. The URL is stored in the generated index file for the project.
QDoc will use this as the base URL when constructing links QDoc will use this as the base URL when constructing external links
to content listed in the index. to content listed in the index.
\note QDoc omits this value when the -installdir argument \note QDoc omits this value when the -installdir argument
@ -139,27 +139,29 @@ is specified when running QDoc.
\keyword examplesinstallpath \keyword examplesinstallpath
\code \badcode
examplesinstallpath = gui examplesinstallpath = gui
\endcode \endcode
This \e examplesinstallpath variable indicates that the examples will be installed This \c examplesinstallpath variable indicates that the examples will be
in the \e gui directory under the parent examples directory (for Qt, this is installed in the \e gui directory under the parent examples directory
$QT_INSTALL_EXAMPLES). (for Qt, this is $QT_INSTALL_EXAMPLES).
\note The examplepath variable has to match the example directory specified in exampledirs. \note The examplepath variable has to match the example directory specified in
\sa exampledirs \c exampledirs.
\code \b {See also}: \l {exampledirs}.
\badcode
qhp.projects = QtGui qhp.projects = QtGui
qhp.QtGui.file = qtgui.qhp qhp.QtGui.file = qtgui.qhp
\endcode \endcode
The following parameters are for creating a QHP file (\e .qhp). The qhelpgenerator The following parameters are for creating a QHP file (\e .qhp). The
program can convert the QHP file into a QCH file (\e .qch), which can be opened in \e qhelpgenerator program can convert the QHP file into a QCH file (\e .qch),
Qt Assistant or Qt Creator. which can be opened in Qt Assistant or Qt Creator.
\code \badcode
qhp.QtGui.namespace = org.qt-project.qtgui.$QT_VERSION_TAG qhp.QtGui.namespace = org.qt-project.qtgui.$QT_VERSION_TAG
\endcode \endcode
@ -167,32 +169,32 @@ A unique identifier which enables QHelpEngine to retrieve the helpfile
from a given link. This namespace is also used as a base url for links from a given link. This namespace is also used as a base url for links
to the helpfile. to the helpfile.
\code \badcode
qhp.QtGui.virtualFolder = qtgui qhp.QtGui.virtualFolder = qtgui
\endcode \endcode
Virtual folders group documentation together into a single location. A Virtual folders group documentation together into a single location. A
virtual folder will become the root directory of all files referenced in a virtual folder will become the root directory of all files referenced in
compressed help file. a compressed help file.
When two manuals are located in the same virtual folder, it is possible to refer When two manuals are located in the same virtual folder, it is possible to
to sections of the other manual using relative paths. refer to sections of the other manual using relative paths. The virtual
The virtual folder tag is mandatory and the folder must not contain any '/'. folder tag is mandatory and the folder must not contain any '/'.
\code \badcode
qhp.QtGui.indexTitle = Qt GUI the title of the page that has the contents qhp.QtGui.indexTitle = Qt GUI
\endcode \endcode
This is the title of the page that has the contents. This is the title of the page that has the contents.
\code \badcode
qhp.QtGui.indexRoot = to be checked qhp.QtGui.indexRoot =
\endcode \endcode
Specifies the title of the root (namespace) page to generate the documentation for. Specifies the title of the root (namespace) page to generate the documentation for.
Typically defined as an empty string. Typically defined as an empty string.
\code \badcode
qhp.QtGui.filterAttributes = qtgui $QT_VERSION qtrefdoc qhp.QtGui.filterAttributes = qtgui $QT_VERSION qtrefdoc
qhp.QtGui.customFilters.Qt.name = QtGui $QT_VERSION qhp.QtGui.customFilters.Qt.name = QtGui $QT_VERSION
qhp.QtGui.customFilters.Qt.filterAttributes = qtgui $QT_VERSION qhp.QtGui.customFilters.Qt.filterAttributes = qtgui $QT_VERSION
@ -206,7 +208,7 @@ filter in its \gui{Filtered by} drop-down list. Only the documentation sets
that have their filter attributes match the attributes of the selected that have their filter attributes match the attributes of the selected
custom filter will be shown. custom filter will be shown.
\code \badcode
qhp.QtGui.subprojects = classes qhp.QtGui.subprojects = classes
qhp.QtGui.subprojects.classes.title = C++ Classes qhp.QtGui.subprojects.classes.title = C++ Classes
qhp.QtGui.subprojects.classes.indexTitle = Qt GUI C++ Classes qhp.QtGui.subprojects.classes.indexTitle = Qt GUI C++ Classes
@ -216,34 +218,22 @@ for this project. In this example, the subproject, which is displayed in
the Assistant's sidebar, is named "C++ Classes" and its index is the page the Assistant's sidebar, is named "C++ Classes" and its index is the page
titled "QT GUI C++ Classes". titled "QT GUI C++ Classes".
\code \badcode
qhp.QtGui.subprojects.classes.selectors = class fake:headerfile qhp.QtGui.subprojects.classes.selectors = class fake:headerfile
\endcode \endcode
Lists all headerfiles. Lists all C++ classes and header files.
A ‘fake’ type specifies a generic documentation node, and is followed by See \l {Creating Help Project Files} for more information.
a c\ : and a \e subtype specifier.
Possible values: \badcode
\code tagfile = ../../../doc/qtgui/qtgui.tags
example
headerfile
file
group
module
page
externalpage
qmlclass
qmlpropertygroup
qmlbasictype
\endcode \endcode
tagfile = ../../../doc/qtgui/qtgui.tags
This specifies the Doxygen tag file that needs to be written when the html is generated This specifies the Doxygen tag file that needs to be written when the html is generated
by QDoc. by QDoc.
\code \badcode
depends += \ depends += \
qtcore \ qtcore \
qtnetwork \ qtnetwork \
@ -259,14 +249,14 @@ Specifies the modules QDoc needs to load for generating output for Qt GUI.
QDoc loads the index files for all modules listed in the depends statement in QDoc loads the index files for all modules listed in the depends statement in
order to enable linking to pages in these modules. order to enable linking to pages in these modules.
\code \badcode
headerdirs += .. headerdirs += ..
\endcode \endcode
Add the parent directory to the list of directories containing the header files Add the parent directory to the list of directories containing the header files
associated with the \e .cpp source files. associated with the \e .cpp source files.
\code \badcode
sourcedirs += .. \ sourcedirs += .. \
../../../examples/gui/doc/src ../../../examples/gui/doc/src
\endcode \endcode
@ -274,7 +264,7 @@ associated with the \e .cpp source files.
Add the specified directories to the list of directories containing the \e .cpp and Add the specified directories to the list of directories containing the \e .cpp and
\e .qdoc files used in the documentation. \e .qdoc files used in the documentation.
\code \badcode
excludedirs = ../../../examples/gui/doc/src/tmp excludedirs = ../../../examples/gui/doc/src/tmp
\endcode \endcode
@ -283,14 +273,13 @@ by qdoc, even if the same directories are included by the \c sourcedirs or \c he
variables. variables.
When executed, QDoc will ignore the directories listed. When executed, QDoc will ignore the directories listed.
\sa excludefiles \b {See also}: \l {excludefiles}.
\code \badcode
exampledirs += ../../../examples/gui \ exampledirs += ../../../examples/gui \
snippets snippets
\endcode \endcode
\sa {examples-variable}{examples} \b {See also}: \l {examples-variable}{examples}, \l {examplesinstallpath}.
\sa examplesinstallpath
Add the two directories specified to the list of directories containing the source Add the two directories specified to the list of directories containing the source
code of the example files. code of the example files.
@ -299,7 +288,7 @@ If QDoc encounters both \c exampledirs and \c examples, it will look first in th
\c examples directory. QDoc will accept the first matching file it finds. QDoc will \c examples directory. QDoc will accept the first matching file it finds. QDoc will
search in the directories specified, not in their subdirectories. search in the directories specified, not in their subdirectories.
\code \badcode
imagedirs += images \ imagedirs += images \
../../../examples/gui/doc/images \ ../../../examples/gui/doc/images \
../../../doc/src/images \ ../../../doc/src/images \