Doc: Fix various issues in QDoc Manual

    - 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>

7 files changed, 149 insertions, 172 deletions

diff --git a/src/tools/qdoc/doc/examples/examples.qdoc b/src/tools/qdoc/doc/examples/examples.qdoc
index 777c869c65..ce67dea20e 100644
--- a/src/tools/qdoc/doc/examples/examples.qdoc
+++ b/src/tools/qdoc/doc/examples/examples.qdoc
@@ -89,10 +89,9 @@
     \title UI Components
     \brief Basic set of UI components
 
-    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 \l{Qt
-    Quick Code Samples}.
+    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
+    \e {Qt Quick Code Samples}.
 
     This module is part of the \l{componentset}{UIComponents} example.
 */
diff --git a/src/tools/qdoc/doc/qdoc-guide/qdoc-guide.qdoc b/src/tools/qdoc/doc/qdoc-guide/qdoc-guide.qdoc
index a8c9c73b5c..af1fa1ba14 100644
--- a/src/tools/qdoc/doc/qdoc-guide/qdoc-guide.qdoc
+++ b/src/tools/qdoc/doc/qdoc-guide/qdoc-guide.qdoc
@@ -112,7 +112,7 @@
     Specifying the path to the source directories allow QDoc to find sources and
     generate documentation.
 
-    \code
+    \badcode
         sourcedirs = <path to source code>
         exampledirs = <path to examples directory>
         imagedirs = <path to image directory>
@@ -129,7 +129,7 @@
     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.
-    \code
+    \badcode
         outputdir  =    $SAMPLE_PROJECT/doc/html
         outputformats = HTML
     \endcode
@@ -144,8 +144,8 @@
     the  \l{Input and Output Directories}{output} directory. It is also possible
     to specify extra files that QDoc should export.
 
-    \code
-        extraimages.HTML = extraImage.png \
+    \badcode
+        HTML.extraimages = extraImage.png \
                            extraImage2.png
     \endcode
 
@@ -169,7 +169,7 @@
     generated documentation into the directory specified by the \c outputdir
     variable.
 
-    \code
+    \badcode
         outputformats = HTML
         outputdir =  <path to output directory>
     \endcode
@@ -178,12 +178,12 @@
     are located. Typically, the templates directory contains a \c scripts,
     \c images, and a \c style directory, containing scripts and CSS files.
 
-    \code
+    \badcode
         HTML.templatedir = <path to templates>
     \endcode
 
     The main configuration variables are:
-    \code
+    \badcode
         HTML.postheader
         HTML.postpostheader
         HTML.postheader
@@ -210,7 +210,7 @@
     documentation, QDoc does not need HTML style templates for generating
     documentation in DITA XML format.
 
-    \code
+    \badcode
         outputformats = DITAXML
         outputdir
     \endcode
@@ -222,7 +222,7 @@
     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.
 
-    \code
+    \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.
@@ -232,7 +232,7 @@
     Macros for substituting HTML characters exist and are helpful for generating
     specific HTML-valid characters.
 
-    \code
+    \badcode
     macro.pi.HTML         = "&Pi;"
     \endcode
     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
     \l{Input and Output Directories}{fileextensions} variable.
 
-    Also, the generated HTML files can have a prefix, specified in the QDoc
-    configuration file.
-    \code
+    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
-    The outputprefixes will, for example, prefix QML type HTML filenames.
-    \code
-    files:
-        uicomponents-button.html
-        uicomponents-scrollbar.html
-    \endcode
+
+    \b {See also}: \l {outputprefixes-variable}{outputprefixes},
+                   \l {outputsuffixes-variable}{outputsuffixes}.
 
 */
 
diff --git a/src/tools/qdoc/doc/qdoc-manual-contextcmds.qdoc b/src/tools/qdoc/doc/qdoc-manual-contextcmds.qdoc
index 50e85676f8..a2e851293c 100644
--- a/src/tools/qdoc/doc/qdoc-manual-contextcmds.qdoc
+++ b/src/tools/qdoc/doc/qdoc-manual-contextcmds.qdoc
@@ -77,7 +77,7 @@
     \page 15-qdoc-commands-navigation.html
     \previouspage Context Commands
     \contentspage QDoc Manual
-    \nextpage Reporting Status
+    \nextpage Status
 
     \title Document Navigation
 
@@ -522,7 +522,7 @@
 
 /*!
     \page 17-qdoc-commands-thread.html
-    \previouspage Reporting Status
+    \previouspage Status
     \contentspage QDoc Manual
     \nextpage Relating Things
 
diff --git a/src/tools/qdoc/doc/qdoc-manual-qdocconf.qdoc b/src/tools/qdoc/doc/qdoc-manual-qdocconf.qdoc
index 57a966277c..2472b0f4fb 100644
--- a/src/tools/qdoc/doc/qdoc-manual-qdocconf.qdoc
+++ b/src/tools/qdoc/doc/qdoc-manual-qdocconf.qdoc
@@ -69,14 +69,14 @@
     you to use special characters like '=' and ' \" ' within the value
     string, for example:
 
-    \code
+    \badcode
     HTML.postheader = "<a href=\"index.html\">Home</a>"
     \endcode
 
     If an entry spans many lines, use a backslash at the end of every
     line but the last:
 
-    \code
+    \badcode
     sourcedirs = kernel \
                  tools \
                  widgets
@@ -163,7 +163,7 @@
     The general syntax is \tt {alias.\e{original-command-name} = \e
     temporary-command-name}.
 
-    \code
+    \badcode
         alias.e = i
     \endcode
 
@@ -200,7 +200,7 @@
     for details). By default, no symbol is defined, meaning that code
     protected with #ifdef...#endif will be ignored.
 
-    \code
+    \badcode
         defines = Q_QDOC \
                   QT_.*_SUPPORT \
                   QT_.*_LIB \
@@ -228,7 +228,7 @@
     You can also define preprocessor symbols manually on the command
     line using the -D option. For example:
 
-    \code
+    \badcode
         currentdirectory$ qdoc -Dconsoleedition qtgui.qdocconf
     \endcode
 
@@ -251,7 +251,7 @@
     The \c edition variable is always used with a particular edition
     name to define the modules for that edition:
 
-    \code
+    \badcode
         edition.Console      = QtCore QtNetwork QtSql QtXml
         edition.Desktop      = QtCore QtGui QtNetwork QtOpenGL QtSql QtXml \
                                QtDesigner QtAssistant Qt3Support QAxContainer \
@@ -265,7 +265,7 @@
     {generatelist} command is used to generate a list of classes for
     this edition:
 
-    \code
+    \badcode
         \generatelist{classesbyedition Console}
     \endcode
 
@@ -288,7 +288,7 @@
     and accept the first matching file it finds. It will only search
     in the specified directories, \e not in subdirectories.
 
-    \code
+    \badcode
         exampledirs = $QTDIR/doc/src \
                       $QTDIR/examples \
                       $QTDIR \
@@ -299,7 +299,7 @@
 
     When processing
 
-    \code
+    \badcode
         \quotefromfile widgets/calculator/calculator.cpp
     \endcode
 
@@ -308,13 +308,13 @@
     there isn't, it will search in the \c exampledirs variable, and
     first see if there exists a file called
 
-    \code
+    \badcode
         $QTDIR/doc/src/widgets/calculator/calculator.cpp
     \endcode
 
     If it doesn't, QDoc will continue looking for a file called
 
-    \code
+    \badcode
         $QTDIR/examples/widgets/calculator/calculator.cpp
     \endcode
 
@@ -345,7 +345,7 @@
     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:
 
-    \code
+    \badcode
         \quotefromfile calculator.cpp
     \endcode
 
@@ -364,7 +364,7 @@
     The extensions are given as standard wildcard expressions. You
     can add a file extension to the filter using '+='. For example:
 
-    \code
+    \badcode
         examples.fileextensions += *.qrc
     \endcode
 
@@ -380,7 +380,7 @@
 
     For example:
 
-    \code
+    \badcode
         sourcedirs =  src/corelib
         excludedirs = src/corelib/tmp
     \endcode
@@ -397,7 +397,7 @@
     The \c excludefiles variable allows you to specify individual files
     that should \e{not} be processed by qdoc.
 
-    \code
+    \badcode
     excludefiles += $QT_CORE_SOURCES/../../src/widgets/kernel/qwidget.h \
                     $QT_CORE_SOURCES/../../src/widgets/kernel/qwidget.cpp
     \endcode
@@ -429,7 +429,7 @@
     reason, these images are specified using the \c extraimages
     variable:
 
-    \code
+    \badcode
         extraimages.HTML = qt-logo
     \endcode
 
@@ -470,7 +470,7 @@
     preprocessor symbol is specified within the \c falsehoods variable
     entry:
 
-    \code
+    \badcode
         falsehoods = NOTYET
     \endcode
 
@@ -496,7 +496,7 @@
     the header files associated with the \c .cpp source files used in
     the documentation.
 
-    \code
+    \badcode
         headerdirs = $QTDIR/src \
                      $QTDIR/extensions/activeqt \
                      $QTDIR/extensions/motif \
@@ -538,7 +538,7 @@
     files in addition to those located in the directories specified by
     the \l {headerdirs} {\c headerdirs} variable.
 
-    \code
+    \badcode
         headers = $QTDIR/src/gui/widgets/qlineedit.h \
                   $QTDIR/src/gui/widgets/qpushbutton.h
     \endcode
@@ -568,7 +568,7 @@
     The extensions are given as standard wildcard expressions. You
     can add a file extension to the filter using '+='. For example:
 
-    \code
+    \badcode
         header.fileextensions += *.H
     \endcode
 
@@ -592,7 +592,7 @@
     and accept the first matching file it finds. It will only search
     in the specified directories, \e not in subdirectories.
 
-    \code
+    \badcode
         imagedirs = $QTDIR/doc/src/images \
                     $QTDIR/examples
 
@@ -601,7 +601,7 @@
 
     When processing
 
-    \code
+    \badcode
         \image calculator-example.png
     \endcode
 
@@ -610,13 +610,13 @@
     variable. If there isn't, it will search in the \c imagedirs
     variable for:
 
-    \code
+    \badcode
         $QTDIR/doc/src/images/calculator-example.png
     \endcode
 
     If the file doesn't exist, QDoc will look for a file called
 
-    \code
+    \badcode
         $QTDIR/examples/calculator-example.png
     \endcode
 
@@ -638,7 +638,7 @@
     files in addition to those located in the directories specified by
     the \l {imagedirs} {\c imagedirs} variable.
 
-    \code
+    \badcode
         images = $QTDIR/doc/src/images/calculator-example.png
     \endcode
 
@@ -662,7 +662,7 @@
     The idea is to enable different image format for different output
     format.
 
-    \code
+    \badcode
         images.fileextensions.HTML = *.png
         images.fileextensions.LOUT = *.eps
     \endcode
@@ -681,7 +681,7 @@
     You can add a file extension to the filter using '+='. For
     example:
 
-    \code
+    \badcode
         images.fileextensions.HTML += *.eps
     \endcode
 
@@ -698,7 +698,7 @@
     specified. However, a possible example of a language variable
     statement:
 
-    \code
+    \badcode
         language = Cpp
     \endcode
 
@@ -717,7 +717,7 @@
     appending \c {.DITAXML} to the macro name, the macro is only used
     when generating DITA XML.
 
-    \code
+    \badcode
         macro.gui              = "\\b"
         macro.raisedaster.HTML = "<sup>*</sup>"
     \endcode
@@ -743,7 +743,7 @@
     The \c naturallanguage variable specifies the natural language
     used for the documentation generated by qdoc.
 
-    \code
+    \badcode
         naturallanguage = zh-Hans
     \endcode
 
@@ -766,7 +766,7 @@
     The \c outputdir variable specifies the directory where QDoc will
     put the generated documentation.
 
-    \code
+    \badcode
         outputdir = $QTDIR/doc/html
     \endcode
 
@@ -774,7 +774,7 @@
     $QTDIR/doc/html. For example, the documentation of the QWidget
     class is located in
 
-    \code
+    \badcode
         $QTDIR/doc/html/qwidget.html
     \endcode
 
@@ -789,7 +789,7 @@
     The \c outputencoding variable specifies the encoding used for the
     documentation generated by qdoc.
 
-    \code
+    \badcode
         outputencoding = UTF-8
     \endcode
 
@@ -874,7 +874,7 @@
     The \c sourcedirs variable specifies the directories containing
     the \c .cpp or \c .qdoc files used in the documentation.
 
-    \code
+    \badcode
         sourcedirs  += .. \
                        ../../../examples/gui/doc/src
     \endcode
@@ -910,7 +910,7 @@
     The \c sourceencoding variable specifies the encoding used for the
     source code and documentation.
 
-    \code
+    \badcode
         sourceencoding = UTF-8
     \endcode
 
@@ -935,7 +935,7 @@
     files in addition to those located in the directories specified by
     the \l {sourcedirs-variable} {sourcedirs} variable.
 
-    \code
+    \badcode
         sources = $QTDIR/src/gui/widgets/qlineedit.cpp \
                   $QTDIR/src/gui/widgets/qpushbutton.cpp
     \endcode
@@ -964,7 +964,7 @@
     The extensions are given as standard wildcard expressions. You
     can add a file extension to the filter using '+='. For example:
 
-    \code
+    \badcode
         sources.fileextensions += *.CC
     \endcode
 
@@ -981,7 +981,7 @@
     output. The warnings are specified using standard wildcard
     expressions.
 
-    \code
+    \badcode
         spurious = "Cannot find .*" \
         "Missing .*"
     \endcode
@@ -990,8 +990,8 @@
     will not be part of the output when running QDoc. For example
     would the following warning be omitted from the output:
 
-    \code
-        qt-4.0/src/opengl/qgl_mac.cpp:156: Missing parameter name
+    \badcode
+        src/opengl/qgl_mac.cpp:156: Missing parameter name
     \endcode
 
     \target syntaxhighlighting
@@ -1001,7 +1001,7 @@
     perform syntax highlighting on source code quoted in the
     documentation it generates.
 
-    \code
+    \badcode
         syntaxhighlighting = true
     \endcode
 
@@ -1013,7 +1013,7 @@
 
     The \c tabsize variable defines the size of a tab character.
 
-    \code
+    \badcode
     tabsize = 4
     \endcode
 
@@ -1032,8 +1032,8 @@
     The \c version variable specifies the version number of the
     documented software.
 
-    \code
-        version = 4.0.1
+    \badcode
+        version = 5.6.0
     \endcode
 
     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
     that defines the version number of the documented software.
 
-    \code
+    \badcode
         versionsym = QT_VERSION_STR
     \endcode
 
     QT_VERSION_STR is defined in qglobal.h as follows
 
-    \code
+    \badcode
         #define QT_VERSION_STR   "4.0.1"
     \endcode
 
@@ -1226,7 +1226,7 @@
     Cpp.ignoredirectives} variables, non-standard constructs
     (typically macros) can result in erroneous documentation.
 
-    \code
+    \badcode
     Cpp.ignoredirectives = Q_DECLARE_INTERFACE \
                            Q_DECLARE_OPERATORS_FOR_FLAGS \
                            Q_DECLARE_PRIVATE \
@@ -1280,7 +1280,7 @@
 
     In \l qtgui.qdocconf:
 
-    \code
+    \badcode
     Cpp.ignoretokens = QAXFACTORY_EXPORT \
                        QM_EXPORT_CANVAS \
                        ...
@@ -1343,15 +1343,12 @@
     quotation marks. Note that if the value spans several lines, each
     line needs to be enclosed by quotation marks.
 
-    \code
+    \badcode
         HTML.footer = "<p /><address><hr /><div align=\"center\">\n" \
                       ...
                       "</tr></table></div></address>"
     \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
     \section1 HTML.postheader
 
@@ -1365,7 +1362,7 @@
     marks. Note that if the value spans several lines, each line needs
     to be enclosed by quotation marks.
 
-    \code
+    \badcode
      HTML.postheader = "<table border=\"0\"..." \
                        ...
                        "<img src=\"images/qt-logo.png\" \
@@ -1389,7 +1386,7 @@
     marks. Note that if the value spans several lines, each line needs
     to be enclosed by quotation marks.
 
-    \code
+    \badcode
     HTML.style = "h3.fn,span.fn" \
                  "{ margin-left: 1cm; text-indent: -1cm; }\n" \
                  "a:link { color: #004faf; text-decoration: none }\n" \
@@ -1400,10 +1397,6 @@
                  "body { background: #ffffff; color: black; }"
     \endcode
 
-    provides the HTML style for the \l
-    {http://doc.qt.digia.com/4.0/index.html} {Qt Reference
-    Documentation}.
-
     \target HTML.stylesheets-variable
     \section1 HTML.stylesheets
 
@@ -1415,7 +1408,7 @@
     has been generated. Typically, it is only necessary to define a
     single stylesheet for any set of documentation; for example:
 
-    \code
+    \badcode
     HTML.stylesheets = classic.css
     \endcode
 
@@ -1464,7 +1457,7 @@
     Reference documentation, you need to specify the associated index
     file:
 
-    \code
+    \badcode
         indexes = $QTDIR/doc/html/qt.index
     \endcode
 
@@ -1479,7 +1472,7 @@
     The project's name is used to form a file name for the associated
     project's \e index file.
 
-    \code
+    \badcode
         project = QtCreator
     \endcode
 
@@ -1499,7 +1492,7 @@
     the base URL when constructing links to classes, functions, and
     other things listed in the index.
 
-    \code
+    \badcode
     project     = Qt
     description = Qt Reference Documentation
     url         = http://doc.qt.io/qt-4.8/
@@ -1522,7 +1515,7 @@
     For example, \l qtgui.qdocconf (the configuration file for Qt)
     contains the following variable definitions:
 
-    \code
+    \badcode
         project     = Qt
         description = Qt Reference Documentation
         url         = http://doc.qt.io/qt-4.8/
@@ -1554,7 +1547,7 @@
 
     A manifest file has the following structure:
 
-    \code
+    \badcode
     <?xml version="1.0" encoding="UTF-8"?>
     <instructionals module="QtGui">
         <examples>
@@ -1596,7 +1589,7 @@
 
     Example:
 
-    \code
+    \badcode
     manifestmeta.filters                = highlighted sql webkit global
 
     manifestmeta.highlighted.names      = "QtGui/Analog Clock Window Example" \
@@ -1632,7 +1625,7 @@
     In your configuration file, set your \c {outputformats} variable
     to \c {DITAXML}, and send the output to an appropriate directory:
 
-    \code
+    \badcode
     outputdir                  = $QTDIR/doc/ditaxml
     outputformats              = DITAXML
     \endcode
@@ -1640,7 +1633,7 @@
     And include these macros in your configuration file to prevent
     QDoc from doing some escaping that doesn't validate in XML:
 
-    \code
+    \badcode
     macro.aacute.DITAXML       = "&aacute;"
     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
     \c {<prolog>} and \c {<metadata>} elements:
 
-    \code
+    \badcode
     dita.metadata.default.author      = Qt Development Frameworks
     dita.metadata.default.permissions = all
     dita.metadata.default.publisher   = Qt Project
diff --git a/src/tools/qdoc/doc/qdoc-manual.qdoc b/src/tools/qdoc/doc/qdoc-manual.qdoc
index c0a1afaa52..a0e35c2e9c 100644
--- a/src/tools/qdoc/doc/qdoc-manual.qdoc
+++ b/src/tools/qdoc/doc/qdoc-manual.qdoc
@@ -39,7 +39,7 @@
       \li \l {Context Commands}
         \list
           \li \l {Document Navigation}
-          \li \l {Reporting Status}
+          \li \l {Status}
           \li \l {Thread Support}
           \li \l {Relating Things}
           \li \l {Grouping Things}
diff --git a/src/tools/qdoc/doc/qdoc-minimum-qdocconf.qdoc b/src/tools/qdoc/doc/qdoc-minimum-qdocconf.qdoc
index 77d252b24c..66ceed4a3d 100644
--- a/src/tools/qdoc/doc/qdoc-minimum-qdocconf.qdoc
+++ b/src/tools/qdoc/doc/qdoc-minimum-qdocconf.qdoc
@@ -27,7 +27,7 @@
 /*!
 \page qdoc-minimum-qdocconf.html
 \target minimal-qdocconf
-\title A minimal qdocconf file
+\title 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
 find the meaning.
 
-\code
-   #include(compat.qdocconf)
+\badcode
+   include(compat.qdocconf)
    outputdir   = html
    headerdirs  = .
    sourcedirs  = .
@@ -46,10 +46,10 @@ find the meaning.
    imagedirs   = ./images
 \endcode
 
-\title Notes
+\b Notes:
 
-\code
-   #include(compat.qdocconf)
+\badcode
+   include(compat.qdocconf)
 \endcode
 
 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.
 
-\code
+\badcode
    headerdirs  = .
 \endcode
 
 The header file associated with the \e .cpp source files can be found in the
 current directory.
 
-\code
+\badcode
    sourcedirs  = .
 \endcode
 
 The current directory is the directory containing the source files: the \e .cpp
 and \e .qdoc files used in the documentation.
 
-\code
+\badcode
    exampledirs = .
 \endcode
 
 The source code of the example files can be found in the current directory.
 
-\code
+\badcode
    imagedirs   = ./images
 \endcode
 
-The image files can be found in the underlying directory "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.
+The image files can be found in the underlying directory \c images.
 */
diff --git a/src/tools/qdoc/doc/qtgui-qdocconf.qdoc b/src/tools/qdoc/doc/qtgui-qdocconf.qdoc
index 3dcd2482d6..d90584ff42 100644
--- a/src/tools/qdoc/doc/qtgui-qdocconf.qdoc
+++ b/src/tools/qdoc/doc/qtgui-qdocconf.qdoc
@@ -30,20 +30,20 @@
 \page qtgui-qdocconf.html
 \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
 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.
 
-\code
+\badcode
    include($QT_INSTALL_DOCS/global/qt-module-defaults.qdocconf)
 
    project                 = QtGui
    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
 
    examplesinstallpath     = gui
@@ -95,20 +95,20 @@ every statement in the qdocconf file.
 
 \title Qtgui.qdocconf with notes
 
-\code
+\badcode
    include($QT_INSTALL_DOCS/global/qt-module-defaults.qdocconf)
 \endcode
 
 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
 the variable.
-\code
+\badcode
    qmake -query
 \endcode
 
-\sa include
+\b {See also}: \l {include}.
 
-\code
+\badcode
    project                 = QtGui
 \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
 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
 \endcode
 
 A short description of the project concerned.
 
-\code
-   url                     = http://doc.qt.io/qt-$QT_VER/qtgui-index.html
+\badcode
+   url                     = http://doc.qt.io/qt-5
 \endcode
 
 The \c url variable holds the base url of 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.
 
 \note QDoc omits this value when the -installdir argument
@@ -139,27 +139,29 @@ is specified when running QDoc.
 
 \keyword examplesinstallpath
 
-\code
+\badcode
    examplesinstallpath     = gui
 \endcode
 
-This \e examplesinstallpath variable indicates that the examples will be installed
-in the \e gui directory under the parent examples directory (for Qt, this is
-$QT_INSTALL_EXAMPLES).
+This \c examplesinstallpath variable indicates that the examples will be
+installed in the \e gui directory under the parent examples directory
+(for Qt, this is $QT_INSTALL_EXAMPLES).
 
-\note The examplepath variable has to match the example directory specified in exampledirs.
-\sa exampledirs
+\note The examplepath variable has to match the example directory specified in
+      \c exampledirs.
 
-\code
+\b {See also}: \l {exampledirs}.
+
+\badcode
    qhp.projects    = QtGui
    qhp.QtGui.file  = qtgui.qhp
 \endcode
 
-The following parameters are for creating a QHP file (\e .qhp). The qhelpgenerator
-program can convert the QHP file into a QCH file (\e .qch), which can be opened in
-Qt Assistant or Qt Creator.
+The following parameters are for creating a QHP file (\e .qhp). The
+\e qhelpgenerator program can convert the QHP file into a QCH file (\e .qch),
+which can be opened in Qt Assistant or Qt Creator.
 
-\code
+\badcode
    qhp.QtGui.namespace           = org.qt-project.qtgui.$QT_VERSION_TAG
 \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
 to the helpfile.
 
-\code
+\badcode
    qhp.QtGui.virtualFolder       = qtgui
 \endcode
 
 Virtual folders group documentation together into a single location. A
-virtual folder will become the root directory of all files referenced in a
-compressed help file.
+virtual folder will become the root directory of all files referenced in
+a compressed help file.
 
-When two manuals are located in the same virtual folder, it is possible to refer
- to sections of the other manual using relative paths.
-The virtual folder tag is mandatory and the folder must not contain any '/'.
+When two manuals are located in the same virtual folder, it is possible to
+refer to sections of the other manual using relative paths. The virtual
+folder tag is mandatory and the folder must not contain any '/'.
 
-\code
-   qhp.QtGui.indexTitle          = Qt GUI  the title of the page that has the contents
+\badcode
+   qhp.QtGui.indexTitle          = Qt GUI
 \endcode
 
 This is the title of the page that has the contents.
 
-\code
-   qhp.QtGui.indexRoot           =  to be checked
+\badcode
+   qhp.QtGui.indexRoot           =
 \endcode
 
 Specifies the title of the root (namespace) page to generate the documentation for.
 Typically defined as an empty string.
 
-\code
+\badcode
    qhp.QtGui.filterAttributes    = qtgui $QT_VERSION qtrefdoc
    qhp.QtGui.customFilters.Qt.name = 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
 custom filter will be shown.
 
-\code
+\badcode
    qhp.QtGui.subprojects         = classes
    qhp.QtGui.subprojects.classes.title = 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
 titled "QT GUI C++ Classes".
 
-\code
+\badcode
    qhp.QtGui.subprojects.classes.selectors = class fake:headerfile
 \endcode
 
-Lists all headerfiles.
-
-A ‘fake’ type specifies a generic documentation node, and is followed by
-a c\ : and a \e subtype specifier.
-
-Possible values:
-\code
-    example
-    headerfile
-    file
-    group
-    module
-    page
-    externalpage
-    qmlclass
-    qmlpropertygroup
-    qmlbasictype
+Lists all C++ classes and header files.
+
+See \l {Creating Help Project Files} for more information.
+
+\badcode
+    tagfile                 = ../../../doc/qtgui/qtgui.tags
 \endcode
 
-tagfile                 = ../../../doc/qtgui/qtgui.tags
 This specifies the Doxygen tag file that needs to be written when the html is generated
 by QDoc.
 
-\code
+\badcode
 depends += \
    qtcore \
    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
 order to enable linking to pages in these modules.
 
-\code
+\badcode
    headerdirs  += ..
 \endcode
 
 Add the parent directory to the list of directories containing the header files
 associated with the \e .cpp source files.
 
-\code
+\badcode
    sourcedirs  += .. \
                   ../../../examples/gui/doc/src
 \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
 \e .qdoc files used in the documentation.
 
-\code
+\badcode
    excludedirs  = ../../../examples/gui/doc/src/tmp
 \endcode
 
@@ -283,14 +273,13 @@ by qdoc, even if the same directories are included by the \c sourcedirs or \c he
 variables.
 
 When executed, QDoc will ignore the directories listed.
-\sa excludefiles
+\b {See also}: \l {excludefiles}.
 
-\code
+\badcode
    exampledirs += ../../../examples/gui \
                   snippets
 \endcode
-\sa {examples-variable}{examples}
-\sa examplesinstallpath
+\b {See also}: \l {examples-variable}{examples}, \l {examplesinstallpath}.
 
 Add the two directories specified to the list of directories containing the source
 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
 search in the directories specified, not in their subdirectories.
 
-\code
+\badcode
    imagedirs   += images \
                   ../../../examples/gui/doc/images \
                   ../../../doc/src/images \