summaryrefslogtreecommitdiffstats
path: root/src/tools/qdoc/doc
diff options
context:
space:
mode:
authorOswald Buddenhagen <oswald.buddenhagen@digia.com>2013-03-07 19:22:06 +0100
committerSimon Hausmann <simon.hausmann@theqtcompany.com>2015-10-22 19:40:09 +0000
commitf343989852b555fd960f5eaae51ece1423ba4373 (patch)
treee1333d22519c72f0fa4759f9a5dc010bf8969bbe /src/tools/qdoc/doc
parenta903ddd8dc806b51c21c84965611880a25037562 (diff)
qdoc is moving back to qttools
Change-Id: Icb5abd32a1cbc3e8d876341c877e8d2a963c0e25 Reviewed-by: Frederik Gladhorn <frederik.gladhorn@theqtcompany.com> Reviewed-by: Topi Reiniö <topi.reinio@digia.com>
Diffstat (limited to 'src/tools/qdoc/doc')
-rw-r--r--src/tools/qdoc/doc/config/qdoc.qdocconf72
-rw-r--r--src/tools/qdoc/doc/corefeatures.qdoc35
-rw-r--r--src/tools/qdoc/doc/examples/componentset/ProgressBar.qml135
-rw-r--r--src/tools/qdoc/doc/examples/componentset/Switch.qml142
-rw-r--r--src/tools/qdoc/doc/examples/componentset/TabWidget.qml183
-rw-r--r--src/tools/qdoc/doc/examples/componentset/componentset.pro5
-rw-r--r--src/tools/qdoc/doc/examples/componentset/uicomponents.qdoc.sample38
-rw-r--r--src/tools/qdoc/doc/examples/cpp.qdoc.sample126
-rw-r--r--src/tools/qdoc/doc/examples/examples.qdoc97
-rw-r--r--src/tools/qdoc/doc/examples/layoutmanagement.qdocinc13
-rw-r--r--src/tools/qdoc/doc/examples/main.cpp46
-rw-r--r--src/tools/qdoc/doc/examples/mainwindow.cpp243
-rw-r--r--src/tools/qdoc/doc/examples/minimum.qdocconf38
-rw-r--r--src/tools/qdoc/doc/examples/objectmodel.qdocinc11
-rw-r--r--src/tools/qdoc/doc/examples/qml.qdoc.sample116
-rw-r--r--src/tools/qdoc/doc/examples/samples.qdocinc109
-rw-r--r--src/tools/qdoc/doc/examples/signalandslots.qdocinc9
-rw-r--r--src/tools/qdoc/doc/files/basicqt.qdoc.sample67
-rw-r--r--src/tools/qdoc/doc/files/compat.qdocconf12
-rw-r--r--src/tools/qdoc/doc/files/qtgui.qdocconf49
-rw-r--r--src/tools/qdoc/doc/images/happy.gifbin11526 -> 0 bytes
-rw-r--r--src/tools/qdoc/doc/images/happyguy.jpgbin53442 -> 0 bytes
-rw-r--r--src/tools/qdoc/doc/images/link-to-qquickitem.pngbin46571 -> 0 bytes
-rw-r--r--src/tools/qdoc/doc/images/links-to-broken-links.pngbin16569 -> 0 bytes
-rw-r--r--src/tools/qdoc/doc/images/links-to-links.pngbin10042 -> 0 bytes
-rw-r--r--src/tools/qdoc/doc/images/qa-table.pngbin7057 -> 0 bytes
-rw-r--r--src/tools/qdoc/doc/images/qt-logo.pngbin1495 -> 0 bytes
-rw-r--r--src/tools/qdoc/doc/images/training.jpgbin8368 -> 0 bytes
-rw-r--r--src/tools/qdoc/doc/qa-pages.qdoc109
-rw-r--r--src/tools/qdoc/doc/qdoc-guide/qdoc-guide.qdoc632
-rw-r--r--src/tools/qdoc/doc/qdoc-guide/qtwritingstyle-cpp.qdoc187
-rw-r--r--src/tools/qdoc/doc/qdoc-guide/qtwritingstyle-qml.qdoc164
-rw-r--r--src/tools/qdoc/doc/qdoc-manual-DITA.qdoc164
-rw-r--r--src/tools/qdoc/doc/qdoc-manual-cmdindex.qdoc156
-rw-r--r--src/tools/qdoc/doc/qdoc-manual-contextcmds.qdoc1058
-rw-r--r--src/tools/qdoc/doc/qdoc-manual-intro.qdoc325
-rw-r--r--src/tools/qdoc/doc/qdoc-manual-markupcmds.qdoc4081
-rw-r--r--src/tools/qdoc/doc/qdoc-manual-qdocconf.qdoc1714
-rw-r--r--src/tools/qdoc/doc/qdoc-manual-topiccmds.qdoc1594
-rw-r--r--src/tools/qdoc/doc/qdoc-manual.qdoc78
-rw-r--r--src/tools/qdoc/doc/qdoc-minimum-qdocconf.qdoc89
-rw-r--r--src/tools/qdoc/doc/qtgui-qdocconf.qdoc299
42 files changed, 0 insertions, 12196 deletions
diff --git a/src/tools/qdoc/doc/config/qdoc.qdocconf b/src/tools/qdoc/doc/config/qdoc.qdocconf
deleted file mode 100644
index 9d841e9b64..0000000000
--- a/src/tools/qdoc/doc/config/qdoc.qdocconf
+++ /dev/null
@@ -1,72 +0,0 @@
-include($QT_INSTALL_DOCS/global/qt-module-defaults.qdocconf)
-
-project = QDoc
-description = QDoc Manual
-version = $QT_VERSION
-
-sourcedirs = ..
-
-exampledirs = .. \
- ../examples
-
-imagedirs = ../images \
- ../../../../widgets/doc/images
-# ../../../doc/src/templates/images
-
-tagfile = ../html/qdoc.tags
-
-examples.fileextensions = "*.cpp *.h *.js *.xq *.svg *.xml *.ui *.qhp *.qhcp *.qml *.css *.qdoc *.qdocinc *.sample"
-
-qhp.projects = QDoc
-
-qhp.QDoc.file = qdoc.qhp
-qhp.QDoc.namespace = org.qt-project.qdoc.$QT_VERSION_TAG
-qhp.QDoc.virtualFolder = qdoc
-qhp.QDoc.indexTitle = QDoc Manual
-qhp.QDoc.indexRoot =
-
-qhp.QDoc.filterAttributes = qdoc qtrefdoc
-qhp.QDoc.customFilters.QDoc.name = QDoc
-qhp.QDoc.customFilters.QDoc.filterAttributes = qdoc
-qhp.QDoc.subprojects = overviews
-qhp.QDoc.subprojects.overviews.title = Overviews
-qhp.QDoc.subprojects.overviews.indexTitle = QDoc Manual
-qhp.QDoc.subprojects.overviews.selectors = fake:page,group,module
-
-depends += \
- activeqt \
- qtassistant \
- qtbluetooth \
- qtconcurrent \
- qtcontacts \
- qtcore \
- qtdbus \
- qtdesigner \
- qtdoc \
- qthelp \
- qtimageformats \
- qtgui \
- qtlocation \
- qtlinguist \
- qtmultimedia \
- qtnetwork \
- qtopengl \
- qtorganizer \
- qtprintsupport \
- qtqml \
- qtquick \
- qtscript \
- qtscripttools \
- qtsensors \
- qtsql \
- qtsvg \
- qttestlib \
- qtuitools \
- qtversit \
- qtwidgets \
- qtwebkit \
- qtwebkitexamples \
- qtxml \
- qtxmlpatterns
-
-navigation.landingpage = "QDoc Manual"
diff --git a/src/tools/qdoc/doc/corefeatures.qdoc b/src/tools/qdoc/doc/corefeatures.qdoc
deleted file mode 100644
index bbee7410fe..0000000000
--- a/src/tools/qdoc/doc/corefeatures.qdoc
+++ /dev/null
@@ -1,35 +0,0 @@
-/****************************************************************************
-**
-** Copyright (C) 2015 The Qt Company Ltd.
-** Contact: http://www.qt.io/licensing/
-**
-** This file is part of the documentation of the Qt Toolkit.
-**
-** $QT_BEGIN_LICENSE:FDL$
-** Commercial License Usage
-** Licensees holding valid commercial Qt licenses may use this file in
-** accordance with the commercial license agreement provided with the
-** Software or, alternatively, in accordance with the terms contained in
-** a written agreement between you and The Qt Company. For licensing terms
-** and conditions see http://www.qt.io/terms-conditions. For further
-** information use the contact form at http://www.qt.io/contact-us.
-**
-** GNU Free Documentation License Usage
-** Alternatively, this file may be used under the terms of the GNU Free
-** Documentation License version 1.3 as published by the Free Software
-** Foundation and appearing in the file included in the packaging of
-** this file. Please review the following information to ensure
-** the GNU Free Documentation License version 1.3 requirements
-** will be met: http://www.gnu.org/copyleft/fdl.html.
-** $QT_END_LICENSE$
-**
-****************************************************************************/
-
-/*!
- \page corefeatures.html
- \title Core Features
-
- \input examples/signalandslots.qdocinc
- \input examples/objectmodel.qdocinc
- \input examples/layoutmanagement.qdocinc
-*/
diff --git a/src/tools/qdoc/doc/examples/componentset/ProgressBar.qml b/src/tools/qdoc/doc/examples/componentset/ProgressBar.qml
deleted file mode 100644
index c4e8c103e9..0000000000
--- a/src/tools/qdoc/doc/examples/componentset/ProgressBar.qml
+++ /dev/null
@@ -1,135 +0,0 @@
-/****************************************************************************
-**
-** Copyright (C) 2015 The Qt Company Ltd.
-** Contact: http://www.qt.io/licensing/
-**
-** This file is part of the examples of the Qt Toolkit.
-**
-** $QT_BEGIN_LICENSE:BSD$
-** You may use this file under the terms of the BSD license as follows:
-**
-** "Redistribution and use in source and binary forms, with or without
-** modification, are permitted provided that the following conditions are
-** met:
-** * Redistributions of source code must retain the above copyright
-** notice, this list of conditions and the following disclaimer.
-** * Redistributions in binary form must reproduce the above copyright
-** notice, this list of conditions and the following disclaimer in
-** the documentation and/or other materials provided with the
-** distribution.
-** * Neither the name of The Qt Company Ltd nor the names of its
-** contributors may be used to endorse or promote products derived
-** from this software without specific prior written permission.
-**
-**
-** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
-** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
-** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
-** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
-** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
-** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
-** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
-** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
-** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
-** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
-** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE."
-**
-** $QT_END_LICENSE$
-**
-****************************************************************************/
-
-import QtQuick 1.0
-
-/*!
- \qmltype ProgressBar
- \inqmlmodule UIComponents
- \brief A component that shows the progress of an event
-
- A ProgressBar shows the linear progress of an event as its \l value.
- The range is specified using the \l {minimum} and the \l{maximum} values.
-
- The ProgressBar component is part of the \l {UI Components} module.
-
- This documentation is part of the \l{componentset}{UIComponents} example.
-*/
-Item {
- id: progressbar
-
- /*!
- The minimum value of the ProgressBar range.
- The \l value must not be less than this value.
- */
- property int minimum: 0
-
- /*!
- The maximum value of the ProgressBar range.
- The \l value must not be more than this value.
- */
- property int maximum: 100
-
- /*!
- The value of the progress.
- */
- property int value: 0
-
- /*!
- \qmlproperty color ProgressBar::color
- The color of the ProgressBar's gradient. Must bind to a color type.
-
- \omit
- The "\qmlproperty <type> <property name>" is needed because
- property alias need to have their types manually entered.
-
- QDoc will not publish the documentation within omit and endomit.
- \endomit
-
- \sa secondColor
- */
- property alias color: gradient1.color
-
- /*!
- \qmlproperty color ProgressBar::secondColor
- The second color of the ProgressBar's gradient.
- Must bind to a color type.
-
- \omit
- The "\qmlproperty <type> <property name>" is needed because
- property alias need to have their types manually entered.
-
- QDoc will not publish the documentation within omit and endomit.
- \endomit
-
- \sa color
- */
- property alias secondColor: gradient2.color
-
- width: 250; height: 23
- clip: true
-
- Rectangle {
- id: highlight
-
- /*!
- An internal documentation comment. The widthDest property is not
- a public API and therefore will not be exposed.
- */
- property int widthDest: ((progressbar.width * (value - minimum)) / (maximum - minimum) - 6)
-
- width: highlight.widthDest
- Behavior on width { SmoothedAnimation { velocity: 1200 } }
-
- anchors { left: parent.left; top: parent.top; bottom: parent.bottom; margins: 3 }
- radius: 1
- gradient: Gradient {
- GradientStop { id: gradient1; position: 0.0 }
- GradientStop { id: gradient2; position: 1.0 }
- }
-
- }
- Text {
- anchors { right: highlight.right; rightMargin: 6; verticalCenter: parent.verticalCenter }
- color: "white"
- font.bold: true
- text: Math.floor((value - minimum) / (maximum - minimum) * 100) + '%'
- }
-}
diff --git a/src/tools/qdoc/doc/examples/componentset/Switch.qml b/src/tools/qdoc/doc/examples/componentset/Switch.qml
deleted file mode 100644
index 7b7e7af31f..0000000000
--- a/src/tools/qdoc/doc/examples/componentset/Switch.qml
+++ /dev/null
@@ -1,142 +0,0 @@
-/****************************************************************************
-**
-** Copyright (C) 2015 The Qt Company Ltd.
-** Contact: http://www.qt.io/licensing/
-**
-** This file is part of the examples of the Qt Toolkit.
-**
-** $QT_BEGIN_LICENSE:BSD$
-** You may use this file under the terms of the BSD license as follows:
-**
-** "Redistribution and use in source and binary forms, with or without
-** modification, are permitted provided that the following conditions are
-** met:
-** * Redistributions of source code must retain the above copyright
-** notice, this list of conditions and the following disclaimer.
-** * Redistributions in binary form must reproduce the above copyright
-** notice, this list of conditions and the following disclaimer in
-** the documentation and/or other materials provided with the
-** distribution.
-** * Neither the name of The Qt Company Ltd nor the names of its
-** contributors may be used to endorse or promote products derived
-** from this software without specific prior written permission.
-**
-**
-** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
-** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
-** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
-** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
-** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
-** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
-** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
-** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
-** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
-** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
-** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE."
-**
-** $QT_END_LICENSE$
-**
-****************************************************************************/
-
-import QtQuick 1.0
-
-/*!
- \qmltype ToggleSwitch
- \inqmlmodule UIComponents
- \brief A component that can be turned on or off
-
- A toggle switch has two states: an \c on and an \c off state. The \c off
- state is when the \l on property is set to \c false.
-
- The ToggleSwitch component is part of the \l {UI Components} module.
-
- This documentation is part of the \l{componentset}{UIComponents} example.
-
-*/
-Item {
- id: toggleswitch
- width: background.width; height: background.height
-
- /*!
- Indicates the state of the switch. If \c false, then the switch is in
- the \c off state.
-
- \omit
- The \qmlproperty <type> <propertyname> is not necessary as QDoc
- will associate this property to the ToggleSwitch
-
- QDoc will not publish the documentation within omit and endomit.
- \endomit
- */
- property bool on: false
-
-
- /*!
- A method to toggle the switch. If the switch is \c on, the toggling it
- will turn it \c off. Toggling a switch in the \c off position will
- turn it \c on.
- */
- function toggle() {
- if (toggleswitch.state == "on")
- toggleswitch.state = "off";
- else
- toggleswitch.state = "on";
- }
-
-
- /*!
- \internal
-
- An internal function to synchronize the switch's internals. This
- function is not for public access. The \internal command will
- prevent QDoc from publishing this comment in the public API.
- */
- function releaseSwitch() {
- if (knob.x == 1) {
- if (toggleswitch.state == "off") return;
- }
- if (knob.x == 78) {
- if (toggleswitch.state == "on") return;
- }
- toggle();
- }
-
- Rectangle {
- id: background
- width: 130; height: 48
- radius: 48
- color: "lightsteelblue"
- MouseArea { anchors.fill: parent; onClicked: toggle() }
- }
-
- Rectangle {
- id: knob
- width: 48; height: 48
- radius: width
- color: "lightblue"
-
- MouseArea {
- anchors.fill: parent
- drag.target: knob; drag.axis: Drag.XAxis; drag.minimumX: 1; drag.maximumX: 78
- onClicked: toggle()
- onReleased: releaseSwitch()
- }
- }
-
- states: [
- State {
- name: "on"
- PropertyChanges { target: knob; x: 78 }
- PropertyChanges { target: toggleswitch; on: true }
- },
- State {
- name: "off"
- PropertyChanges { target: knob; x: 1 }
- PropertyChanges { target: toggleswitch; on: false }
- }
- ]
-
- transitions: Transition {
- NumberAnimation { properties: "x"; easing.type: Easing.InOutQuad; duration: 200 }
- }
-}
diff --git a/src/tools/qdoc/doc/examples/componentset/TabWidget.qml b/src/tools/qdoc/doc/examples/componentset/TabWidget.qml
deleted file mode 100644
index 008c5e14e7..0000000000
--- a/src/tools/qdoc/doc/examples/componentset/TabWidget.qml
+++ /dev/null
@@ -1,183 +0,0 @@
-/****************************************************************************
-**
-** Copyright (C) 2015 The Qt Company Ltd.
-** Contact: http://www.qt.io/licensing/
-**
-** This file is part of the examples of the Qt Toolkit.
-**
-** $QT_BEGIN_LICENSE:BSD$
-** You may use this file under the terms of the BSD license as follows:
-**
-** "Redistribution and use in source and binary forms, with or without
-** modification, are permitted provided that the following conditions are
-** met:
-** * Redistributions of source code must retain the above copyright
-** notice, this list of conditions and the following disclaimer.
-** * Redistributions in binary form must reproduce the above copyright
-** notice, this list of conditions and the following disclaimer in
-** the documentation and/or other materials provided with the
-** distribution.
-** * Neither the name of The Qt Company Ltd nor the names of its
-** contributors may be used to endorse or promote products derived
-** from this software without specific prior written permission.
-**
-**
-** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
-** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
-** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
-** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
-** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
-** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
-** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
-** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
-** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
-** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
-** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE."
-**
-** $QT_END_LICENSE$
-**
-****************************************************************************/
-
-import QtQuick 1.0
-
-/*!
- \qmltype TabWidget
- \inqmlmodule UIComponents
- \brief A widget that places its children as tabs
-
- A TabWidget places its children as tabs in a view. Selecting
- a tab involves selecting the tab at the top.
-
- The TabWidget component is part of the \l {UI Components} module.
-
- This documentation is part of the \l{componentset}{UIComponents} example.
-
- \section1 Adding Tabs
-
- To add a tab, declare the tab as a child of the TabWidget.
-
- \code
- TabWidget {
- id: tabwidget
-
- Rectangle {
- id: tab1
- color: "red"
- //... omitted
- }
- Rectangle {
- id: tab2
- color: "blue"
- //... omitted
- }
-
- }
- \endcode
-
-*/
-Item {
- id: tabWidget
-
- /*!
- \internal
-
- Setting the default property to stack.children means any child items
- of the TabWidget are actually added to the 'stack' item's children.
-
- See the \l{"Property Binding in QML"}
- documentation for details on default properties.
-
- This is an implementation detail, not meant for public knowledge. Putting
- the \internal command at the beginning will cause QDoc to not publish this
- documentation in the public API page.
-
- Normally, a property alias needs to have a
- "\qmlproperty <type> <propertyname>" to assign the alias a type.
-
- */
- default property alias content: stack.children
-
-
- /*!
- The currently active tab in the TabWidget.
- */
- property int current: 0
-
- /*!
- A sample \c{read-only} property.
- A contrived property to demonstrate QDoc's ability to detect
- read-only properties.
-
- The signature is:
- \code
- readonly property int sampleReadOnlyProperty: 0
- \endcode
-
- Note that the property must be initialized to a value.
-
- */
- readonly property int sampleReadOnlyProperty: 0
-
- /*!
- \internal
-
- This handler is an implementation
- detail. The \c{\internal} command will prevent QDoc from publishing this
- documentation on the public API.
- */
- onCurrentChanged: setOpacities()
- Component.onCompleted: setOpacities()
-
- /*!
- \internal
-
- An internal function to set the opacity.
- The \internal command will prevent QDoc from publishing this
- documentation on the public API.
- */
- function setOpacities() {
- for (var i = 0; i < stack.children.length; ++i) {
- stack.children[i].opacity = (i == current ? 1 : 0)
- }
- }
-
- Row {
- id: header
-
- Repeater {
- model: stack.children.length
- delegate: Rectangle {
- width: tabWidget.width / stack.children.length; height: 36
-
- Rectangle {
- width: parent.width; height: 1
- anchors { bottom: parent.bottom; bottomMargin: 1 }
- color: "#acb2c2"
- }
- BorderImage {
- anchors { fill: parent; leftMargin: 2; topMargin: 5; rightMargin: 1 }
- border { left: 7; right: 7 }
- source: "tab.png"
- visible: tabWidget.current == index
- }
- Text {
- horizontalAlignment: Qt.AlignHCenter; verticalAlignment: Qt.AlignVCenter
- anchors.fill: parent
- text: stack.children[index].title
- elide: Text.ElideRight
- font.bold: tabWidget.current == index
- }
- MouseArea {
- anchors.fill: parent
- onClicked: tabWidget.current = index
- }
- }
- }
- }
-
- Item {
- id: stack
- width: tabWidget.width
- anchors.top: header.bottom; anchors.bottom: tabWidget.bottom
- }
-}
diff --git a/src/tools/qdoc/doc/examples/componentset/componentset.pro b/src/tools/qdoc/doc/examples/componentset/componentset.pro
deleted file mode 100644
index 5b44737c2d..0000000000
--- a/src/tools/qdoc/doc/examples/componentset/componentset.pro
+++ /dev/null
@@ -1,5 +0,0 @@
-SOURCES = componentset.pro \
- ProgressBar.qml \
- Switch.qml \
- TabWidget.qml \
- uicomponents.qdoc
diff --git a/src/tools/qdoc/doc/examples/componentset/uicomponents.qdoc.sample b/src/tools/qdoc/doc/examples/componentset/uicomponents.qdoc.sample
deleted file mode 100644
index 7a14f88f45..0000000000
--- a/src/tools/qdoc/doc/examples/componentset/uicomponents.qdoc.sample
+++ /dev/null
@@ -1,38 +0,0 @@
-/****************************************************************************
-**
-** Copyright (C) 2015 The Qt Company Ltd.
-** Contact: http://www.qt.io/licensing/
-**
-** This file is part of the documentation of the Qt Toolkit.
-**
-** $QT_BEGIN_LICENSE:FDL$
-** Commercial License Usage
-** Licensees holding valid commercial Qt licenses may use this file in
-** accordance with the commercial license agreement provided with the
-** Software or, alternatively, in accordance with the terms contained in
-** a written agreement between you and The Qt Company. For licensing terms
-** and conditions see http://www.qt.io/terms-conditions. For further
-** information use the contact form at http://www.qt.io/contact-us.
-**
-** GNU Free Documentation License Usage
-** Alternatively, this file may be used under the terms of the GNU Free
-** Documentation License version 1.3 as published by the Free Software
-** Foundation and appearing in the file included in the packaging of
-** this file. Please review the following information to ensure
-** the GNU Free Documentation License version 1.3 requirements
-** will be met: http://www.gnu.org/copyleft/fdl.html.
-** $QT_END_LICENSE$
-**
-****************************************************************************/
-
-/*!
- \qmlmodule UIComponents 1.0
- \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 module is part of the \l{componentset}{UIComponents} example.
-*/
diff --git a/src/tools/qdoc/doc/examples/cpp.qdoc.sample b/src/tools/qdoc/doc/examples/cpp.qdoc.sample
deleted file mode 100644
index 38a131783b..0000000000
--- a/src/tools/qdoc/doc/examples/cpp.qdoc.sample
+++ /dev/null
@@ -1,126 +0,0 @@
-/****************************************************************************
-**
-** Copyright (C) 2015 The Qt Company Ltd.
-** Contact: http://www.qt.io/licensing/
-**
-** This file is part of the documentation of the Qt Toolkit.
-**
-** $QT_BEGIN_LICENSE:FDL$
-** Commercial License Usage
-** Licensees holding valid commercial Qt licenses may use this file in
-** accordance with the commercial license agreement provided with the
-** Software or, alternatively, in accordance with the terms contained in
-** a written agreement between you and The Qt Company. For licensing terms
-** and conditions see http://www.qt.io/terms-conditions. For further
-** information use the contact form at http://www.qt.io/contact-us.
-**
-** GNU Free Documentation License Usage
-** Alternatively, this file may be used under the terms of the GNU Free
-** Documentation License version 1.3 as published by the Free Software
-** Foundation and appearing in the file included in the packaging of
-** this file. Please review the following information to ensure
-** the GNU Free Documentation License version 1.3 requirements
-** will be met: http://www.gnu.org/copyleft/fdl.html.
-** $QT_END_LICENSE$
-**
-****************************************************************************/
-
-//![class]
-/*!
- \class QCache
- \brief The QCache class is a template class that provides a cache.
-
- \ingroup tools
- \ingroup shared
-
- \reentrant
-
- QCache\<Key, T\> defines a cache that stores objects of type T
- associated with keys of type Key. For example, here's the
- definition of a cache that stores objects of type Employee
- associated with an integer key:
-
- \snippet code/doc_src_qcache.cpp 0
-
- Here's how to insert an object in the cache:
-
- \snippet code/doc_src_qcache.cpp 1
-
- ... detailed description ommitted
-
- \sa QPixmapCache, QHash, QMap
-*/
-//![class]
-
-//![function]
-/*!
- \fn QString &QString::remove(int position, int n)
-
- Removes \a n characters from the string, starting at the given \a
- position index, and returns a reference to the string.
-
- If the specified \a position index is within the string, but \a
- position + \a n is beyond the end of the string, the string is
- truncated at the specified \a position.
-
- \snippet qstring/main.cpp 37
-
- \sa insert(), replace()
-*/
-QString &QString::remove(int pos, int len)
-//! [function]
-
-//! [return]
-/*!
- Returns \c true if a QScroller object was already created for \a target; \c false otherwise.
-
- \sa scroller()
-*/
-bool QScroller::hasScroller(QObject *target)
-//! [return]
-
-//! [property]
-/*!
- \property QVariantAnimation::duration
- \brief the duration of the animation
-
- This property describes the duration in milliseconds of the
- animation. The default duration is 250 milliseconds.
-
- \sa QAbstractAnimation::duration()
- */
-int QVariantAnimation::duration() const
-//! [property]
-
-//! [signals]
-/*!
- \fn QAbstractTransition::triggered()
-
- This signal is emitted when the transition has been triggered (after
- onTransition() has been called).
-*/
-//! [signals]
-
-//! [enums]
-/*!
- \enum QSql::TableType
-
- This enum type describes types of SQL tables.
-
- \value Tables All the tables visible to the user.
- \value SystemTables Internal tables used by the database.
- \value Views All the views visible to the user.
- \value AllTables All of the above.
-*/
-//! [enums]
-
-//! [overloaded notifier]
-/*!
-\property QSpinBox::value
-\brief the value of the spin box
-
-setValue() will emit valueChanged() if the new value is different
-from the old one. The \l{QSpinBox::}{value} property has a second notifier
-signal which includes the spin box's prefix and suffix.
-*/
-//! [overloaded notifier]
diff --git a/src/tools/qdoc/doc/examples/examples.qdoc b/src/tools/qdoc/doc/examples/examples.qdoc
deleted file mode 100644
index 28810e30da..0000000000
--- a/src/tools/qdoc/doc/examples/examples.qdoc
+++ /dev/null
@@ -1,97 +0,0 @@
-/****************************************************************************
-**
-** Copyright (C) 2015 The Qt Company Ltd.
-** Contact: http://www.qt.io/licensing/
-**
-** This file is part of the documentation of the Qt Toolkit.
-**
-** $QT_BEGIN_LICENSE:FDL$
-** Commercial License Usage
-** Licensees holding valid commercial Qt licenses may use this file in
-** accordance with the commercial license agreement provided with the
-** Software or, alternatively, in accordance with the terms contained in
-** a written agreement between you and The Qt Company. For licensing terms
-** and conditions see http://www.qt.io/terms-conditions. For further
-** information use the contact form at http://www.qt.io/contact-us.
-**
-** GNU Free Documentation License Usage
-** Alternatively, this file may be used under the terms of the GNU Free
-** Documentation License version 1.3 as published by the Free Software
-** Foundation and appearing in the file included in the packaging of
-** this file. Please review the following information to ensure
-** the GNU Free Documentation License version 1.3 requirements
-** will be met: http://www.gnu.org/copyleft/fdl.html.
-** $QT_END_LICENSE$
-**
-****************************************************************************/
-
-/*!
- \example componentset
- \title QML Documentation Example
-
- This example demonstrates one of the ways to document QML types.
-
- In particular, there are sample types that are documented with QDoc
- commands comments. There are documentation comments for the QML types
- and their public interfaces. The types are grouped into a module, the
- \l{UI Components} module.
-
- The \l{componentset/uicomponents.qdoc.sample}{uicomponents.qdoc} file generates
- the overview page for the \l{UI Components} module page.
-
- The generated documentation is available in the \l{UI Components} module.
-
- \section1 QML Class
-
- The QML types use the \l{qmltype-command}{\\qmltype} to document the
- type. In addition, they have the \l{inmodule-command}{\\inmodule}
- command in order for QDoc to associate them to the \c UIComponents module.
-
- QDoc uses the \l{brief-command}{\\brief} command to place a basic
- description when listing the types.
-
- \section1 Properties, Signals, Handlers, and Methods
-
- The types have their properties, signals, handlers, and methods
- defined in their respective QML files. QDoc associates the properties and
- methods to the types, therefore, you only need to place the
- documentation above the property, method, or signal.
-
- To document the type of a \e {property alias}, you must use the
- \l{qmlproperty-command}{\\qmlproperty} command to specify the data type.
-
- \code
- \qmlproperty int anAliasedProperty
- An aliased property of type int.
- \endcode
-
- \section2 Internal Documentation
-
- You may declare that a documentation is for internal use by placing the
- \l{internal-command}{\\internal} command after the beginning QDoc comment
- \begincomment. QDoc will prevent the internal documentation from appearing
- in the public API.
-
- If you wish to omit certain parts of the documentation, you may use the
- \l{omit-command}{\\omit} and \l{omit-command}{\\endomit} command.
-
- \section1 QML Types with C++ Implementation
-
- This example only demonstrates the documentation for types in QML
- files, but the regular \l{qml-documentation}{QML commands} may be placed
- inside C++ classes to define the public API of the QML type.
-
-*/
-
-
-/*!
- \qmlmodule UIComponents 1.0
- \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 on the
- \l{Qt Quick Examples and Tutorials}{Qt Quick Code Samples}.
-
- This module is part of the \l{componentset}{UIComponents} example.
-*/
diff --git a/src/tools/qdoc/doc/examples/layoutmanagement.qdocinc b/src/tools/qdoc/doc/examples/layoutmanagement.qdocinc
deleted file mode 100644
index 780b03c8ff..0000000000
--- a/src/tools/qdoc/doc/examples/layoutmanagement.qdocinc
+++ /dev/null
@@ -1,13 +0,0 @@
-\section1 Layout Classes
-
-The Qt layout system provides a simple and powerful way of specifying
-the layout of child widgets.
-
-By specifying the logical layout once, you get the following benefits:
-
-\list
- \li Positioning of child widgets.
- \li Sensible default sizes for windows.
- \li Sensible minimum sizes for windows.
- \li ...
-\endlist
diff --git a/src/tools/qdoc/doc/examples/main.cpp b/src/tools/qdoc/doc/examples/main.cpp
deleted file mode 100644
index 849405e0ae..0000000000
--- a/src/tools/qdoc/doc/examples/main.cpp
+++ /dev/null
@@ -1,46 +0,0 @@
-/****************************************************************************
-**
-** Copyright (C) 2015 The Qt Company Ltd.
-** Contact: http://www.qt.io/licensing/
-**
-** This file is part of the tools applications of the Qt Toolkit.
-**
-** $QT_BEGIN_LICENSE:LGPL21$
-** Commercial License Usage
-** Licensees holding valid commercial Qt licenses may use this file in
-** accordance with the commercial license agreement provided with the
-** Software or, alternatively, in accordance with the terms contained in
-** a written agreement between you and The Qt Company. For licensing terms
-** and conditions see http://www.qt.io/terms-conditions. For further
-** information use the contact form at http://www.qt.io/contact-us.
-**
-** GNU Lesser General Public License Usage
-** Alternatively, this file may be used under the terms of the GNU Lesser
-** General Public License version 2.1 or version 3 as published by the Free
-** Software Foundation and appearing in the file LICENSE.LGPLv21 and
-** LICENSE.LGPLv3 included in the packaging of this file. Please review the
-** following information to ensure the GNU Lesser General Public License
-** requirements will be met: https://www.gnu.org/licenses/lgpl.html and
-** http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html.
-**
-** As a special exception, The Qt Company gives you certain additional
-** rights. These rights are described in The Qt Company LGPL Exception
-** version 1.1, included in the file LGPL_EXCEPTION.txt in this package.
-**
-** $QT_END_LICENSE$
-**
-****************************************************************************/
-
-#include <QApplication>
-#include <QPushButton>
-
-int main(int argc, char *argv[])
-{
- QApplication app(argc, argv);
-
- QPushButton hello("Hello world!");
- hello.resize(100, 30);
-
- hello.show();
- return app.exec();
-}
diff --git a/src/tools/qdoc/doc/examples/mainwindow.cpp b/src/tools/qdoc/doc/examples/mainwindow.cpp
deleted file mode 100644
index 68b878c07e..0000000000
--- a/src/tools/qdoc/doc/examples/mainwindow.cpp
+++ /dev/null
@@ -1,243 +0,0 @@
-/****************************************************************************
-**
-** Copyright (C) 2015 The Qt Company Ltd.
-** Contact: http://www.qt.io/licensing/
-**
-** This file is part of the tools applications of the Qt Toolkit.
-**
-** $QT_BEGIN_LICENSE:LGPL21$
-** Commercial License Usage
-** Licensees holding valid commercial Qt licenses may use this file in
-** accordance with the commercial license agreement provided with the
-** Software or, alternatively, in accordance with the terms contained in
-** a written agreement between you and The Qt Company. For licensing terms
-** and conditions see http://www.qt.io/terms-conditions. For further
-** information use the contact form at http://www.qt.io/contact-us.
-**
-** GNU Lesser General Public License Usage
-** Alternatively, this file may be used under the terms of the GNU Lesser
-** General Public License version 2.1 or version 3 as published by the Free
-** Software Foundation and appearing in the file LICENSE.LGPLv21 and
-** LICENSE.LGPLv3 included in the packaging of this file. Please review the
-** following information to ensure the GNU Lesser General Public License
-** requirements will be met: https://www.gnu.org/licenses/lgpl.html and
-** http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html.
-**
-** As a special exception, The Qt Company gives you certain additional
-** rights. These rights are described in The Qt Company LGPL Exception
-** version 1.1, included in the file LGPL_EXCEPTION.txt in this package.
-**
-** $QT_END_LICENSE$
-**
-****************************************************************************/
-
-#include <QtWidgets>
-
-#include "mainwindow.h"
-#include "scribblearea.h"
-
-//! [0]
-MainWindow::MainWindow()
-{
- scribbleArea = new ScribbleArea;
- setCentralWidget(scribbleArea);
-
- createActions();
- createMenus();
-
- setWindowTitle(tr("Scribble"));
- resize(500, 500);
-}
-//! [0]
-
-//! [1]
-void MainWindow::closeEvent(QCloseEvent *event)
-//! [1] //! [2]
-{
- if (maybeSave()) {
- event->accept();
- } else {
- event->ignore();
- }
-}
-//! [2]
-
-//! [3]
-void MainWindow::open()
-//! [3] //! [4]
-{
- if (maybeSave()) {
- QString fileName = QFileDialog::getOpenFileName(this,
- tr("Open File"), QDir::currentPath());
- if (!fileName.isEmpty())
- scribbleArea->openImage(fileName);
- }
-}
-//! [4]
-
-//! [5]
-void MainWindow::save()
-//! [5] //! [6]
-{
- QAction *action = qobject_cast<QAction *>(sender());
- QByteArray fileFormat = action->data().toByteArray();
- saveFile(fileFormat);
-}
-//! [6]
-
-//! [7]
-void MainWindow::penColor()
-//! [7] //! [8]
-{
- QColor newColor = QColorDialog::getColor(scribbleArea->penColor());
- if (newColor.isValid())
- scribbleArea->setPenColor(newColor);
-}
-//! [8]
-
-//! [9]
-void MainWindow::penWidth()
-//! [9] //! [10]
-{
- bool ok;
- int newWidth = QInputDialog::getInteger(this, tr("Scribble"),
- tr("Select pen width:"),
- scribbleArea->penWidth(),
- 1, 50, 1, &ok);
- if (ok)
- scribbleArea->setPenWidth(newWidth);
-}
-//! [10]
-
-//! [11]
-void MainWindow::about()
-//! [11] //! [12]
-{
- QMessageBox::about(this, tr("About Scribble"),
- tr("<p>The <b>Scribble</b> example shows how to use QMainWindow as the "
- "base widget for an application, and how to reimplement some of "
- "QWidget's event handlers to receive the events generated for "
- "the application's widgets:</p><p> We reimplement the mouse event "
- "handlers to facilitate drawing, the paint event handler to "
- "update the application and the resize event handler to optimize "
- "the application's appearance. In addition we reimplement the "
- "close event handler to intercept the close events before "
- "terminating the application.</p><p> The example also demonstrates "
- "how to use QPainter to draw an image in real time, as well as "
- "to repaint widgets.</p>"));
-}
-//! [12]
-
-//! [13]
-void MainWindow::createActions()
-//! [13] //! [14]
-{
- openAct = new QAction(tr("&Open..."), this);
- openAct->setShortcuts(QKeySequence::Open);
- connect(openAct, SIGNAL(triggered()), this, SLOT(open()));
-
- foreach (const QByteArray &format, QImageWriter::supportedImageFormats()) {
- QString text = tr("%1...").arg(QString(format).toUpper());
-
- QAction *action = new QAction(text, this);
- action->setData(format);
- connect(action, SIGNAL(triggered()), this, SLOT(save()));
- saveAsActs.append(action);
- }
-
- printAct = new QAction(tr("&Print..."), this);
- connect(printAct, SIGNAL(triggered()), scribbleArea, SLOT(print()));
-
- exitAct = new QAction(tr("E&xit"), this);
- exitAct->setShortcuts(QKeySequence::Quit);
- connect(exitAct, SIGNAL(triggered()), this, SLOT(close()));
-
- penColorAct = new QAction(tr("&Pen Color..."), this);
- connect(penColorAct, SIGNAL(triggered()), this, SLOT(penColor()));
-
- penWidthAct = new QAction(tr("Pen &Width..."), this);
- connect(penWidthAct, SIGNAL(triggered()), this, SLOT(penWidth()));
-
- clearScreenAct = new QAction(tr("&Clear Screen"), this);
- clearScreenAct->setShortcut(tr("Ctrl+L"));
- connect(clearScreenAct, SIGNAL(triggered()),
- scribbleArea, SLOT(clearImage()));
-
- aboutAct = new QAction(tr("&About"), this);
- connect(aboutAct, SIGNAL(triggered()), this, SLOT(about()));
-
- aboutQtAct = new QAction(tr("About &Qt"), this);
- connect(aboutQtAct, SIGNAL(triggered()), qApp, SLOT(aboutQt()));
-}
-//! [14]
-
-//! [15]
-void MainWindow::createMenus()
-//! [15] //! [16]
-{
- saveAsMenu = new QMenu(tr("&Save As"), this);
- foreach (QAction *action, saveAsActs)
- saveAsMenu->addAction(action);
-
- fileMenu = new QMenu(tr("&File"), this);
- fileMenu->addAction(openAct);
- fileMenu->addMenu(saveAsMenu);
- fileMenu->addAction(printAct);
- fileMenu->addSeparator();
- fileMenu->addAction(exitAct);
-
- optionMenu = new QMenu(tr("&Options"), this);
- optionMenu->addAction(penColorAct);
- optionMenu->addAction(penWidthAct);
- optionMenu->addSeparator();
- optionMenu->addAction(clearScreenAct);
-
- helpMenu = new QMenu(tr("&Help"), this);
- helpMenu->addAction(aboutAct);
- helpMenu->addAction(aboutQtAct);
-
- menuBar()->addMenu(fileMenu);
- menuBar()->addMenu(optionMenu);
- menuBar()->addMenu(helpMenu);
-}
-//! [16]
-
-//! [17]
-bool MainWindow::maybeSave()
-//! [17] //! [18]
-{
- if (scribbleArea->isModified()) {
- QMessageBox::StandardButton ret;
- ret = QMessageBox::warning(this, tr("Scribble"),
- tr("The image has been modified.\n"
- "Do you want to save your changes?"),
- QMessageBox::Save | QMessageBox::Discard
- | QMessageBox::Cancel);
- if (ret == QMessageBox::Save) {
- return saveFile("png");
- } else if (ret == QMessageBox::Cancel) {
- return false;
- }
- }
- return true;
-}
-//! [18]
-
-//! [19]
-bool MainWindow::saveFile(const QByteArray &fileFormat)
-//! [19] //! [20]
-{
- QString initialPath = QDir::currentPath() + "/untitled." + fileFormat;
-
- QString fileName = QFileDialog::getSaveFileName(this, tr("Save As"),
- initialPath,
- tr("%1 Files (*.%2);;All Files (*)")
- .arg(QString(fileFormat.toUpper()))
- .arg(QString(fileFormat)));
- if (fileName.isEmpty()) {
- return false;
- } else {
- return scribbleArea->saveImage(fileName, fileFormat);
- }
-}
-//! [20]
diff --git a/src/tools/qdoc/doc/examples/minimum.qdocconf b/src/tools/qdoc/doc/examples/minimum.qdocconf
deleted file mode 100644
index e360685f1d..0000000000
--- a/src/tools/qdoc/doc/examples/minimum.qdocconf
+++ /dev/null
@@ -1,38 +0,0 @@
-# QDoc is a tool that constantly evolves to suit our needs,
-# and there are some compatibility issues between old and new
-# practices. For that reason, any QDoc configuration file needs to
-# include compat.qdocconf.
-
-#include(compat.qdocconf)
-
-
-# The outputdir variable specifies the directory
-# where QDoc will put the generated documentation.
-
-outputdir = html
-
-
-# The headerdirs variable specifies the directories
-# containing the header files associated
-# with the .cpp source files used in the documentation.
-
-headerdirs = .
-
-
-# The sourcedirs variable specifies the
-# directories containing the .cpp or .qdoc
-# files used in the documentation.
-
-#sourcedirs = .
-
-
-# The exampledirs variable specifies the directories containing
-# the source code of the example files.
-
-exampledirs = .
-
-
-# The imagedirs variable specifies the
-# directories containing the images used in the documentation.
-
-imagedirs = ./images
diff --git a/src/tools/qdoc/doc/examples/objectmodel.qdocinc b/src/tools/qdoc/doc/examples/objectmodel.qdocinc
deleted file mode 100644
index 02b5991c4d..0000000000
--- a/src/tools/qdoc/doc/examples/objectmodel.qdocinc
+++ /dev/null
@@ -1,11 +0,0 @@
-\section1 Qt Object Model
-
-The standard C++ object model provides very efficient runtime support
-for the object paradigm. But its static nature is inflexibile in
-certain problem domains. Graphical user interface programming is a
-domain that requires both runtime efficiency and a high level of
-flexibility. Qt provides this, by combining the speed of C++ with the
-flexibility of the Qt Object Model.
-
-...
-
diff --git a/src/tools/qdoc/doc/examples/qml.qdoc.sample b/src/tools/qdoc/doc/examples/qml.qdoc.sample
deleted file mode 100644
index cacd912242..0000000000
--- a/src/tools/qdoc/doc/examples/qml.qdoc.sample
+++ /dev/null
@@ -1,116 +0,0 @@
-/****************************************************************************
-**
-** Copyright (C) 2015 The Qt Company Ltd.
-** Contact: http://www.qt.io/licensing/
-**
-** This file is part of the documentation of the Qt Toolkit.
-**
-** $QT_BEGIN_LICENSE:FDL$
-** Commercial License Usage
-** Licensees holding valid commercial Qt licenses may use this file in
-** accordance with the commercial license agreement provided with the
-** Software or, alternatively, in accordance with the terms contained in
-** a written agreement between you and The Qt Company. For licensing terms
-** and conditions see http://www.qt.io/terms-conditions. For further
-** information use the contact form at http://www.qt.io/contact-us.
-**
-** GNU Free Documentation License Usage
-** Alternatively, this file may be used under the terms of the GNU Free
-** Documentation License version 1.3 as published by the Free Software
-** Foundation and appearing in the file included in the packaging of
-** this file. Please review the following information to ensure
-** the GNU Free Documentation License version 1.3 requirements
-** will be met: http://www.gnu.org/copyleft/fdl.html.
-** $QT_END_LICENSE$
-**
-****************************************************************************/
-
-//![qmltype]
- \qmltype TextEdit
- \instantiates QQuickTextEdit
- \inqmlmodule QtQuick
- \ingroup qtquick-visual
- \ingroup qtquick-input
- \inherits Item
- \brief Displays multiple lines of editable formatted text
-
- The TextEdit item displays a block of editable, formatted text.
-
- It can display both plain and rich text. For example:
-
- \qml
- TextEdit {
- width: 240
- text: "<b>Hello</b> <i>World!</i>"
- font.family: "Helvetica"
- font.pointSize: 20
- color: "blue"
- focus: true
- }
- \endqml
-
- \image declarative-textedit.gif
-
- ... omitted detailed description
-
- \sa Text, TextInput, {examples/quick/text/textselection}{Text Selection example}
-//![qmltype]
-
-//![function]
-/*
- \qmlmethod QtQuick2::ListModel::remove(int index, int count = 1)
-
- Deletes the content at \a index from the model.
-
- \sa clear()
-*/
-void QQuickListModel::remove(QQmlV8Function *args)
-//! [function]
-
-//! [return]
-/*
- Returns \c true if a QScroller object was already created for \a target; \c false otherwise.
-
- \sa scroller()
-*/
-bool QScroller::hasScroller(QObject *target)
-//! [return]
-
-//! [property]
-/*
- \property QVariantAnimation::duration
- \brief the duration of the animation
-
- This property describes the duration in milliseconds of the
- animation. The default duration is 250 milliseconds.
-
- \sa QAbstractAnimation::duration()
- */
-int QVariantAnimation::duration() const
-//! [property]
-
-//! [signals]
-/*
- This signal is emitted when the user clicks the button. A click is defined
- as a press followed by a release. The corresponding handler is
- \c onClicked.
-*/
-signal clicked()
-//! [signals]
-
-//! [enums]
-/*!
-\qmlproperty enumeration QtQuick2::Text::font.weight
-
-Sets the font's weight.
-
-The weight can be one of:
-\list
-\li Font.Light
-\li Font.Normal - the default
-\li Font.DemiBold
-\li Font.Bold
-\li Font.Black
-\endlist
-*/
-//! [enums]
diff --git a/src/tools/qdoc/doc/examples/samples.qdocinc b/src/tools/qdoc/doc/examples/samples.qdocinc
deleted file mode 100644
index d5679fdcd8..0000000000
--- a/src/tools/qdoc/doc/examples/samples.qdocinc
+++ /dev/null
@@ -1,109 +0,0 @@
-/****************************************************************************
-**
-** Copyright (C) 2015 The Qt Company Ltd.
-** Contact: http://www.qt.io/licensing/
-**
-** This file is part of the documentation of the Qt Toolkit.
-**
-** $QT_BEGIN_LICENSE:FDL$
-** Commercial License Usage
-** Licensees holding valid commercial Qt licenses may use this file in
-** accordance with the commercial license agreement provided with the
-** Software or, alternatively, in accordance with the terms contained in
-** a written agreement between you and The Qt Company. For licensing terms
-** and conditions see http://www.qt.io/terms-conditions. For further
-** information use the contact form at http://www.qt.io/contact-us.
-**
-** GNU Free Documentation License Usage
-** Alternatively, this file may be used under the terms of the GNU Free
-** Documentation License version 1.3 as published by the Free Software
-** Foundation and appearing in the file included in the packaging of
-** this file. Please review the following information to ensure
-** the GNU Free Documentation License version 1.3 requirements
-** will be met: http://www.gnu.org/copyleft/fdl.html.
-** $QT_END_LICENSE$
-**
-****************************************************************************/
-
-//! [qvector3d-class]
-/*!
- \class QVector3D
- \brief The QVector3D class represents a vector or vertex in 3D space.
- \since 4.6
- \ingroup painting-3D
-
- Vectors are one of the main building blocks of 3D representation and
- drawing. They consist of three coordinates, traditionally called
- x, y, and z.
-
- The QVector3D class can also be used to represent vertices in 3D space.
- We therefore do not need to provide a separate vertex class.
-
- \b{Note:} By design values in the QVector3D instance are stored as \c float.
- This means that on platforms where the \c qreal arguments to QVector3D
- functions are represented by \c double values, it is possible to
- lose precision.
-
- \sa QVector2D, QVector4D, QQuaternion
-*/
-//! [qvector3d-class]
-
-//! [qvector3d-function]
-/*!
- \fn QVector3D::QVector3D(const QPoint& point)
-
- Constructs a vector with x and y coordinates from a 2D \a point, and a
- z coordinate of 0.
-*/
-//! [qvector3d-function]
-
-//! [sample-page]
-/*!
- \page generic-guide.html
- \title Generic QDoc Guide
- \nextpage Creating QDoc Configuration Files
- There are three essential materials for generating documentation with qdoc:
-
- \list
- \li \c qdoc binary
- \li \c qdocconf configuration files
- \li \c Documentation in \c C++, \c QML, and \c .qdoc files
- \endlist
-*/
-//! [sample-page]
-
-//! [sample-faq]
-/*!
- \page altruism-faq.html faq
- \title Altruism Frequently Asked Questions
-
- \brief All the questions about altruism, answered.
-
- ...
-*/
-//! [sample-faq]
-
-//! [sample-example]
-/*!
- \title UI Components: Tab Widget Example
- \example declarative/ui-components/tabwidget
-
- This example shows how to create a tab widget. It also demonstrates how
- \l {Property aliases}{property aliases} and
- \l {Introduction to the QML Language#Default Properties}{default properties} can be used to collect and
- assemble the child items declared within an \l Item.
-
- \image qml-tabwidget-example.png
-*/
-//! [sample-example]
-
-//! [sample-overview]
-/*!
- \page overview-qt-technology.html overview
- \title Overview of a Qt Technology
-
- \brief provides a technology never seen before.
-
-*/
-//! [sample-overview]
-
diff --git a/src/tools/qdoc/doc/examples/signalandslots.qdocinc b/src/tools/qdoc/doc/examples/signalandslots.qdocinc
deleted file mode 100644
index e14ede1441..0000000000
--- a/src/tools/qdoc/doc/examples/signalandslots.qdocinc
+++ /dev/null
@@ -1,9 +0,0 @@
-\section1 Signals and Slots
-
-Signals and slots are used for communication between objects. The signals and
-slots mechanism is a central feature of Qt and probably the part that differs
-most from the features provided by other frameworks.
-
-\section2 Introduction
-
-In GUI programming, when we ...
diff --git a/src/tools/qdoc/doc/files/basicqt.qdoc.sample b/src/tools/qdoc/doc/files/basicqt.qdoc.sample
deleted file mode 100644
index ce8df096fa..0000000000
--- a/src/tools/qdoc/doc/files/basicqt.qdoc.sample
+++ /dev/null
@@ -1,67 +0,0 @@
- /*!
- \page basicqt.html
- \contentspage {Basic Qt} {Contents}
- \nextpage Getting Started
-
- \indexpage Index
- \startpage Basic Qt
-
- \title Basic Qt
-
- The Qt toolkit is a C++ class library and a set of tools for
- building multiplatform GUI programs using a "write once,
- compile anywhere approach".
-
- Table of contents:
-
- \list
- \li \l {Getting Started}
- \li \l {Creating Dialogs}
- \li \l {Creating Main Windows}
- \endlist
- */
-
- /*!
- \page gettingstarted.html
- \previouspage Basic Qt
- \contentspage {Basic Qt} {Contents}
- \nextpage Creating Dialogs
-
- \indexpage Index
- \startpage Basic Qt
-
- \title Getting Started
-
- This chapter shows how to combine basic C++ with the
- functionality provided by Qt to create a few small graphical
- interface (GUI) applications.
-*/
-
-/ *!
- \page creatingdialogs.html
- \previouspage Getting Started
- \contentspage {Basic Qt} {Contents}
-
- \indexpage Index
- \startpage Basic Qt
-
- \title Creating Dialogs
-
- This chapter will teach you how to create dialog boxes using Qt.
-*/
-
-/*!
- \page index.html
-
- \indexpage Index
- \startpage Basic Qt
-
- \title Index
-
- \list
- \li \l {Basic Qt}
- \li \l {Creating Dialogs}
- \li \l {Getting Started}
- \endlist
-*/
-
diff --git a/src/tools/qdoc/doc/files/compat.qdocconf b/src/tools/qdoc/doc/files/compat.qdocconf
deleted file mode 100644
index 3e7ea6c891..0000000000
--- a/src/tools/qdoc/doc/files/compat.qdocconf
+++ /dev/null
@@ -1,12 +0,0 @@
-alias.include = input
-
-macro.0 = "\\\\0"
-macro.b = "\\\\b"
-macro.n = "\\\\n"
-macro.r = "\\\\r"
-macro.img = "\\image"
-macro.endquote = "\\endquotation"
-macro.relatesto = "\\relates"
-
-spurious = "Missing comma in .*" \
- "Missing pattern .*"
diff --git a/src/tools/qdoc/doc/files/qtgui.qdocconf b/src/tools/qdoc/doc/files/qtgui.qdocconf
deleted file mode 100644
index 0b2d281081..0000000000
--- a/src/tools/qdoc/doc/files/qtgui.qdocconf
+++ /dev/null
@@ -1,49 +0,0 @@
-include($QT_INSTALL_DOCS/global/qt-module-defaults.qdocconf)
-
-project = QtGui
-description = Qt GUI Reference Documentation
-version = $QT_VERSION
-
-examplesinstallpath = qtbase/gui
-
-qhp.projects = QtGui
-
-qhp.QtGui.file = qtgui.qhp
-qhp.QtGui.namespace = org.qt-project.qtgui.$QT_VERSION_TAG
-qhp.QtGui.virtualFolder = qtgui
-qhp.QtGui.indexTitle = Qt GUI
-qhp.QtGui.indexRoot =
-
-qhp.QtGui.filterAttributes = qtgui $QT_VERSION qtrefdoc
-qhp.QtGui.customFilters.Qt.name = Qtgui $QT_VERSION
-qhp.QtGui.customFilters.Qt.filterAttributes = qtgui $QT_VERSION
-
-qhp.QtGui.subprojects = classes
-qhp.QtGui.subprojects.classes.title = C++ Classes
-qhp.QtGui.subprojects.classes.indexTitle = Qt GUI C++ Classes
-qhp.QtGui.subprojects.classes.selectors = class fake:headerfile
-qhp.QtGui.subprojects.classes.sortPages = true
-
-tagfile = ../../../doc/qtgui/qtgui.tags
-
-depends += \
- qtcore \
- qtnetwork \
- qtopengl \
- qtsvg \
- qtqml \
- qtquick \
- qtwidgets \
- qtdoc
-
-headerdirs += ..
-
-sourcedirs += .. \
- ../../../examples/gui/doc/src
-
-exampledirs += ../../../examples/gui \
- snippets
-
-imagedirs += images \
- ../../../examples/gui/doc/images \
- ../../../doc/src/images \
diff --git a/src/tools/qdoc/doc/images/happy.gif b/src/tools/qdoc/doc/images/happy.gif
deleted file mode 100644
index a4597f6fa8..0000000000
--- a/src/tools/qdoc/doc/images/happy.gif
+++ /dev/null
Binary files differ
diff --git a/src/tools/qdoc/doc/images/happyguy.jpg b/src/tools/qdoc/doc/images/happyguy.jpg
deleted file mode 100644
index e8604793c2..0000000000
--- a/src/tools/qdoc/doc/images/happyguy.jpg
+++ /dev/null
Binary files differ
diff --git a/src/tools/qdoc/doc/images/link-to-qquickitem.png b/src/tools/qdoc/doc/images/link-to-qquickitem.png
deleted file mode 100644
index 00e03c3717..0000000000
--- a/src/tools/qdoc/doc/images/link-to-qquickitem.png
+++ /dev/null
Binary files differ
diff --git a/src/tools/qdoc/doc/images/links-to-broken-links.png b/src/tools/qdoc/doc/images/links-to-broken-links.png
deleted file mode 100644
index 775143bd4a..0000000000
--- a/src/tools/qdoc/doc/images/links-to-broken-links.png
+++ /dev/null
Binary files differ
diff --git a/src/tools/qdoc/doc/images/links-to-links.png b/src/tools/qdoc/doc/images/links-to-links.png
deleted file mode 100644
index 9d2cc2fae5..0000000000
--- a/src/tools/qdoc/doc/images/links-to-links.png
+++ /dev/null
Binary files differ
diff --git a/src/tools/qdoc/doc/images/qa-table.png b/src/tools/qdoc/doc/images/qa-table.png
deleted file mode 100644
index 5818739fac..0000000000
--- a/src/tools/qdoc/doc/images/qa-table.png
+++ /dev/null
Binary files differ
diff --git a/src/tools/qdoc/doc/images/qt-logo.png b/src/tools/qdoc/doc/images/qt-logo.png
deleted file mode 100644
index 6b72d5fb72..0000000000
--- a/src/tools/qdoc/doc/images/qt-logo.png
+++ /dev/null
Binary files differ
diff --git a/src/tools/qdoc/doc/images/training.jpg b/src/tools/qdoc/doc/images/training.jpg
deleted file mode 100644
index c2ce5c3b21..0000000000
--- a/src/tools/qdoc/doc/images/training.jpg
+++ /dev/null
Binary files differ
diff --git a/src/tools/qdoc/doc/qa-pages.qdoc b/src/tools/qdoc/doc/qa-pages.qdoc
deleted file mode 100644
index a96673901a..0000000000
--- a/src/tools/qdoc/doc/qa-pages.qdoc
+++ /dev/null
@@ -1,109 +0,0 @@
-/****************************************************************************
-**
-** Copyright (C) 2015 The Qt Company Ltd.
-** Contact: http://www.qt.io/licensing/
-**
-** This file is part of the documentation of the Qt Toolkit.
-**
-** $QT_BEGIN_LICENSE:FDL$
-** Commercial License Usage
-** Licensees holding valid commercial Qt licenses may use this file in
-** accordance with the commercial license agreement provided with the
-** Software or, alternatively, in accordance with the terms contained in
-** a written agreement between you and The Qt Company. For licensing terms
-** and conditions see http://www.qt.io/terms-conditions. For further
-** information use the contact form at http://www.qt.io/contact-us.
-**
-** GNU Free Documentation License Usage
-** Alternatively, this file may be used under the terms of the GNU Free
-** Documentation License version 1.3 as published by the Free Software
-** Foundation and appearing in the file included in the packaging of
-** this file. Please review the following information to ensure
-** the GNU Free Documentation License version 1.3 requirements
-** will be met: 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-guide/qdoc-guide.qdoc b/src/tools/qdoc/doc/qdoc-guide/qdoc-guide.qdoc
deleted file mode 100644
index af1fa1ba14..0000000000
--- a/src/tools/qdoc/doc/qdoc-guide/qdoc-guide.qdoc
+++ /dev/null
@@ -1,632 +0,0 @@
-/****************************************************************************
-**
-** Copyright (C) 2015 The Qt Company Ltd.
-** Contact: http://www.qt.io/licensing/
-**
-** This file is part of the documentation of the Qt Toolkit.
-**
-** $QT_BEGIN_LICENSE:FDL$
-** Commercial License Usage
-** Licensees holding valid commercial Qt licenses may use this file in
-** accordance with the commercial license agreement provided with the
-** Software or, alternatively, in accordance with the terms contained in
-** a written agreement between you and The Qt Company. For licensing terms
-** and conditions see http://www.qt.io/terms-conditions. For further
-** information use the contact form at http://www.qt.io/contact-us.
-**
-** GNU Free Documentation License Usage
-** Alternatively, this file may be used under the terms of the GNU Free
-** Documentation License version 1.3 as published by the Free Software
-** Foundation and appearing in the file included in the packaging of
-** this file. Please review the following information to ensure
-** the GNU Free Documentation License version 1.3 requirements
-** will be met: http://www.gnu.org/copyleft/fdl.html.
-** $QT_END_LICENSE$
-**
-****************************************************************************/
-/*!
- \page qdoc-guide.html
- \title Getting Started with QDoc
- \nextpage Creating QDoc Configuration Files
-
- Qt uses QDoc to generate its documentation set into HTML and DITA XML
- formats. QDoc uses a set of configuration files to generate documentation
- from QDoc comments. The comments have types called
- \l{writing-topic-commands}{topics} that determine whether a comment is a
- class documentation or a property documentation. A comment may also have
- \l{writing-markup}{mark up} to enhance the layout and formatting of the
- final output.
-
- There are three essential materials for generating documentation with qdoc:
- \list
- \li \c QDoc binary
- \li \c qdocconf configuration files
- \li \c Documentation in \c C++, \c QML, and \c .qdoc files
- \endlist
-
- This section intends to cover the basic necessities for creating a
- documentation set. Additionally, the guide presents special considerations
- and options to documenting non-C++ API documentation as well as QML
- documentation. Finally, the guide will provide a sample project
- documentation and an example of a QML type documentation.
-
- For specific QDoc information, consult the
- \l{QDoc Manual}.
- \section1 Chapters
-
- \list 1
- \li \l{Creating QDoc Configuration Files}
- \li \l{Writing Documentation}
- \li \l{Categories of Documentation}
- \list
- \li \l{C++ Documentation Style}
- \li \l{QML Documentation Style}
- \endlist
- \li \l{QML Documentation Example}
- \endlist
-
-*/
-
-/*!
- \page qdoc-guide-conf.html
- \title Creating QDoc Configuration Files
- \previouspage Getting Started with QDoc
- \nextpage Writing Documentation
- To generate documentation, QDoc uses configuration files, with the
- \c qdocconf extension, to store configuration settings.
-
- The \l{The QDoc Configuration File} article covers the various configuration
- variables in greater detail.
-
- \section1 QDoc Configuration Files
- QDoc's configuration settings can reside in a single \e qdocconf file, but
- can also be in other qdocconf files. The \c {include(<filepath>)} command
- allows configuration files to include other configuration files.
-
- QDoc has two outputs, HTML documentation and documentation in DITA XML
- format. The main distinction between the two outputs is that HTML
- documentation needs to have its HTML styling information in the
- configuration files. DITA XML documentation does not, and a separate process
- can style the documentation in DITA at a later time. DITA XML is therefore
- more flexible in allowing different styles to apply to the same information.
-
- To run qdoc, the project configuration file is supplied as an argument.
- \code
- qdoc project.qdocconf
- \endcode
-
- The project configuration contains information that qdoc uses to create the
- documentation.
-
- \section2 Project Information
-
- QDoc uses the \c project information to generate the documentation.
- \code
- project = QDoc Project
- description = Sample QDoc project
- \endcode
-
- \target qdoc-input-output-dir
- \section2 Input and Output Directories
-
- Specifying the path to the source directories allow QDoc to find sources and
- generate documentation.
-
- \badcode
- sourcedirs = <path to source code>
- exampledirs = <path to examples directory>
- imagedirs = <path to image directory>
-
- sources.fileextensions = "*.cpp *.qdoc *.mm *.qml"
- headers.fileextensions = "*.h *.ch *.h++ *.hh *.hpp *.hxx"
- examples.fileextensions = "*.cpp *.h *.js *.xq *.svg *.xml *.ui *.qhp *.qhcp *.qml"
- examples.imageextensions = "*.png *.jpeg *.jpg *.gif *.mng"
- \endcode
-
- QDoc will process headers and sources from the ones specified in the
- \c fileextensions variable.
-
- Likewise, QDoc needs the path to the output directory. The \c outputformats
- variable determines the type of documentation. These variables should be
- in separate configuration files to modularize the documentation build.
- \badcode
- outputdir = $SAMPLE_PROJECT/doc/html
- outputformats = HTML
- \endcode
-
- QDoc can resolve the paths relative to the qdocconf file as well as
- environment variables.
-
- \note During each QDoc run, the output directory is deleted.
- \section2 Extra Files
-
- QDoc will output generated documentation into the directory specified in
- the \l{Input and Output Directories}{output} directory. It is also possible
- to specify extra files that QDoc should export.
-
- \badcode
- HTML.extraimages = extraImage.png \
- extraImage2.png
- \endcode
-
- The \c extraImage.png and the \c extraImage2.png files will be copied to the
- HTML output directory.
-
- \section2 Qt Help Framework Configuration
-
- QDoc will also export a \e {Qt Help Project} file, in a \c qhp file.
- The qhp file is then used by the \c qhelpgenerator to package the
- documentation into a \c qch file. Qt Creator and Qt Assistant reads the qch
- file to display the documentation.
-
- The \l {Creating Help Project Files} article covers the configuration
- options.
-
- \section2 HTML Configuration
-
- QDoc has an HTML generator that will export a set of documentation into
- HTML files using various configuration settings. QDoc will place the
- generated documentation into the directory specified by the \c outputdir
- variable.
-
- \badcode
- outputformats = HTML
- outputdir = <path to output directory>
- \endcode
-
- QDoc needs to know where the styles and templates for generating HTML
- are located. Typically, the templates directory contains a \c scripts,
- \c images, and a \c style directory, containing scripts and CSS files.
-
- \badcode
- HTML.templatedir = <path to templates>
- \endcode
-
- The main configuration variables are:
- \badcode
- HTML.postheader
- HTML.postpostheader
- HTML.postheader
- HTML.footer
-
- HTML.headerstyles
- HTML.stylesheets = style.css \
- style1.css
-
- HTML.scripts = script.js
- \endcode
-
- The \c{HTML.headerstyles} variable inserts the style information into the
- HTML file and the \c{HTML.stylesheets} specifies which files QDoc should
- copy into the output directory. As well, QDoc will embed the string
- in the \c postheader, \c footer, and related variables into each HTML file.
-
- The \l {HTML Specific Configuration Variables} article outlines the usage
- of each variable.
-
- \section2 DITA XML Configuration
-
- DITA XML output is enabled using the \c outputformats variable. Unlike HTML
- documentation, QDoc does not need HTML style templates for generating
- documentation in DITA XML format.
-
- \badcode
- outputformats = DITAXML
- outputdir
- \endcode
-
- \section2 Qt Index Reference
- Documentation projects can link to Qt APIs and other articles by specifying
- the path to the \c qt.index file. When qdoc generates the Qt Reference
- Documentation, it will also generate an index file, containing the URLs to
- the articles. Other projects can use the links in the index file so that
- they can link to other articles and API documentation within Qt.
-
- \badcode
- indexes = $QT_INSTALL_DOCS/html/qt.index $OTHER_PROJECT/html/qt.index
- \endcode
- It is possible to specify multiple index files from several projects.
-
- \section1 Macros and Other Configurations
-
- Macros for substituting HTML characters exist and are helpful for generating
- specific HTML-valid characters.
-
- \badcode
- macro.pi.HTML = "&Pi;"
- \endcode
- The snippet code will replace any instances of \c{\\pi} with \c &Pi; in the
- HTML file, which will appear as the Greek \pi symbol when viewed in
- browsers.
-
- \section2 QML Additions
-
- QDoc is able to parse QML files for QDoc comments. QDoc will parse files
- with the QML extension, \c{.qml}, if the extension type is included in the
- \l{Input and Output Directories}{fileextensions} variable.
-
- Also, the generated HTML files can have a prefix and a suffix following the
- QML module name, specified in the QDoc configuration file.
- \badcode
- outputprefixes = QML
- outputprefixes.QML = uicomponents-
- outputsuffixes = QML
- outputsuffixes.QML = -tp
- \endcode
-
- \b {See also}: \l {outputprefixes-variable}{outputprefixes},
- \l {outputsuffixes-variable}{outputsuffixes}.
-
-*/
-
-/*!
- \page qdoc-guide-writing.html
- \title Writing Documentation
- \previouspage Creating QDoc Configuration Files
- \nextpage Categories of Documentation
-
- \section1 QDoc Comments
-
- Documentation is contained within qdoc \e comments, delimited by
- \beginqdoc and \endqdoc comments. Note that these are valid comments
- in C++, QML, and JavaScript.
-
- QDoc will parse C++ and QML files to look for qdoc comments. To explicitly
- omit a certain file type, omit it from the
- \l{Input and Output Directories}{configuration} file.
-
- \section1 QDoc Commands
-
- QDoc uses \e commands to retrieve information about the documentation. \c
- Topic commands determine the type of documentation element, the \c context
- commands provide hints and information about a topic, and \c markup commands
- provide information on how QDoc should format a piece of documentation.
-
- \target writing-topic-commands
- \section2 QDoc Topics
- Each qdoc comment must have a \e topic type. A topic distinguishes it from
- other topics. To specify a topic type, use one of the several
- \l{Topic Commands}{topic commands}.
-
- QDoc will collect similar topics and create a page for each one. For
- example, all the enumerations, properties, functions, and class description
- of a particular C++ class will reside in one page. A generic page is
- specified using the \l{page-command}{\\page} command and the filename is the
- argument.
-
- Example of topic commands:
- \list
- \li \l{enum-command}{\\enum} - for enumeration documentation
- \li \l{class-command}{\\class} - for C++ class documentation
- \li \l{qmltype-command}{\\qmltype} - for QML type documentation
- \li \l{page-command}{\\page} - for creating a page.
- \endlist
-
- The \l{page-command}{\\page} command is for creating articles that are not
- part of source documentation. The command can also accept two arguments: the
- file name of the article and the documentation type. The possible types are:
- \list
- \li \c howto
- \li \c overview
- \li \c tutorial
- \li \c faq
- \li \c article - \e default when there is no type
- \endlist
-
- \snippet examples/samples.qdocinc sample-faq
-
- The \l{Topic Commands} page has information on all of the available topic
- commands.
-
- \target writing-context
- \section2 Topic Contexts
-
- Context commands give QDoc a hint about the \e context of the topic. For
- example, if a C++ function is obsolete, then it should be marked obsolete
- with the \l{obsolete-command}{\\obsolete} command. Likewise,
- \l{nextpage-command}{page navigation} and \l{title-command}{page title} 
- give extra page information to QDoc.
-
- QDoc will create additional links or pages for these contexts. For example,
- a group is created using the \l{group-command}{\\group} command and the
- members have the \l{ingroup-command}{\\ingroup} command. The group name is
- supplied as an argument.
-
- The \l{Context Commands} page has a listing of all the available context
- commands.
-
- \target writing-markup
- \section2 Documentation Markup
-
- QDoc can do \e markup of text similar to other markup or
- documentation tools. QDoc can mark a section of text in \b{bold},
- when the text is marked up with the \l{b-command}{\\b} command.
-
- \code
- \b{This} text will be in \b{bold}.
- \endcode
-
- The \l{Markup Commands} page has a full listing of the available markup
- commands.
-
- \section1 Anatomy of Documentation
-
- Essentially, for QDoc to create a page, there must be some essential
- ingredients present.
-
- \list
- \li Assign a topic to a QDoc comment - A comment could be a page, a
- property documentation, a class documentation, or any of the available
- \l{Topic Commands}{topic commands}.
-
- \li Give the topic a context - QDoc can associate certain topics to other
- pages such as associating obsolete functions when the documentation is
- marked with \l{obsolete-command}{\\obsolete}.
-
- \li Mark sections of the document with
- \l{Markup Commands}{markup commands} - QDoc can create layouts and
- format the documentation for the documentation.
- \endlist
-
- In Qt, the \l{QVector3D} class was documented with the following QDoc
- comment:
- \snippet examples/samples.qdocinc qvector3d-class
-
- It has a constructor, \l{QVector3D::QVector3D()}, which was documented with
- the following QDoc comment:
- \snippet examples/samples.qdocinc qvector3d-function
-
- The different comments may reside in different files and QDoc will collect
- them depending on their topic and their context. The resulting documentation
- from the snippets are generated into the \l{QVector3D} class documentation.
-
- Note that if the documentation immediately precedes the function or class
- in the source code, then it does not need to have a topic. QDoc will assume
- that the documentation above the code is the documentation for that code.
-
- An article is created using \l{page-command}{\\page} command. The first
- argument is the HTML file that QDoc will create. The topic is supplemented
- with context commands, the \l{title-command}{\\title} and
- \l{nextpage-command}{\\nextpage} commands. There are several other
- QDoc commands such as the \l{list-command}{\\list} command.
- \snippet examples/samples.qdocinc sample-page
-
- The section on \l{QDoc Topics}{topic commands} gives an overview on several
- other topic types.
-
-
-*/
-
-/*!
- \page qdoc-categories.html
- \title Categories of Documentation
- \previouspage Writing Documentation
- \nextpage QML Documentation Example
- \brief Describes the different types such as How-To's, Tutorials, Overviews,
- Examples, and Class Documentation.
-
- There are several types of predefined documentation \e categories or
- \e types:
- \list
- \li How-To's
- \li Tutorial
- \li Overview
- \li Article
- \li FAQ (Frequently Asked Questions)
- \li C++ API Documentation
- \li QML Type Documentation
- \li Code Example
- \endlist
-
- QDoc has the ability to format a page depending on the type. Further,
- stylesheets can provide additional control on the display of each category.
-
- \section1 API Documentation
- QDoc excels in the creation of API documentation given a set of source code
- and documentation in QDoc comments. Specifically, QDoc is aware of Qt's
- architecture and can validate the existence of Qt C++ class, function, or
- property documentation. QDoc gives warnings and errors if it cannot
- associate a documentation with a code entity or if a code entity does not
- have documentation.
-
- In general, every Qt code entity such as properties, classes, methods,
- signals, and enumerations have a corresponding
- \l{qdoc-topics}{topic command}. QDoc will associate the documentation to the
- source using C++ naming rules.
-
- QDoc will parse the header files (typically \c .h files) to build a tree of
- the class structures. Then QDoc will parse the source files and
- documentation files to attach documentation to the class structure.
- Afterwards, QDoc will generate a page for the class.
-
- \note QDoc uses the header files to inform itself about the class and will
- not properly process QDoc comments in header files.
-
- \section2 Language Styles
-
- To produce quality API documentation, the Qt API references follow a
- particular language guidelines. While the contents of this page demonstrates
- how to create API documentation, the style guidelines demonstrate how
- the reference materials follow a consistent use of language.
-
- \list
- \li \l{C++ Documentation Style}
- \li \l{QML Documentation Style}
- \endlist
-
- \keyword qml-documentation
- \section2 Documenting QML Types
-
- In the world of \l{Qt Quick}{QML}, there are additional entities we need to
- document such as QML signals, attached properties, and QML methods.
- Internally, they use Qt technologies, however, QML API documentation
- requires different layout and naming conventions from the Qt C++ API
- documentation.
-
- A list of QML related QDoc commands:
- \list
- \li \l{qmlattachedproperty-command}{\\qmlattachedproperty}
- \li \l{qmlattachedsignal-command}{\\qmlattachedsignal}
- \li \l{qmlbasictype-command}{\\qmlbasictype}
- \li \l{qmltype-command}{\\qmltype} - creates a QML type documentation
- \li \l{qmlmethod-command}{\\qmlmethod}
- \li \l{qmlproperty-command}{\\qmlproperty}
- \li \l{qmlsignal-command}{\\qmlsignal}
- \li \l{inherits-command}{\\inherits}
- \li \l{qmlmodule-command}{\\qmlmodule}
- \li \l{inqmlmodule-command}{\\inqmlmodule}
- \li \l{instantiates-command}{\\instantiates}
-
- \endlist
-
- \note Remember to enable QML parsing by including the \c{*.qml} filetype in
- the \l{qdoc-input-output-dir}{fileextension} variable.
-
- To document a QML type, start by creating a QDoc comment that uses the
- \l{qmltype-command} {\\qmltype} command as its topic command.
-
- \section3 QML Parser
-
- If your QML type is defined in a \e qml file, document it there.
- If your QML type is represented by a C++ class, document it in the
- \e cpp file for that C++ class and include an
- \l{instantiates-command}{\\instantiates} command to specify the
- name of the C++ class. Don't document a QML type in a \e{cpp} file
- if the QML type is defined in a \e{qml} file.
-
- When documenting a QML type in a \e{qml} file, place each QDoc
- comment directly above the entity to which the comment applies.
- For example, place the QDoc comment containing the \e{\\qmltype}
- command (the topic comment) directly above the outer QML type in
- the \e{qml} file. Place the comment for documenting a QML property
- directly above the property declaration, and so on for QML signal
- handlers and QML methods. Note that when documenting QML
- properties in a \e{qml} file, you don't normally include the
- \e{\\qmlproperty} command as a topic command (which you must do
- when documenting QML types in \e{cpp} files), because the QML
- parser automatically associates each QDoc comment with the next
- QML declaration it parses. The same is true for QML signal handler
- and QML method comments. But it is sometimes useful to include one
- or more \e{\\qmlproperty} commands in the comment, e.g. when the
- property type is another QML type and you want the user to only
- use certain properties within that other QML type, but not all of
- them. But when documenting a property that has an alias, place the
- QDoc comment for it directly above the alias declaration. In these
- cases, the QDoc comment \e must contain a \e{\\qmlproperty}
- command, because that is the only way QDoc can know the type of
- the aliased property.
-
- When documenting a QML type in the \e cpp file of its
- corresponding C++ class (if it has one), you normally place each
- QDoc comment directly above the entity it documents. However, QDoc
- does not use the QML parser to parse these files (the C++ parser
- is used), so these QML QDoc comments can appear anywhere in the
- \e{cpp} file. Note that QML QDoc comments in \e cpp files \e must
- use the QML topic commands. i.e., the \l{qmltype-command}
- {\\qmltype} command \e must appear in the QDoc comment for the
- QML type, and a \l{qmlproperty-command} {\\qmlproperty} command \e
- must appear in each QML property QDoc comment.
-
- \section3 QML Modules
-
- A QML type belongs to a \e module. The module
- may include all the related types for a platform or contain a certain
- version of \l{Qt Quick}. For example, the Qt Quick 2 QML types belong
- to the Qt Quick 2 module while there is also a Qt Quick 1 module for the older
- types introduced in Qt 4.
-
- QML modules allow grouping QML types. The \l{qmltype-command}
- {\\qmltype} topic command must have an \l{inqmlmodule-command}
- {\\inqmlmodule} context command to relate the type to a QML
- module. Similarly, a \l{qmlmodule-command}{\\qmlmodule} topic
- command must exist in a separate \c{.qdoc} file to create the
- overview page for the module. The overview page will list the
- QML types of the QML module.
-
- The links to the QML types must therefore also contain the module name.
- For example, if a type called \c TabWidget is in the \c UIComponents
- module, it must be linked as \c {UIComponents::TabWidget}.
-
- The \l{componentset}{UIComponents} example demonstrates proper usage of
- QDoc commands to document QML types and QML modules.
-
- \section3 Read-only and Internal QML Properties
-
- QDoc detects QML properties that are marked as \c readonly. Note that the
- property must be initialized with a value.
-
- \code
- readonly property int sampleReadOnlyProperty: 0
- \endcode
- For example, the example \l{TabWidget} type has a fictitious read-only
- property \c sampleReadOnlyProperty. Its declaration has the \c readonly
- identifier and it has an initial value.
-
- Properties and signals that are not meant for the public interface may
- be marked with the \l{internal-command}{\\internal} command. QDoc will not
- publish the documentation in the generated outputs.
-
- \section1 Articles & Overviews
- Articles and overviews are a style of writing best used for providing
- summary detail on a topic or concept. It may introduce a technology or
- discuss how a concept may be applied, but without discussing exact steps
- in too much detail. However, this type of content could provide the entry
- point for readers to find instructional and reference materials that do,
- such as tutorials, examples and class documentation. An example of an
- overview might be a product page, such as a top level discussion of
- Qt Quick, individual modules, design principles, or tools.
-
- To signify that a document is an article, you append the article keyword
- to the \\page command:
-
- \snippet examples/samples.qdocinc sample-overview
-
- The \l{writing-topic-commands}{writing topic commands} section has a listing
- of the available \\page command arguments.
-
- \section1 Tutorials, How-To's, FAQ's
-
- Tutorials, How-To's, and FAQ's are all instructional material, in that they
- instruct or prescribe to the reader. Tutorials are content designed to guide
- the reader along a progressive learning path for a concept or technology.
- How-To's and FAQ's (\e{Frequently Asked Questions}) provide guidance by
- presenting material in the form of answers to commonly asked topics.
- How-To's and FAQ's are designed for easy reference and are not necessarily
- presented in a linear progression.
-
- To create these types, mark the pages by providing a \c type argument to the
- \l{page-command}{\\page} command. The \c type argument is the second
- argument, with the file name being the first.
- \snippet examples/samples.qdocinc sample-faq
-
- The \l{writing-topic-commands}{writing topic commands} section has a listing
- of the available \\page command arguments.
-
- \section1 Code Examples
- Examples are an effective way to demonstrate practical usage of a given
- technology or concept. When it comes to middleware this is usually in the
- form of an application using simple code and clear explanations of what the
- code is doing. Any module, API, project, pattern etc. should have at least
- one good example.
-
- An example may have an accompanying tutorial. The tutorial instructs and
- describes the code, while the code example is the code content that users
- may study. Code examples may have accompanying text that are not in the
- tutorial.
-
- QDoc will create a page containing the example code with a description
- using the \l{example-command}{\\example} command.
-
- \snippet examples/samples.qdocinc sample-example
-
- QDoc will use the directory specified in the input
- \l{Input and Output Directories}{exampledirs} variable to find the Qt
- Project (\c .pro) file to generate the example files. The generated HTML
- will have the filename, \c {declarative-ui-components-tabwidget.html}. QDoc
- will also list all of the example code.
-
- \note The example's project file must be the same as the
- directory name.
-*/
-
-
diff --git a/src/tools/qdoc/doc/qdoc-guide/qtwritingstyle-cpp.qdoc b/src/tools/qdoc/doc/qdoc-guide/qtwritingstyle-cpp.qdoc
deleted file mode 100644
index 8cbf74cd67..0000000000
--- a/src/tools/qdoc/doc/qdoc-guide/qtwritingstyle-cpp.qdoc
+++ /dev/null
@@ -1,187 +0,0 @@
-/****************************************************************************
-**
-** Copyright (C) 2015 The Qt Company Ltd.
-** Contact: http://www.qt.io/licensing/
-**
-** This file is part of the documentation of the Qt Toolkit.
-**
-** $QT_BEGIN_LICENSE:FDL$
-** Commercial License Usage
-** Licensees holding valid commercial Qt licenses may use this file in
-** accordance with the commercial license agreement provided with the
-** Software or, alternatively, in accordance with the terms contained in
-** a written agreement between you and The Qt Company. For licensing terms
-** and conditions see http://www.qt.io/terms-conditions. For further
-** information use the contact form at http://www.qt.io/contact-us.
-**
-** GNU Free Documentation License Usage
-** Alternatively, this file may be used under the terms of the GNU Free
-** Documentation License version 1.3 as published by the Free Software
-** Foundation and appearing in the file included in the packaging of
-** this file. Please review the following information to ensure
-** the GNU Free Documentation License version 1.3 requirements
-** will be met: http://www.gnu.org/copyleft/fdl.html.
-** $QT_END_LICENSE$
-**
-****************************************************************************/
-
-/*!
-\page qtwritingstyle-cpp.html
-\title C++ Documentation Style
-\brief Style guidelines for C++ documentation
-
-To generate the documentation, QDoc goes through the source code and generates
-documentation for C++ types such as classes. QDoc then associates member
-functions, properties, and other types to the appropriate class.
-
-Note that the documentation must be in the implementation files such as \c .cpp.
-
-\section1 Class Documentation
-
-Class documentation is generated using the \l{class-command}{\\class} command and
-the name of the class as the first argument.
-
-\snippet examples/cpp.qdoc.sample class
-
-\l{Context commands} add information about the class, such as its module or
-which version the class was added.
-
-Some common context commands are:
-\list
-\li \l{brief-command}{\\brief} - the class' brief description \b (mandatory)
-\li \l{since-command}{\\since} - the version to which the class was added \b (mandatory)
-\li \l{internal-command}{\\internal} - marks the class as internal. Internal
-classes do not appear in the public API documentation.
-\endlist
-
-
-\section2 The Brief and Detailed Description
-
-The \e{brief description} is marked with the \l{brief-command}{\\brief} command
-and it is for summarizing the purpose or functionality of the class. For C++
-classes, QDoc will take the class and create annotated information for the
-class. The annotated information appears in lists and tables which display the
-class.
-
-The C++ brief should start with:
-\code
-"The <C++ class name> class"
-\endcode
-
-The \e{detailed description} section starts after the brief description. It
-provides more information about the class. The detailed description may contain
-images, snippet code, or links to other relevant documents. There
-must be an empty line which separates the brief and detailed description.
-
-\section1 Member Functions
-
-Typically, function documentation immediately precedes the implementation of the
-function in the \c .cpp file. For function documentation that is not immediately
-above the implementation, the \l{fn-command}{\\fn} is needed.
-
-\snippet examples/cpp.qdoc.sample function
-
-The function documentation starts with a verb, indicating the operation the
-function performs. This also applies to constructors and destructors.
-
-Some common verbs for function documentation:
-\list
-\li "Constructs..." - for constructors
-\li "Destroys..." - for destructors
-\li "Returns..." - for accessor functions
-\endlist
-
-The function documentation must document:
-\list
-\li the return type
-\li the parameters
-\li the actions of the functions
-\endlist
-
-The \l{a-command}{\\a} command marks the parameter in the documentation.
-The return type documentation should link to the type documentation or be
-marked with the \l{c-command}{\\c} command in the case of boolean values.
-
-\snippet examples/cpp.qdoc.sample return
-
-\section1 Properties
-
-The property documentation resides immediately above the read function's
-implementation. The \l{writing-topic-commands}{topic command} for properties is
-\l{property-command}{\\property}.
-
-\snippet examples/cpp.qdoc.sample property
-
-Property documentation usually starts with "This property...", but these are
-alternate expressions:
-\list
-\li "This property holds..."
-\li "This property describes..."
-\li "This property represents..."
-\li "Returns \c true when... and \c false when..." - for properties that
-are read.
-\li "Sets the..." - for properties that configure a type.
-\endlist
-
-Property documentation must include:
-\list
-\li description and behavior of the property
-\li accepted values for the property
-\li the default value of the property
-\endlist
-Similar to \l{Member Functions}{functions}, the default type may be linked
-or marked with the \c{\c} command.
-
-An example of a value range style is:
-\quotation
-The values range from 0.0 (no blur) to maximumRadius (maximum blur). By default, the property is set to 0.0 (no blur).
-\endquotation
-
-\section1 Signals, Notifiers, and Slots
-The \l{writing-topic-commands}{topic command} for signals, notifiers, and slots
-is \l{fn-command}{\\fn}. Signal documentation state when they are triggered
-or emitted.
-
-\snippet examples/cpp.qdoc.sample signals
-
-Signal documentation typically begin with "This signal is triggered when...".
-Here are alternate styles:
-\list
-\li "This signal is triggered when..."
-\li "Triggered when..."
-\li "Emitted when..."
-\endlist
-
-For slots or notifiers, the condition when they are executed or triggered by
-a signal should be documented.
-\list
-\li "Executed when..."
-\li "This slot is executed when..."
-\endlist
-
-For properties that have overloaded signals, QDoc groups the overloaded
-notifiers together. To refer to a specific version of a notifier or signal,
-simply refer to the property and mention that there are different versions of
-the notifier.
-
-\snippet examples/cpp.qdoc.sample overloaded notifier
-
-\section1 Enums, Namespaces, and Other Types
-
-Enums, namespaces, and macros have a \l{writing-topic-commands}{topic command} for their documentation:
-\list
-\li \l{enum-command}{\\enum}
-\li \l{typedef-command}{\\typedef}
-\li \l{macro-command}{\\macro}
-\endlist
-
-The language style for these types mention that they are an enum or a macro and
-continues with the type description.
-
-For enumerations, the \l{value-command}{\\value} command is for listing the
-values. QDoc creates a table of values for the enum.
-
-\snippet examples/cpp.qdoc.sample enums
-
-*/
-
diff --git a/src/tools/qdoc/doc/qdoc-guide/qtwritingstyle-qml.qdoc b/src/tools/qdoc/doc/qdoc-guide/qtwritingstyle-qml.qdoc
deleted file mode 100644
index 6955a042c2..0000000000
--- a/src/tools/qdoc/doc/qdoc-guide/qtwritingstyle-qml.qdoc
+++ /dev/null
@@ -1,164 +0,0 @@
-/****************************************************************************
-**
-** Copyright (C) 2015 The Qt Company Ltd.
-** Contact: http://www.qt.io/licensing/
-**
-** This file is part of the documentation of the Qt Toolkit.
-**
-** $QT_BEGIN_LICENSE:FDL$
-** Commercial License Usage
-** Licensees holding valid commercial Qt licenses may use this file in
-** accordance with the commercial license agreement provided with the
-** Software or, alternatively, in accordance with the terms contained in
-** a written agreement between you and The Qt Company. For licensing terms
-** and conditions see http://www.qt.io/terms-conditions. For further
-** information use the contact form at http://www.qt.io/contact-us.
-**
-** GNU Free Documentation License Usage
-** Alternatively, this file may be used under the terms of the GNU Free
-** Documentation License version 1.3 as published by the Free Software
-** Foundation and appearing in the file included in the packaging of
-** this file. Please review the following information to ensure
-** the GNU Free Documentation License version 1.3 requirements
-** will be met: http://www.gnu.org/copyleft/fdl.html.
-** $QT_END_LICENSE$
-**
-****************************************************************************/
-
-/*!
-\page qtwritingstyle-qml.html
-\title QML Documentation Style
-\brief Style guidelines for QML documentation
-
-QDoc can process QML types defined as C++ classes and QML types defined in
-\c .qml files. For C++ classes documented as QML types, the QDoc comments are
-in the \c .cpp file while QML types defined in QML are in the \c .qml
-file. The C++ classes must also be documented
-documented with the QML \l{topic-commands}{topic commands}:
-
-\list
-\li \l{qmlattachedproperty-command}{\\qmlattachedproperty}
-\li \l{qmlattachedsignal-command}{\\qmlattachedsignal}
-\li \l{qmlbasictype-command}{\\qmlbasictype}
-\li \l{qmltype-command}{\\qmltype}
-\li \l{qmlmethod-command}{\\qmlmethod}
-\li \l{qmlproperty-command}{\\qmlproperty}
-\li \l{qmlsignal-command}{\\qmlsignal}
-\li \l{qmlmodule-command}{\\qmlmodule}
-\li \l{inqmlmodule-command}{\\inqmlmodule}
-\li \l{instantiates-command}{\\instantiates}
-\endlist
-
-For QML types defined in \c .qml files, QDoc will parse the QML and determine
-the properties, signals, and the type within the QML definition. The QDoc
-block then needs to be immediately above the declaration. For QML types
-implemented in C++, QDoc will output warnings if the C++ class documentation
-does not exist. The class documentation may be marked as
-\l{internal-command}{internal} if it is not a public API.
-
-\section1 QML Types
-
-The \l{qmltype-command}{\\qmltype} command is for QML type documentation.
-
-\snippet examples/qml.qdoc.sample qmltype
-
-The \l{instantiates-command}{\\instantiates} accepts the C++ class which
-implements the QML type as the argument. For types implemented in QML, this
-is not needed.
-
-The \e{brief description} provides a summary for the QML type. The brief does
-not need to be a complete sentence and may start with a verb. QDoc will append
-the brief description onto the QML type in tables and generated lists.
-
-\code
-\qmltype ColorAnimation
-\brief Animates changes in color values
-\endcode
-
-Here are some alternate verbs for the brief statement:
-\list
-\li "Provides..."
-\li "Specifies..."
-\li "Describes..."
-\endlist
-
-The \e{detailed description} follows the brief and may contain images, snippet,
-and link to other documentation.
-
-\section1 Properties
-
-The property description focuses on what the property \e does and may use the
-following style:
-
-Property documentation usually starts with "This property..." but for certain
-properties, these are the common expressions:
-\list
-\li "This property holds..."
-\li "This property describes..."
-\li "This property represents..."
-\li "Returns \c true when... and \c false when..." - for properties that
-are marked \c{read-only}.
-\li "Sets the..." - for properties that configure a type.
-\endlist
-
-\section1 Signals and Handlers Documentation
-
-QML signals are documented either in the QML file or in the C++ implementation
-with the \l{qmlsignal-command}{\\qmlsignal} command. Signal documentation
-must include the condition for emitting the signal, mention the corresponding
-signal handler, and document whether the signal accepts a parameter.
-
-\snippet examples/qml.qdoc.sample signals
-
-These are the possible documentation styles for signals:
-\list
-\li "This signal is triggered when..."
-\li "Triggered when..."
-\li "Emitted when..."
-\endlist
-
-\section1 Methods and JavaScript Functions
-
-Typically, function documentation immediately precedes the implementation of the
-function in the \c .cpp file. The \l{topic-commands}{topic command} for
-functions is \l{fn-command}{\\fn}. For functions in QML or JavaScript, the
-documentation must reside immediately above the function declaration.
-
-The function documentation starts with a verb, indicating the operation the
-function performs.
-
-\snippet examples/qml.qdoc.sample function
-
-Some common verbs for function documentation:
-\list
-\li "Copies..." - for constructors
-\li "Destroys..." - for destructors
-\li "Returns..." - for accessor functions
-\endlist
-
-The function documentation must document:
-\list
-\li the return type
-\li the parameters
-\li the actions of the functions
-\endlist
-
-The \l{a-command}{\\a} command marks the parameter in the documentation.
-The return type documentation should link to the type documentation or be
-marked with the \l{c-command}{\\c} command in the case of boolean values.
-
-\section1 Enumerations
-
-QML enumerations are documented as QML properties with the
-\l{qmlproperty-command}{\\qmlproperty} command. The type of the property
-is \c enumeration.
-
-\snippet examples/qml.qdoc.sample enums
-
-The QDoc comment lists the values of the enumeration. If the enumeration is
-implemented in C++, the documentation may link to the corresponding C++
-enumeration. However, the QDoc comment should advise that the enumeration
-is a C++ enumeration.
-
-*/
-
diff --git a/src/tools/qdoc/doc/qdoc-manual-DITA.qdoc b/src/tools/qdoc/doc/qdoc-manual-DITA.qdoc
deleted file mode 100644
index 72882c8eb1..0000000000
--- a/src/tools/qdoc/doc/qdoc-manual-DITA.qdoc
+++ /dev/null
@@ -1,164 +0,0 @@
-/****************************************************************************
-**
-** Copyright (C) 2015 The Qt Company Ltd.
-** Contact: http://www.qt.io/licensing/
-**
-** This file is part of the documentation of the Qt Toolkit.
-**
-** $QT_BEGIN_LICENSE:FDL$
-** Commercial License Usage
-** Licensees holding valid commercial Qt licenses may use this file in
-** accordance with the commercial license agreement provided with the
-** Software or, alternatively, in accordance with the terms contained in
-** a written agreement between you and The Qt Company. For licensing terms
-** and conditions see http://www.qt.io/terms-conditions. For further
-** information use the contact form at http://www.qt.io/contact-us.
-**
-** GNU Free Documentation License Usage
-** Alternatively, this file may be used under the terms of the GNU Free
-** Documentation License version 1.3 as published by the Free Software
-** Foundation and appearing in the file included in the packaging of
-** this file. Please review the following information to ensure
-** the GNU Free Documentation License version 1.3 requirements
-** will be met: http://www.gnu.org/copyleft/fdl.html.
-** $QT_END_LICENSE$
-**
-****************************************************************************/
-
-/*!
- \page 21-0-qdoc-creating-dita-maps.html
- \previouspage Miscellaneous
- \contentspage QDoc Manual
- \nextpage The QDoc Configuration File
-
- \title Creating DITA Maps
-
- You can create DITA map files using three new qdoc commands, the \l{ditamap-command}
- {ditamap} command, the \l{topicref-command} {topicref} command, and the \l{mapref-command}
- {mapref} command. How these DITA maps will be used automatically or manually by the
- documentation build process is still under consideration. This section will be updated
- as the decisions are made.
-
- \section1 What is a DITA Map?
-
- A complete description of DITA can be found at the
- \l{http://www.oasis-open.org/committees/tc_home.php?wg_abbrev=dita}
- {OASIS Darwin Information Typing Architecture} site.
-
- An explanation of the DITA map is found at that site
- \l{http://docs.oasis-open.org/dita/v1.2/os/spec/langref/map.html}{here}.
-
- \target ditamap-command
- \section1 \\ditamap
-
- The \\ditamap command is for creating a DITA map using qdoc commands.
- The \\ditamap command is a kind of \\page command that produces a
- \e{.ditamap} instead of a \e{.html} or \e{.xml} file. The file that
- is created actually contains XML text, but the \e{.ditamap} suffix is
- used to identify the file as containing a DITA MAP.
-
- The argument is the name of the file to be created. In the following
- example, the file \e{creator.ditamap} is output:
- \code
- \ditamap creator.ditamap
- \endcode
-
- \target topicref-command
- \section1 \\topicref \\endtopicref
-
- The \\topicref \\endtopicref commands are for creating a topicref
- in the ditamap. The \\endtopicref command is required because
- \\topicref commands can be nested.
-
- \\topicref has two arguments. The first argument becomes the value
- of the \e navtitle attribute. Normally, you use the title of the
- topic being referenced. This title is often what will appear in a
- table of contents constructed from the ditamap.
-
- The second argument is the name of the page being referenced. The
- second argument is actually optional, for example if you are using
- a topicref as a container for other topicrefs and maprefs. It is
- also optional if you want qdoc to find the page name for you by
- looking up the title in its internal data structure. It is recommended
- that you provide the second parameter if you know the page name.
-
- \code
- \topicref {QML Module QtQuick 2} {qtquick-2.xml}
- \mapref {Creator Manual} {creator-manual.ditamap} \endmapref
- \topicref {QML Mouse Events} {qtquick2-mouseevents.xml} \endtopicref
- \topicref {Property Binding} {qtquick2-propertybinding.xml} \endtopicref
- \endtopicref
- \endcode
-
- \target mapref-command
- \section1 \\mapref
-
- The \\mapref command is for creating a mapref in the ditamap. A
- mapref refers to another ditamap, which you want to include in
- your ditamap. Like the \\topicref command, the \\mapref command
- has two arguments, but for the \\mapref command, both arguments
- are required. The arguments are essentially the same as described
- for \\topicref, but for \\mapref, the second command must be the
- name of another ditamap, i.e. it must have the \e{.ditamap}
- suffix. You must provide the file name. qdoc can't look up the
- file name for you.
-
- \code
- \mapref {Creator Manual} {creator-manual.ditamap} \endmapref
- \endcode
-
- \section1 An Example Ditamap Page
-
- The following example uses the three qdoc ditamap commands described above.
-
- \code
- \ditamap creator.ditamap
- \title The DITA Map for Creator
-
- \topicref {QML Module QtQuick 1}
- \topicref {QML Mouse Events} \endtopicref
- \topicref {Property Binding} \endtopicref
- \endtopicref
-
- \topicref {QML Module QtQuick 2} {qtquick-2.xml}
- \mapref {Creator Manual} {creator-manual.ditamap} \endmapref
- \topicref {QML Mouse Events} {qtquick2-mouseevents.xml} \endtopicref
- \topicref {Property Binding} {qtquick2-propertybinding.xml} \endtopicref
- \endtopicref
-
- \topicref {QML Module QtQuick.Particles 2} {qtquick-particles-2.xml}
- \topicref {Age} {qml-qtquick-particles2-age.xml} \endtopicref
- \endtopicref
- \endcode
-
- \section1 The Resulting Ditamap File
-
- This is the \e{.ditamap} file you get when you input the qdoc
- ditamap page shown above. Note that you can write ditamap files
- directly in XML just as easily as you can write them using the
- qdoc commands. The choice is yours.
-
- \code
- <?xml version="1.0" encoding="UTF-8"?>
- <!DOCTYPE map PUBLIC "-//OASIS//DTD DITA Map//EN" "map.dtd">
- <map>
- <topicmeta>
- <shortdesc>The DITA Map for Creator</shortdesc>
- </topicmeta>
- <topicref navtitle="QML Module QtQuick 1" href="qtquick-1.xml">
- <topicref navtitle="QML Mouse Events" href="qtquick2-mouseevents.xml"/>
- <topicref navtitle="Property Binding" href="qtquick2-propertybinding.xml"/>
- </topicref>
- <topicref navtitle="QML Module QtQuick 2" href="qtquick-2.xml">
- <mapref navtitle="Creator Manual" href="creator-manual.ditamap"/>
- <topicref navtitle="QML Mouse Events" href="qtquick2-mouseevents.xml"/>
- <topicref navtitle="Property Binding" href="qtquick2-propertybinding.xml"/>
- </topicref>
- <topicref navtitle="QML Module QtQuick.Particles 2" href="qtquick-particles-2.xml">
- <topicref navtitle="Age" href="qml-qtquick-particles2-age.xml"/>
- </topicref>
- </map>
- \endcode
-
-*/
-
diff --git a/src/tools/qdoc/doc/qdoc-manual-cmdindex.qdoc b/src/tools/qdoc/doc/qdoc-manual-cmdindex.qdoc
deleted file mode 100644
index d3f188c265..0000000000
--- a/src/tools/qdoc/doc/qdoc-manual-cmdindex.qdoc
+++ /dev/null
@@ -1,156 +0,0 @@
-/****************************************************************************
-**
-** Copyright (C) 2015 The Qt Company Ltd.
-** Contact: http://www.qt.io/licensing/
-**
-** This file is part of the documentation of the Qt Toolkit.
-**
-** $QT_BEGIN_LICENSE:FDL$
-** Commercial License Usage
-** Licensees holding valid commercial Qt licenses may use this file in
-** accordance with the commercial license agreement provided with the
-** Software or, alternatively, in accordance with the terms contained in
-** a written agreement between you and The Qt Company. For licensing terms
-** and conditions see http://www.qt.io/terms-conditions. For further
-** information use the contact form at http://www.qt.io/contact-us.
-**
-** GNU Free Documentation License Usage
-** Alternatively, this file may be used under the terms of the GNU Free
-** Documentation License version 1.3 as published by the Free Software
-** Foundation and appearing in the file included in the packaging of
-** this file. Please review the following information to ensure
-** the GNU Free Documentation License version 1.3 requirements
-** will be met: http://www.gnu.org/copyleft/fdl.html.
-** $QT_END_LICENSE$
-**
-****************************************************************************/
-
-/*!
- \page 27-qdoc-commands-alphabetical.html
- \previouspage Introduction to QDoc
- \contentspage QDoc Manual
- \nextpage Topic Commands
-
- \title Command Index
-
- This is a complete, alphabetized list of the QDoc commands.
-
- \list
-
- \li \l {a-command} {\\a}
- \li \l {abstract-command} {\\abstract}
- \li \l {annotatedlist-command} {\\annotatedlist}
- \li \l {b-command} {\\b}
- \li \l {b-command} {\\bold} \span {class="newStuff"} {(deprecated, use \\b)}
- \li \l {brief-command} {\\brief}
- \li \l {c-command} {\\c}
- \li \l {caption-command} {\\caption}
- \li \l {chapter-command} {\\chapter}
- \li \l {class-command} {\\class}
- \li \l {code-command} {\\code}
- \li \l {codeline-command} {\\codeline},
- \li \l {compat-command} {\\compat}
- \li \l {contentspage-command} {\\contentspage}
- \li \l {default-command} {\\default}
- \li \l {div-command} {\\div}
- \li \l {dots-command} {\\dots}
- \li \l {e-command} {\\e}
- \li \l {else-command} {\\else}
- \li \l {endif-command} {\\endif}
- \li \l {enum-command} {\\enum}
- \li \l {example-command} {\\example}
- \li \l {externalpage-command} {\\externalpage}
- \li \l {fn-command} {\\fn}
- \li \l {footnote-command} {\\footnote}
- \li \l {generatelist-command} {\\generatelist}
- \li \l {group-command} {\\group}
- \li \l {header-command} {\\header}
- \li \l {headerfile-command} {\\headerfile}
- \li \l {e-command} {\\i} \span {class="newStuff"} {(deprecated, use \\e)}
- \li \l {if-command} {\\if}
- \li \l {image-command} {\\image}
- \li \l {include-command} {\\include}
- \li \l {indexpage-command} {\\indexpage}
- \li \l {ingroup-command} {\\ingroup}
- \li \l {inherits-command}{\\inherits}
- \li \l {inlineimage-command} {\\inlineimage}
- \li \l {inmodule-command} {\\inmodule}
- \li \l {inqmlmodule-command} {\\inqmlmodule}
- \li \l {instantiates-command} {\\instantiates}
- \li \l {internal-command} {\\internal}
- \li \l {keyword-command} {\\keyword}
- \li \l {l-command} {\\l}
- \li \l {legalese-command} {\\legalese}
- \li \l {li-command} {\\li}
- \li \l {list-command} {\\list}
- \li \l {macro-command} {\\macro}
- \li \l {meta-command} {\\meta}
- \li \l {module-command} {\\module}
- \li \l {namespace-command} {\\namespace}
- \li \l {nextpage-command} {\\nextpage}
- \li \l {newcode-command} {\\newcode}
- \li \l {noautolist-command} {\\noautolist}
- \li \l {nonreentrant-command} {\\nonreentrant}
- \li \l {note-command} {\\note}
- \li \l {li-command} {\\o} \span {class="newStuff"} {(deprecated, use \\li)}
-
- \li \l {obsolete-command} {\\obsolete}
- \li \l {oldcode-command} {\\oldcode}
- \li \l {omit-command} {\\omit}
- \li \l {omitvalue-command} {\\omitvalue}
- \li \l {overload-command} {\\overload}
- \li \l {page-command} {\\page}
- \li \l {part-command} {\\part}
- \li \l {preliminary-command} {\\preliminary}
- \li \l {previouspage-command} {\\previouspage}
- \li \l {printline-command} {\\printline}
- \li \l {printto-command} {\\printto}
- \li \l {printuntil-command} {\\printuntil}
- \li \l {property-command} {\\property}
- \li \l {qmlabstract-command} {\\qmlabstract}
- \li \l {qmlattachedproperty-command} {\\qmlattachedproperty}
- \li \l {qmlattachedsignal-command} {\\qmlattachedsignal}
- \li \l {qmlbasictype-command} {\\qmlbasictype}
- \li \l {qmlclass-command} {\\qmlclass} \span {class="newStuff"} {(deprecated, use \\qmltype)}
- \li \l {qmltype-command} {\\qmltype}
- \li \l {qmlmethod-command} {\\qmlmethod}
- \li \l {qmlproperty-command} {\\qmlproperty}
- \li \l {qmlsignal-command} {\\qmlsignal}
- \li \l {qmlmodule-command} {\\qmlmodule}
- \li \l {quotation-command} {\\quotation}
- \li \l {quotefile-command} {\\quotefile}
- \li \l {quotefromfile-command} {\\quotefromfile}
- \li \l {raw-command} {\\raw}
- \li \l {reentrant-command} {\\reentrant}
- \li \l {reimp-command} {\\reimp}
- \li \l {relates-command} {\\relates}
- \li \l {row-command} {\\row}
- \li \l {sa-command} {\\sa}
- \li \l {sectionOne-command} {\\section1}
- \li \l {sectionTwo-command} {\\section2}
- \li \l {sectionThree-command} {\\section3}
- \li \l {sectionFour-command} {\\section4}
- \li \l {since-command} {\\since}
- \li \l {skipline-command} {\\skipline}
- \li \l {skipto-command} {\\skipto}
- \li \l {skipuntil-command} {\\skipuntil}
- \li \l {snippet-command} {\\snippet},
- \li \l {span-command} {\\span}
- \li \l {startpage-command} {\\startpage}
- \li \l {sub-command} {\\sub}
- \li \l {subtitle-command} {\\subtitle}
- \li \l {sup-command} {\\sup}
- \li \l {table-command} {\\table}
- \li \l {tableofcontents-command} {\\tableofcontents}
- \li \l {target-command} {\\target}
- \li \l {threadsafe-command} {\\threadsafe}
- \li \l {title-command} {\\title}
- \li \l {tt-command} {\\tt}
- \li \l {typedef-command} {\\typedef}
- \li \l {uicontrol-command} {\\uicontrol}
- \li \l {underline-command} {\\underline}
- \li \l {variable-command} {\\variable}
- \li \l {value-command} {\\value}
- \li \l {warning-command} {\\warning}
- \endlist
-*/
diff --git a/src/tools/qdoc/doc/qdoc-manual-contextcmds.qdoc b/src/tools/qdoc/doc/qdoc-manual-contextcmds.qdoc
deleted file mode 100644
index d707c77cfb..0000000000
--- a/src/tools/qdoc/doc/qdoc-manual-contextcmds.qdoc
+++ /dev/null
@@ -1,1058 +0,0 @@
-/****************************************************************************
-**
-** Copyright (C) 2015 The Qt Company Ltd.
-** Contact: http://www.qt.io/licensing/
-**
-** This file is part of the documentation of the Qt Toolkit.
-**
-** $QT_BEGIN_LICENSE:FDL$
-** Commercial License Usage
-** Licensees holding valid commercial Qt licenses may use this file in
-** accordance with the commercial license agreement provided with the
-** Software or, alternatively, in accordance with the terms contained in
-** a written agreement between you and The Qt Company. For licensing terms
-** and conditions see http://www.qt.io/terms-conditions. For further
-** information use the contact form at http://www.qt.io/contact-us.
-**
-** GNU Free Documentation License Usage
-** Alternatively, this file may be used under the terms of the GNU Free
-** Documentation License version 1.3 as published by the Free Software
-** Foundation and appearing in the file included in the packaging of
-** this file. Please review the following information to ensure
-** the GNU Free Documentation License version 1.3 requirements
-** will be met: http://www.gnu.org/copyleft/fdl.html.
-** $QT_END_LICENSE$
-**
-****************************************************************************/
-
-/*!
- \page 14-qdoc-commands-contextcommands.html
- \previouspage Topic Commands
- \contentspage QDoc Manual
- \nextpage Document Navigation
-
- \title Context Commands
-
- The context commands provide information about the element being
- documented that QDoc can't deduce on its own. For example:
- \list
- \li Is this class thread-safe?
- \li Is this function reentrant?
- \li Of which module is this class a member ?
- \endlist
-
- Context commands can appear anywhere in a QDoc comment,
- but they are normally placed near the top of the comment, just
- below the \l {Topic Commands} {topic} command.
-
- \list
- \li \l {abstract-command} {\\abstract}
- \li \l {compat-command}{\\compat},
- \li \l {contentspage-command}{\\contentspage},
- \li \l {indexpage-command}{\\indexpage},
- \li \l {ingroup-command}{\\ingroup},
- \li \l {inherits-command}{\\inherits},
- \li \l {inmodule-command}{\\inmodule},
- \li \l {internal-command}{\\internal},
- \li \l {nextpage-command}{\\nextpage},
- \li \l {nonreentrant-command}{\\nonreentrant},
- \li \l {obsolete-command}{\\obsolete},
- \li \l {overload-command}{\\overload},
- \li \l {preliminary-command}{\\preliminary},
- \li \l {previouspage-command}{\\previouspage},
- \li \l {qmlabstract-command} {\\qmlabstract}
- \li \l {reentrant-command}{\\reentrant},
- \li \l {reimp-command}{\\reimp},
- \li \l {relates-command}{\\relates},
- \li \l {since-command}{\\since},
- \li \l {startpage-command}{\\startpage},
- \li \l {subtitle-command}{\\subtitle}
- \li \l {threadsafe-command}{\\threadsafe},
- \li \l {title-command}{\\title}
- \endlist
-
-*/
-
-/*!
- \page 15-qdoc-commands-navigation.html
- \previouspage Context Commands
- \contentspage QDoc Manual
- \nextpage Status
-
- \title Document Navigation
-
- The navigation commands are for linking the pages of a document in
- a meaningful sequence. Below is a sequence of QDoc comments that
- shows a typical use of the navigation commands.
-
- \section1 Example
- \quotefile files/basicqt.qdoc.sample
-
- QDoc renders the "Getting Started" page in \c{creatingdialogs.html}:
-
- \quotation
- \raw HTML
- <table border="0" cellpadding="0" cellspacing="5" width="100%">
-
- <tr>
- <p>
- [Previous: <a href="15-qdoc-commands-navigation.html#deadlink">
- Basic Qt</a>]
- [<a href="15-qdoc-commands-navigation.html#deadlink">Contents</a>]
- [Next: <a href="15-qdoc-commands-navigation.html#deadlink">
- Creating Dialogs</a>]
- </p>
-
- <h1 align="center">Getting Started<br /></h1>
-
- <p>
- This chapter shows how to combine basic C++ with the
- functionality provided by Qt to create a few small graphical
- interface (GUI) applications.
- </p>
-
- <p>
- [Previous: <a href="15-qdoc-commands-navigation.html#deadlink">
- Basic Qt</a>]
- [<a href="15-qdoc-commands-navigation.html#deadlink">Contents</a>]
- [Next: <a href="15-qdoc-commands-navigation.html#deadlink">
- Creating Dialogs</a>]
- </p>
-
- </table>
- \endraw
- \endquotation
-
- The \l {indexpage-command} {\\indexpage} and \l
- {startpage-command} {\\startpage} commands create links to the
- page's index page and start page. These links can be used by
- browsers and search engines.
-
- The index page is typically an alphabetical list of the document's
- titles and topics, while the start page is the page considered by
- the author to be the starting point of a multipage document.
-
- The links are included in the generated HTML source code, but have
- no visual effect on the documentation:
-
- \code
- <head>
- ...
- <link rel="index" href="index.html" />
- <link rel="start" href="basicqt.html" />
- ...
- </head>
- \endcode
-
- \section1 Commands
-
- \target previouspage-command
- \section2 \\previouspage
-
- The \\previouspage command links the current page to the previous
- page in a sequence.a The command has two arguments, each enclosed
- by curly braces: the first is the link target (the title of
- the previous page), the second is the link text. If the page's
- title is equivalent to the link text, the second argument can be
- omitted.
-
- The command must stand alone on its own line.
-
- \target nextpage-command
- \section2 \\nextpage
-
- The \\nextpage command links the current page to the next page in
- a sequence. The command follows the same syntax and argument
- convention as the \l {previouspage-command} {\\previouspage}
- command.
-
- \target startpage-command
- \section2 \\startpage
-
- The \\startpage command specifies the first page of a sequence of
- pages. The command must stand alone on its own line, and its
- unique argument is the title of the first document.
-
- QDoc will generate a link to the start page and include it in the
- generated HTML file, but this has no visual effect on the
- documentation. The generated link type tells browsers and search
- engines which document is considered by the author to be the
- starting point of the collection.
-
- \target contentspage-command
- \section2 \\contentspage
-
- The \\contentspage command links the current page to a table of
- contents page. The command follows the same syntax and argument
- convention as the \l {previouspage-command} {\\previouspage}
- command.
-
- \target indexpage-command
- \section2 \\indexpage
-
- The \\indexpage command specifies an index page for the current
- document. The command must stand alone on its own line, and its
- unique argument is the title of the index document.
-
- QDoc will generate a link to the index page and include it in the
- generated HTML file, but this has no visual effect on the
- documentation. The generated link type tells browsers and search
- engines which document is considered by the author to be the
- index page of the collection.
-*/
-
-/*!
- \page 16-qdoc-commands-status.html
- \previouspage Document Navigation
- \contentspage QDoc Manual
- \nextpage Thread Support
-
- \title Status
-
- These commands are for indicating that a documented element has
- some special status. The element could be marked as about to be
- made obsolete, or that it is provided for compatibility with an
- earlier version, or is simply not to be included in the public
- interface. The \l {since-command}{\\since} command is for
- specifying the version number in which a function or class first
- appeared. The \l {qmlabstract-command} {\\qmlabstract} command is
- for marking a QML type as an abstract base class.
-
- \target abstract-command
- \target qmlabstract-command
- \section1 \\abstract and \\qmlabstract
-
- \\abstract is a synonym for the \\qmlabstract command. Add this
- command to the \l {qmltype-command} {\\qmltype} comment for a QML
- type when that type is meant to be used \e {only} as an abstract
- base type. When a QML type is abstract, it means that the QML type
- that can't be instantiated. Instead, the properties in its public
- API are included in the public properties list on the reference
- page for each QML type that inherits the abstract QML type. The
- properties are documented as if they are properties of the
- inheriting QML type.
-
- Normally, when a QML type is marked with \e{\\qmlabstract}, it is
- also marked with \e{\\internal} so that its reference page is not
- generated. It the abstract QML type is not marked internal, it
- will have a reference page in the documentation.
-
- \target compat-command
- \section1 \\compat
-
- The \\compat command is for indicating that a class or function is
- part of the support library provided to keep old source code
- working.
-
- The command must stand on its own line.
-
- Usually an equivalent function or class is provided as an
- alternative.
-
- If the command is used in the documentation of a class, the
- command expands to a warning that the referenced class is part of
- the support library. The warning is located at the top of the
- documentation page.
-
- \code
- \beginqdoc
- \class MyQt3SupportClass
- \compat
- \endqdoc
- \endcode
-
- QDoc renders this at the top of the MyQt3SupportClass class
- reference page.
-
- \quotation
- \b {This class is part of the Qt 3 support
- library.} It is provided to keep old source code
- working. We strongly advise against using it in new
- code. See the \l
- {http://doc.qt.io/qt-4.8/porting4.html} {Porting
- Guide} for more information.
- \endquotation
-
- If the command is used when documenting a function, QDoc will
- create and link to a separate page documenting Qt 3 support
- members when generating the reference documentation for the
- associated class.
-
- \code
- \beginqdoc
- \fn MyClass::MyQt3SupportMemberFunction
- \compat
-
- Use MyNewFunction() instead.
- \endqdoc
- \endcode
-
- QDoc renders this in \c{myclass-qt3.html} as:
-
- \quotation
- \raw HTML
- <h1>Qt 3 Support Members for MyClass</h1>
- \endraw
-
- \b {The following class members are part of the Qt 3
- support layer.} They are provided to help you port old code to
- Qt 4. We advise against using them in new code.
-
- ...
-
- \list
- \li void MyQt3SupportMemberFunction()
- \li ...
- \endlist
-
- \raw HTML
- <hr />
- <h2>Member Function Documentation</h2>
- <h3>void MyQt3SupportMemberFunction ()</h3>
- <p>Use MyNewFunction() instead.</p>
- \endraw
- ...
- \endquotation
-
- \target default-command
- \section1 \\default
-
- The \\default command is for marking a QML property as the
- \l {default-properties}
- {default property}. The word \span {class="newStuff"} {default} is shown in red in
- the documentation of the property.
-
- \code
- / *!
- \qmlproperty list<Change> State::changes
- This property holds the changes to apply for this state.
- \default
-
- By default these changes are applied against the default state. If the state
- extends another state, then the changes are applied against the state being
- extended.
- * /
- \endcode
-
- See how QDoc renders this property on the reference page for the
- \l {State::changes}{State} type.
-
- \target obsolete-command
- \section1 \\obsolete
-
- The \\obsolete command is for indicating that a function is being
- deprecated, and it should no longer be used in new code. There is
- no guarantee for how long it will remain in the library.
-
- The command must stand on its own line.
-
- When generating the reference documentation for a class, QDoc will
- create and link to a separate page documenting its obsolete
- functions. Usually an equivalent function is provided as an
- alternative.
-
- \code
- / *!
- \fn MyClass::MyObsoleteFunction
- \obsolete
-
- Use MyNewFunction() instead.
- * /
- \endcode
-
- QDoc renders this in \c{myclass-obsolete.html} as:
-
- \quotation
- \raw HTML
- <h1>Obsolete Members for MyClass</h1>
- \endraw
-
- \b {The following class members are obsolete.} They are
- provided to keep old source code working. We strongly advise
- against using them in new code.
-
- ...
-
- \list
- \li void MyObsoleteFunction() \c (obsolete)
- \li ...
- \endlist
-
- \raw HTML
- <hr />
- <h2>Member Function Documentation</h2>
- <h3>void MyObsoleteFunction ()</h3>
- <p>Use MyNewFunction() instead.</p>
- \endraw
- ...
- \endquotation
-
- \target internal-command
- \section1 \\internal
-
- The \\internal command indicates that the referenced
- function is not part of the public interface.
-
- The command must stand on its own line.
-
- QDoc ignores the documentation as well as the documented item,
- when generating the associated class reference documentation.
-
- \code
- / *!
- \internal
-
- Tries to find the decimal separator. If it can't find
- it and the thousand delimiter is != '.' it will try to
- find a '.';
- * /
- int QDoubleSpinBoxPrivate::findDelimiter
- (const QString &str, int index) const
- {
- int dotindex = str.indexOf(delimiter, index);
- if (dotindex == -1 && thousand != dot && delimiter != dot)
- dotindex = str.indexOf(dot, index);
- return dotindex;
- }
- \endcode
-
- This function will not be included in the documentation.
-
- \target preliminary-command
- \section1 \\preliminary
-
- The \\preliminary command is for indicating that a referenced
- function is still under development.
-
- The command must stand on its own line.
-
- The \\preliminary command expands to a notification in the
- function documentation, and marks the function as preliminary when
- it appears in lists.
-
- \code
- / *!
- \preliminary
-
- Returns information about the joining type attributes of the
- character (needed for certain languages such as Arabic or
- Syriac).
-
- * /
- QChar::JoiningType QChar::joiningType() const
- {
- return QChar::joiningType(ucs);
- }
- \endcode
-
- QDoc renders this as:
-
- \quotation
- \raw HTML
- <h3>
- <a href="http://doc.qt.io/qt-5/qchar.html#JoiningType-enum">JoiningType</a>
- QChar::joiningType() const</h3>
- \endraw
-
- \b {This function is under development and
- subject to change.}
-
- Returns information about the joining type attributes of the
- character (needed for certain languages such as Arabic or
- Syriac).
- \endquotation
-
- And the function's entry in QChar's list of public functions will be
- rendered as:
-
- \quotation
- \list
- \li ...
- \li JoiningType \l {QChar::joiningType()} {joiningType}() const \c (preliminary)
- \li ...
- \endlist
- \endquotation
-
- \target since-command
- \section1 \\since
-
- The \\since command tells in which minor release
- the associated functionality was added.
-
- \code
- / *!
- \since 4.1
-
- Returns an icon for \a standardIcon.
-
- ...
-
- \sa standardPixmap()
- * /
- QIcon QStyle::standardIcon(StandardPixmap standardIcon, const QStyleOption *option, const QWidget *widget) const
- {
- }
- \endcode
-
- QDoc renders this as:
-
- \quotation
- \raw HTML
- <h3>QIcon QStyle::standardIcon(StandardPixmap standardIcon, const QStyleOption *option, const QWidget *widget) const</h3>
- \endraw
-
- This function was introduced in Qt version 4.1
-
- Returns an icon for \a standardIcon.
-
- ...
-
- See also \l {QStyle::standardPixmap()} {standardPixmap()}.
- \endquotation
-
- QDoc generates the "Qt" reference from the \l
- {25-qdoc-configuration-derivedprojects.html#project} {\c project}
- configuration variable. For that reason this reference will change
- according to the current documentation project.
-
- See also \l {project}
- {\c project}.
-*/
-
-
-/*!
- \page 17-qdoc-commands-thread.html
- \previouspage Status
- \contentspage QDoc Manual
- \nextpage Relating Things
-
- \title Thread Support
-
- The thread support commands are for specifying the level of
- support for multithreaded programming in a class or function.
- There are three levels of support: \c threadsafe, \c reentrant and
- \c nonreentrant.
-
- The default is \c nonreentrant which means that the associated
- class or function cannot be called by multiple threads. \c
- Reentrant and \c threadsafe are levels primarily used for classes.
-
- \c Reentrant means that all the functions in the referenced class
- can be called simultaneously by multiple threads, provided that
- each invocation of the functions reference unique data. While \c
- threadsafe means that all the functions in the referenced class
- can be called simultaneously by multiple threads even when each
- invocation references shared data.
-
- When a class is marked \l {reentrant-command} {\\reentrant} or \l
- {threadsafe-command} {\\threadsafe}, functions in that class can
- be marked \c nonreentrant using the \l {nonreentrant-command}
- {\\nonreentrant} command.
-
- \section1 Example
-
- \target reentrant-example
- \code
- \beginqdoc
- \class QLocale
- \brief The QLocale class converts between numbers and their
- string representations in various languages.
-
- \reentrant
- \ingroup i18n
- \ingroup text
-
- QLocale is initialized with a language/country pair in its
- constructor and offers number-to-string and string-to-number
- conversion functions similar to those in QString.
-
- ...
-
- \nonreentrant
-
- Sets the global default locale to \a locale. These values are
- used when a QLocale object is constructed with no
- arguments. If this function is not called, the system's locale
- is used.
-
- \warning In a multithreaded application, the default locale
- should be set at application startup, before any non-GUI
- threads are created.
-
- \sa system(), c()
- \endqdoc
- void QLocale::setDefault(const QLocale &locale)
- {
- default_d = locale.d;
- }
- \endcode
-
- QDoc renders this as:
-
- \quotation
- \raw HTML
- <h1><center>QLocale Class Reference</center></h1>
- \endraw
-
- The QLocale class converts between numbers and their string
- representations in various languages. More...
-
- \code
- #include <QLocale>
- \endcode
-
- \b {Note:} All the functions in this class are \l
- {17-qdoc-commands-thread.html#reentrant} {reentrant}, except \l
- {QLocale::setDefault()} {setDefault()}.
-
- ...
-
- \raw HTML
- <hr />
- <h2>Member Type Documentation</h2>
- \endraw
-
- ...
-
- \raw HTML
- <h3>void QLocale::setDefault ( const QLocale & locale ) </h3>
- \endraw
-
- Sets the global default locale to locale. These values are
- used when a QLocale object is constructed with no
- arguments. If this function is not called, the system's locale
- is used.
-
- \warning In a multithreaded application, the default locale
- should be set at application startup, before any non-GUI
- threads are created.
-
- \warning This function is not reentrant.
-
- See also \l {QLocale::system()} {system()} and \l
- {QLocale::c()} {c()}.
-
- ...
- \endquotation
-
- As shown above, QDoc generates a notification when a class is
- declared reentrant, and lists the exceptions (the declared
- nonreentrant functions). A link to the general documentation on \l
- {17-qdoc-commands-thread.html#reentrant} {reentrancy and thread-safety} is
- included. In addition a warning, "\b Warning: This function is
- not reentrant.", is generated in the nonreentrant functions'
- documentation.
-
- QDoc will generate the same notification and warnings when a class
- is declared threadsafe.
-
- For more information see the general documentation on \l
- {17-qdoc-commands-thread.html#reentrant} {reentrancy and thread-safety}.
-
- \section1 Commands
-
- \target threadsafe-command
- \section2 \\threadsafe
-
- The \\threadsafe command includes a line in the documentation to
- indicate that the associated class or function is \e threadsafe
- and can be called simultaneously by multiple threads, even when
- separate invocations reference shared data.
-
- The command must stand on its own line.
-
- The documentation generated from this command will be similar to
- the what is generated for the \l {reentrant-command} {\\reentrant}
- command. See the example above in the \l {reentrant-example}
- {introduction}.
-
- See also \l{reentrant-command} {\\reentrant} and
- \l{nonreentrant-command} {\\nonreentrant}.
-
- \target reentrant-command
- \section2 \\reentrant
-
- The \\reentrant command indicates that the associated class or
- function can be called simultaneously by multiple threads,
- provided that each invocation references its own data. See the \l
- {reentrant-example} {example} above.
-
- The command must stand on its own line.
-
- See also \l{nonreentrant-command} {\\nonreentrant} and
- \l{threadsafe-command} {\\threadsafe}.
-
- \target nonreentrant-command
- \section2 \\nonreentrant
-
- The \\nonreentrant command indicates that the associated class or
- function cannot be called by multiple threads. Nonreentrant is the
- default case.
-
- The command must stand on its own line.
-
- When a class is marked \l {reentrant-command} {\\reentrant} or \l
- {threadsafe-command} {\\threadsafe}, functions in that class can
- be marked \c nonreentrant using this command in the \l{fn-command}
- {\\fn} comment of the functions to be excluded.
-
- See also \l{reentrant-command} {\\reentrant} and
- \l{threadsafe-command} {\\threadsafe}.
-*/
-
-/*!
- \page 18-qdoc-commands-relating.html
- \previouspage Thread Support
- \contentspage QDoc Manual
- \nextpage Grouping Things
-
- \title Relating Things
-
- The relating commands are for specifying how one documented
- element relates to another documented element. Some examples:
- \list
- \li This function is an overload of another function.
- \li This function is a reimplementation of another function.
- \li This typedef is \e related to some class or header file.
- \endlist
-
- There is also a command for documenting that a QML type inherits
- some other QML type.
-
- \section1 Commands
-
- \target inherits-command
- \section2 \\inherits
-
- The \\inherits command is for documenting that one QML type
- inherits some other QML type. It must be included in the
- inheriting element's \l{qmltype-command}{\\qmltype} comment.
- The argument is the name of the inherited QML type.
-
- \code
- / *!
- \qmltype PauseAnimation
- \instantiates QDeclarativePauseAnimation
- \ingroup qml-animation-transition
- \since 4.7
- \inherits Animation
- \brief The PauseAnimation element provides a pause for an animation.
-
- When used in a SequentialAnimation, PauseAnimation is a step
- when nothing happens, for a specified duration.
-
- A 500ms animation sequence, with a 100ms pause between two animations:
-
- SequentialAnimation {
- NumberAnimation { ... duration: 200 }
- PauseAnimation { duration: 100 }
- NumberAnimation { ... duration: 200 }
- }
-
- \sa {QML Animation and Transitions}, {declarative/animation/basics}{Animation basics example}
- * /
- \endcode
-
- QDoc includes this line on the reference page for the
- \l{http://qt-project.org/doc/qt-4.7/qml-pauseanimation.html} {PauseAnimation}
- element:
-
- \quotation
- Inherits \l{http://qt-project.org/doc/qt-4.7/qml-animation.html} {Animation}
- \endquotation
-
- \target overload-command
- \section2 \\overload
-
- The \\overload command is for indicating that a function is a
- secondary overload of its name.
-
- The command must stand on its own line.
-
- For a function name that is overloaded (except constructors), QDoc
- expects one primary version of the function, and all the others
- marked with the \b {\\overload command}. The primary version
- should be fully documented. Each overload can have whatever extra
- documentation you want to add for just that overloaded version.
-
- From Qt 4.5, you can include the function name plus '()' as a
- parameter to the \b{\\overload} command, which will include a
- standard \e{This function overloads...} line of text with a link
- to the documentation for the primary version of the function.
-
- \code
- / *!
- \overload addAction()
-
- This convenience function creates a new action with an
- \a icon and some \a text. The function adds the newly
- created action to the menu's list of actions, and
- returns it.
-
- \sa QWidget::addAction()
- * /
- QAction *QMenu::addAction(const QIcon &icon, const QString &text)
- {
- QAction *ret = new QAction(icon, text, this);
- addAction(ret);
- return ret;
- }
- \endcode
-
- QDoc renders this as:
-
- \quotation
- \raw HTML
- <h3><a href="http://doc.qt.io/qt-5/qaction.html">QAction</a>
- * QMenu::addAction ( const QIcon & <i>icon</i>,
- const QString & <i>text</i> )
- </h3>
- \endraw
-
- This function overloads \l {QMenu::addAction()} {addAction()}
-
- This convenience function creates a new action with an
- \e icon and some \e text. The function adds the newly
- created action to the menu's list of actions, and
- returns it.
-
- See also
- \l {QWidget::addAction()} {QWidget::addAction}().
- \endquotation
-
- If you don't include the function name with the \b{\\overload}
- command, then instead of the "This function overloads..." line
- with the link to the documentation for the primary version, you
- get the old standard line:
-
- \quotation
- This is an overloaded member function, provided for
- convenience.
- \endquotation.
-
- \target reimp-command
- \section2 \\reimp
-
- The \\reimp command is for indicating that a function is a
- reimplementation of a virtual function.
-
- The command must stand on its own line.
-
- QDoc will omit the reimplemented function from the class
- reference.
-
- \code
- / *!
- \reimp
- * /
- void QToolButton::nextCheckState()
- {
- Q_D(QToolButton);
- if (!d->defaultAction)
- QAbstractButton::nextCheckState();
- else
- d->defaultAction->trigger();
- }
- \endcode
-
- This function will not be included in the documentation. Instead,
- a link to the base function QAbstractButton::nextCheckState() will
- appear in the documentation.
-
- \target relates-command
- \section2 \\relates
-
- The \\relates command is for including the documentation of a
- global element to some class or header file. The argument is a
- class name or header file.
-
- \code
- / *!
- \relates QChar
-
- Reads a char from the stream \a in into char \a chr.
-
- \sa {Format of the QDataStream operators}
- * /
- QDataStream &operator>>(QDataStream &in, QChar &chr)
- {
- quint16 u;
- in >> u;
- chr.unicode() = ushort(u);
- return in;
- }
- \endcode
-
- The documentation for this function will be included on the reference page
- for class QChar.
-*/
-
-/*!
- \page 19-qdoc-commands-grouping.html
- \previouspage Relating Things
- \contentspage QDoc Manual
- \nextpage Naming Things
-
- \title Grouping Things
-
- The grouping commands relate classes to defined groups and
- modules. The groups are used when generating lists of related
- classes in the documentation, while the modules are elements of
- Qt's structure.
-
- \section1 Commands
-
- \target ingroup-command
- \section2 \\ingroup
-
- The \\ingroup command indicates that the given
- overview or documented class belongs to a certain group of
- related docmentation.
-
- A class or overview may belong to many groups.
-
- The \\ingroup command's argument is a group name, but note
- that the command considers the rest of the line as part of
- its argument. Make sure that the group name is followed by
- a linebreak.
-
- \code
- / *!
- \class QDir
- \brief The QDir class provides access to directory
- structures and their contents.
-
- \ingroup io
- ...
- * /
- \endcode
-
- This will include the QDir class in the \c io group, which means,
- for example, that QDir will appear on the list created by calling
- the \l {group-command} {\\group} command with the \c io argument.
-
- To list overviews that are related to a certain group, you must
- generate the list explicitly using the \l {generatelist-command}
- {\\generatelist} command with the \c related argument.
-
- See also \l {group-command} {\\group}.
-
- \target inmodule-command
- \section2 \\inmodule
-
- The \\inmodule command relates a class to the module specified by
- the command's argument.
-
- For the basic classes in Qt, a class's module is determined by its
- location, namely its directory. However, for extensions like
- ActiveQt and Qt Designer, a class must be related to a module
- explicitly.
-
- The command's argument is a module name, but note that the command
- considers the rest of the line as part of its argument. Make sure
- that the module name is followed by a linebreak.
-
- \code
- /*!
- \class QDesignerTaskMenuExtension
- \inmodule QtDesigner
- * /
- \endcode
-
- This ensures that the QDesignerTaskMenuExtension class is included
- in the Qt Designer module, which means, for example, that the
- class will appear on the list created by calling the \l
- {generatelist-command} {\\generatelist} command with the \c
- {{classesbymodule QtDesigner}} argument.
-
- See also \l {module-command} {\\module} and \l
- {generatelist-command} {\\generatelist}.
-*/
-
-/*!
- \page 20-qdoc-commands-namingthings.html
- \previouspage Grouping Things
- \contentspage QDoc Manual
- \nextpage Markup Commands
-
- \title Naming Things
-
- In general, a title command considers everything that follows it
- until the first line break as its argument. If the title is so
- long it must span multiple lines, end each line (except the last
- one) with a backslash.
-
- \section1 Commands
-
- \target title-command
- \section2 \\title
-
- The \\title command sets the title for a documentation page, or
- allows you to override it.
-
- \code
- / *!
- \page signalandslots.html
-
- \title Signals & Slots
-
- Signals and slots are used for communication between
- objects. The signals and slots mechanism is a central
- feature of Qt, and probably the part that differs most
- from the features provided by other frameworks.
-
- ...
- * /
- \endcode
-
- QDoc renders this as:
-
- \quotation
- \raw HTML
- <h1><center>Signal and Slots</center></h1>
- \endraw
-
- Signals and slots are used for communication between
- objects. The signals and slots mechanism is a central
- feature of Qt and probably the part that differs most
- from the features provided by other frameworks.
- ...
- \endquotation
- See also \l {subtitle-command} {\\subtitle}.
-
- \target subtitle-command
- \section2 \\subtitle
-
- The \\subtitle command sets a subtitle for a documentation page.
-
- \code
- \beginqdoc
- \page qtopiacore-overview.html
-
- \title Qtopia Core
- \subtitle Qt for Embedded Linux
-
- Qt/Embedded, the embedded Linux port of Qt, is a
- complete and self-contained C++ GUI and platform
- development tool for Linux-based embedded development.
- ...
- \endqdoc
- \endcode
-
- QDoc renders this as:
-
- \quotation
- \raw HTML
- <h1><center>Qtopia Core</center></h1>
- <h2><center>Qt for Embedded Linux</center></h2>
- \endraw
-
- Qt/Embedded, the embedded Linux port of Qt, is a
- complete and self-contained C++ GUI and platform
- development tool for Linux-based embedded development.
- ...
- \endquotation
-
- See also \l {title-command} {\\title}.
-
-*/
diff --git a/src/tools/qdoc/doc/qdoc-manual-intro.qdoc b/src/tools/qdoc/doc/qdoc-manual-intro.qdoc
deleted file mode 100644
index 84f9416843..0000000000
--- a/src/tools/qdoc/doc/qdoc-manual-intro.qdoc
+++ /dev/null
@@ -1,325 +0,0 @@
-/****************************************************************************
-**
-** Copyright (C) 2015 The Qt Company Ltd.
-** Contact: http://www.qt.io/licensing/
-**
-** This file is part of the documentation of the Qt Toolkit.
-**
-** $QT_BEGIN_LICENSE:FDL$
-** Commercial License Usage
-** Licensees holding valid commercial Qt licenses may use this file in
-** accordance with the commercial license agreement provided with the
-** Software or, alternatively, in accordance with the terms contained in
-** a written agreement between you and The Qt Company. For licensing terms
-** and conditions see http://www.qt.io/terms-conditions. For further
-** information use the contact form at http://www.qt.io/contact-us.
-**
-** GNU Free Documentation License Usage
-** Alternatively, this file may be used under the terms of the GNU Free
-** Documentation License version 1.3 as published by the Free Software
-** Foundation and appearing in the file included in the packaging of
-** this file. Please review the following information to ensure
-** the GNU Free Documentation License version 1.3 requirements
-** will be met: http://www.gnu.org/copyleft/fdl.html.
-** $QT_END_LICENSE$
-**
-****************************************************************************/
-
-/*!
- \page 01-qdoc-manual.html
- \contentspage QDoc Manual
- \previouspage QDoc Manual
- \nextpage Command Index
-
- \title Introduction to QDoc
-
- QDoc is a tool used by Qt Developers to generate documentation for
- software projects. It works by extracting \e {QDoc comments} from
- project source files and then formatting these comments as HTML
- pages or DITA XML documents. QDoc finds QDoc comments in \c
- {.cpp} files and in \c {.qdoc} files. QDoc does not look for QDoc
- comments in \c {.h} files. A QDoc comment always begins with an
- exclamation mark (\b{!})). For example:
-
- \code
- / *!
- \class QObject
- \brief The QObject class is the base class of all Qt objects.
-
- \ingroup objectmodel
-
- \reentrant
-
- QObject is the heart of the Qt \l{Object Model}. The
- central feature in this model is a very powerful mechanism
- for seamless object communication called \l{signals and
- slots}. You can connect a signal to a slot with connect()
- and destroy the connection with disconnect(). To avoid
- never ending notification loops you can temporarily block
- signals with blockSignals(). The protected functions
- connectNotify() and disconnectNotify() make it possible to
- track connections.
-
- QObjects organize themselves in \l {Object Trees &
- Ownership} {object trees}. When you create a QObject with
- another object as parent, the object will automatically
- add itself to the parent's \c children() list. The parent
- takes ownership of the object. It will automatically
- delete its children in its destructor. You can look for an
- object by name and optionally type using findChild() or
- findChildren().
-
- Every object has an objectName() and its class name can be
- found via the corresponding metaObject() (see
- QMetaObject::className()). You can determine whether the
- object's class inherits another class in the QObject
- inheritance hierarchy by using the \c inherits() function.
-
- ....
- * /
- \endcode
-
- From the QDoc comment above, QDoc generates the HTML \l {QObject}
- {QObject class reference} page.
-
- This manual explains how to use the QDoc commands in QDoc comments
- to embed good documentation in your source files. It also explains
- how to make a \l {The QDoc Configuration File} {QDoc configuration
- file}, which you will pass to QDoc on the command line.
-
- \section1 Running QDoc
-
- 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}
- \endquotation
-
- QDoc recognizes the \c {.qdocconf} suffix as a \l{The QDoc
- Configuration File} {QDoc configuration file}. The configuration
- file is where you tell QDoc where to find the project source
- files, header files, and \c {.qdoc} files. It is also where you
- tell QDoc what kind of output to generate (HTML, DITA XML,...),
- and where to put the generated documentation. The configuration
- file also contains other information for QDoc.
-
- 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
- command line. It stores all the variables from the configuration
- file for later use. One of the first variables it uses is \c
- {outputformats}. This variable tells QDoc which output generators
- it will run. The default value is \e {HTML}, so if you don't set
- \c {outputformats} in your configuration file, QDoc will generate
- HTML output. That's usually what you will want anyway, but you can
- also specify \e {DITAXML} to get DITA XML output instead.
-
- Next, QDoc uses the values of the
- \l {headerdirs-variable}
- {headerdirs} variable and/or the \l
- {22-qdoc-configuration-generalvariables.html#headers-variable}
- {headers} variable to find and parse all the header files for your
- project. QDoc does \e not scan header files for QDoc comments. It
- parses the header files to build a master tree of all the items
- that should be documented, in other words, the items that QDoc should find
- QDoc comments for.
-
- After parsing all the header files and building the master tree of
- items to be documented, QDoc uses the value of the \l
- {22-qdoc-configuration-generalvariables.html#sourcedirs-variable}
- {sourcedirs} variable and/or the value of the \l
- {22-qdoc-configuration-generalvariables.html#sources-variable}
- {sources} variable to find and parse all the \c {.cpp} and \c
- {.qdoc} files for your project. These are the files QDoc scans for
- \e {QDoc comments}. Remember that a QDoc comment begins with
- an exclamation mark: \b {/*!} .
-
- For each QDoc comment it finds, it searches the master tree for
- the item where the documentation belongs. Then it interprets the
- qdoc commands in the comment and stores the interpreted commands
- and the comment text in the tree node for the item.
-
- Finally, QDoc traverses the master tree. For each node, if the
- node has stored documentation, QDoc calls the output generator
- specified by the \c {outputformats} variable to format and write
- the documentation in the directory specified in the configuration
- file in the \l
- {22-qdoc-configuration-generalvariables.html#outputdir-variable}
- {outputdir} variable.
-
- \section1 Command Types
-
- QDoc interprets three types of commands:
-
- \list
- \li \l {Topic Commands}
- \li \l {Context Commands}
- \li \l {Markup Commands}
- \endlist
-
- Topic commands identify the element you are documenting, for example
- a C++ class, function, type, or an extra page of text
- that doesn't map to an underlying C++ element.
-
- Context commands tell QDoc how the element being documented
- relates to other documented elements, for example, next and previous page
- links, inclusion in page groups, or library modules. Context
- commands can also provide information about the documented element
- that QDoc can't get from the source files, for example, whether the
- element is thread-safe, whether it is an overloaded or reimplemented function,
- or whether it has been deprecated.
-
- Markup commands tell QDoc how text and image elements in the
- document should be rendered, or about the document's outline
- structure.
-*/
-
diff --git a/src/tools/qdoc/doc/qdoc-manual-markupcmds.qdoc b/src/tools/qdoc/doc/qdoc-manual-markupcmds.qdoc
deleted file mode 100644
index 49cbfc0654..0000000000
--- a/src/tools/qdoc/doc/qdoc-manual-markupcmds.qdoc
+++ /dev/null
@@ -1,4081 +0,0 @@
-/****************************************************************************
-**
-** Copyright (C) 2015 The Qt Company Ltd.
-** Contact: http://www.qt.io/licensing/
-**
-** This file is part of the documentation of the Qt Toolkit.
-**
-** $QT_BEGIN_LICENSE:FDL$
-** Commercial License Usage
-** Licensees holding valid commercial Qt licenses may use this file in
-** accordance with the commercial license agreement provided with the
-** Software or, alternatively, in accordance with the terms contained in
-** a written agreement between you and The Qt Company. For licensing terms
-** and conditions see http://www.qt.io/terms-conditions. For further
-** information use the contact form at http://www.qt.io/contact-us.
-**
-** GNU Free Documentation License Usage
-** Alternatively, this file may be used under the terms of the GNU Free
-** Documentation License version 1.3 as published by the Free Software
-** Foundation and appearing in the file included in the packaging of
-** this file. Please review the following information to ensure
-** the GNU Free Documentation License version 1.3 requirements
-** will be met: http://www.gnu.org/copyleft/fdl.html.
-** $QT_END_LICENSE$
-**
-****************************************************************************/
-
-/*!
- \page 03-qdoc-commands-markup.html
- \contentspage QDoc Manual
- \previouspage Naming Things
- \nextpage Text Markup
-
- \title Markup Commands
-
- The markup commands indicate the generated documentation's visual
- appearance and logical structure.
-
- \list
- \li \l {a-command} {\\a}
- \li \l {annotatedlist-command} {\\annotatedlist}
- \li \l {b-command} {\\b} \span {class="newStuff"}
- \li \l {b-command} {\\bold} {(deprecated, use \\b)}
- \li \l {brief-command} {\\brief}
- \li \l {c-command} {\\c}
- \li \l {caption-command} {\\caption}
- \li \l {chapter-command} {\\chapter}
- \li \l {code-command} {\\code}
- \li \l {codeline-command} {\\codeline}
- \li \l {div-command} {\\div}
- \li \l {dots-command} {\\dots}
- \li \l {e-command} {\\e} \span {class="newStuff"}
- \li \l {else-command} {\\else}
- \li \l {endif-command} {\\endif}
- \li \l {footnote-command} {\\footnote}
- \li \l {generatelist-command} {\\generatelist}
- \li \l {header-command} {\\header}
- \li \l {e-command} {\\i} \span {class="newStuff"} {(deprecated, use \\e)}
- \li \l {if-command} {\\if}
- \li \l {image-command} {\\image}
- \li \l {include-command} {\\include}
- \li \l {include-command} {\\input}
- \li \l {inlineimage-command} {\\inlineimage}
- \li \l {keyword-command} {\\keyword}
- \li \l {l-command} {\\l}
- \li \l {legalese-command} {\\legalese}
- \li \l {li-command} {\\li} \span {class="newStuff"}
- \li \l {list-command} {\\list}
- \li \l {meta-command} {\\meta}
- \li \l {noautolist-command} {\\noautolist}
- \li \l {newcode-command} {\\newcode}
- \li \l {li-command} {\\o} \span {class="newStuff"} {(deprecated, use \\li)}
- \li \l {note-command} {\\note}
- \li \l {oldcode-command} {\\oldcode}
- \li \l {omit-command} {\\omit}
- \li \l {part-command} {\\part}
- \li \l {printline-command} {\\printline}
- \li \l {printto-command} {\\printto}
- \li \l {printuntil-command} {\\printuntil}
- \li \l {quotation-command} {\\quotation}
- \li \l {quotefile-command} {\\quotefile}
- \li \l {quotefromfile-command} {\\quotefromfile}
- \li \l {raw-command} {\\raw}
- \li \l {row-command} {\\row}
- \li \l {sa-command} {\\sa}
- \li \l {sectionOne-command} {\\section1}
- \li \l {sectionTwo-command} {\\section2}
- \li \l {sectionThree-command} {\\section3}
- \li \l {sectionFour-command} {\\section4}
- \li \l {skipline-command} {\\skipline}
- \li \l {skipto-command} {\\skipto}
- \li \l {skipuntil-command} {\\skipuntil}
- \li \l {snippet-command} {\\snippet}
- \li \l {span-command} {\\span}
- \li \l {sub-command} {\\sub}
- \li \l {sup-command} {\\sup}
- \li \l {table-command} {\\table}
- \li \l {tableofcontents-command} {\\tableofcontents}
- \li \l {target-command} {\\target}
- \li \l {tt-command} {\\tt}
- \li \l {uicontrol-command} {\\uicontrol} {(new 25/3/2012)}
- \li \l {underline-command} {\\underline}
- \li \l {raw-command} {\\unicode}
- \li \l {warning-command} {\\warning}
- \li \l {backslash-command} {\\\\}
- \endlist
-*/
-
-
-/*!
- \page 04-qdoc-commands-textmarkup.html
- \contentspage QDoc Manual
- \previouspage Markup Commands
- \nextpage Document Structure
-
- \title Text Markup
-
- The text formatting commands indicate how text is to be rendered.
-
- \target a-command
- \section1 \\a (parameter marker)
-
- The \\a command tells QDoc the next word is a formal parameter name.
-
- A warning is emitted when a formal parameter is not documented or
- is misspelled, so when you document a function you should mention
- each formal parameter by name in the function description,
- preceded by the \\a command. The parameter name is then rendered
- in italics.
-
- \code
- / *!
- Constructs a line edit containing the text
- \a contents. The \a parent parameter is sent
- to the QWidget constructor.
- * /
-
- QLineEdit::QLineEdit(const QString &contents, QWidget *parent) :QWidget(parent)
- {
- ...
- }
-
- \endcode
-
- QDoc renders this as:
-
- \quotation
- \b {QLineEdit::QLineEdit ( const QString &
- contents, QWidget *parent )}
-
- Constructs a line edit containing the text \a contents.
- The \a parent parameter is sent to the QWidget constructor.
- \endquotation
-
- The formal parameter name may be enclosed between curly brackets,
- but that isn't required.
-
- \target c-command
- \section1 \\c (code font)
-
- The \\c command is used for rendering variable names, user-defined
- class names, and C++ keywords (for example, \c int and \c for) in the code
- font.
-
- The command renders its argument using a monospace font. For
- example:
-
- \code
- / *!
- The \c AnalogClock class provides a clock widget with hour
- and minute hands that is automatically updated every
- few seconds.
- * /
- \endcode
-
- QDoc renders this as:
-
- \quotation
- The \c AnalogClock class provides a clock widget with hour
- and minute hands, which are automatically updated every
- few seconds.
- \endquotation
-
- If the text to be rendered in the code font contains spaces, enclose the
- entire text in curly brackets.
-
- \code
- \c {QLineEdit::QLineEdit(const QString &contents, QWidget *parent) :QWidget(parent)}
- \endcode
-
- QDoc renders this as:
-
- \quotation
- \c {QLineEdit::QLineEdit(const QString &contents, QWidget *parent) :QWidget(parent)}
- \endquotation
-
- The \\c command accepts the special character \c \ within its
- argument, which renders it as a normal character. So if you want
- to use nested commands, you must use the \l {tt-command} {teletype
- (\\tt)} command instead.
-
- See also \l {tt-command} {\\tt} and \l {code-command} {\\code}.
-
- \target div-command
- \section1 \\div
-
- The \\div and \\enddiv commands delimit a large or small block of
- text (which may include other QDoc commands) to which special
- formatting attributes should be applied.
-
- An argument must be provided in curly braces, as in the qdoc
- comment shown below. The argument is not interpreted but is used
- as attribute(s) of the tag that is output by qdoc.
-
- For example, we might want to render an inline image so that it
- floats to the right of the current block of text:
-
- \code
- / *!
- \div {class="float-right"}
- \inlineimage qml-column.png
- \enddiv
-
- * /
- \endcode
-
- If qdoc is generating HTML, it will translate these commands to:
-
- \code
- <div class="float-right"><p><img src="images/qml-column.png" /></p></div>
- \endcode
-
- For HTML, the attribute value \e {float-right} then will refer to
- a clause in the style.css file, which in this case could be:
-
- \code
- div.float-right
- {
- float: right; margin-left: 2em
- }
- \endcode
-
- If qdoc is generating DITA XML, it will translate the commands to:
-
- \code
- <sectiondiv outputclass="float-right">
- <p>
- <fig>
- <image href="images/qml-column.png" placement="inline"/>
- </fig>
- </p>
- </sectiondiv>
- \endcode
-
- Your DITA XML publishing program must then recognize the \e
- {outputclass} attribute value.
-
- \note Note that the \b {\\div} command can be nested.
-
- Below you can find an example taken from the index.qdoc file used to
- generate index.html for Qt 4.7:
-
- \code
- \div {class="indexbox guide"}
- \div {class="heading"}
- Qt Developer Guide
- \enddiv
- \div {class="indexboxcont indexboxbar"}
- \div {class="section indexIcon"} \emptyspan
- \enddiv
- \div {class="section"}
- Qt is a cross-platform application and UI
- framework. Using Qt, you can write web-enabled
- applications once and deploy them across desktop,
- mobile and embedded operating systems without
- rewriting the source code.
- \enddiv
- \div {class="section sectionlist"}
- \list
- \li \l{Getting Started}
- \li \l{Installation} {Installation}
- \li \l{how-to-learn-qt.html} {How to learn Qt}
- \li \l{tutorials.html} {Tutorials}
- \li \l{Qt Examples} {Examples}
- \li \l{qt4-7-intro.html} {What's new in Qt 4.7}
- \endlist
- \enddiv
- \enddiv
- \enddiv
- \endcode
-
- When all the class attribute values are defined as they are in the
- style.css file that is used for rendering the Qt documentation,
- the above example is rendered as:
-
- \div {class="indexbox guide"}
- \div {class="heading"}
- Qt Developer Guide
- \enddiv
- \div {class="indexboxcont indexboxbar"}
- \div {class="section indexIcon"} \emptyspan
- \enddiv
- \div {class="section"}
- Qt is a cross-platform application and UI
- framework. Using Qt, you can write web-enabled
- applications once and deploy them across desktop,
- mobile and embedded operating systems without
- rewriting the source code.
- \enddiv
- \div {class="section sectionlist"}
- \list
- \li Getting Started
- \li Installation
- \li How to learn Qt
- \li Tutorials
- \li Examples
- \li What's new in Qt 4.7
- \endlist
- \enddiv
- \enddiv
- \enddiv
-
- When generating DITA XML, qdoc outputs the nested \e {div} commands as:
-
- \code
- <sectiondiv outputclass="indexbox guide">
- <sectiondiv outputclass="heading">
- <p>Qt Developer Guide</p>
- </sectiondiv>
- <sectiondiv outputclass="indexboxcont indexboxbar">
- <sectiondiv outputclass="section indexIcon"/>
- <sectiondiv outputclass="section">
- <p>Qt is a cross-platform application and UI
- framework. Using Qt, you can write
- web-enabled applications once and deploy
- them across desktop, mobile and embedded
- operating systems without rewriting the
- source code.
- </p>
- </sectiondiv>
- <sectiondiv outputclass="section sectionlist">
- <ul>
- <li>
- <xref href="gettingstarted.xml#id-606ee7a8-219b-47b7-8f94-91bc8c76e54c">Getting started</xref>
- </li>
- <li>
- <xref href="installation.xml#id-075c20e2-aa1e-4f88-a316-a46517e50443">Installation</xref>
- </li>
- <li>
- <xref href="how-to-learn-qt.xml#id-49f509b5-52f9-4cd9-9921-74217b9a5182">How to learn Qt</xref>
- </li>
- <li>
- <xref href="tutorials.xml#id-a737f955-a904-455f-b4aa-0dc69ed5a64f">Tutorials</xref>
- </li>
- <li>
- <xref href="all-examples.xml#id-98d95159-d65b-4706-b08f-13d80080448d">Examples</xref>
- </li>
- <li>
- <xref href="qt4-7-intro.xml#id-519ae0e3-4242-4c2a-b2be-e05d1e95f177">What's new in Qt 4.7</xref>
- </li>
- </ul>
- </sectiondiv>
- </sectiondiv>
- </sectiondiv>
- \endcode
-
- Your DITA XML publishing program must recognize the values of the
- \e {outputclass} attribute.
-
- See also \l {span-command} {\\span}.
-
- \target span-command
- \section1 \\span
-
- The \\span command applies special formatting to a small block of text.
-
- Two arguments must be provided, each argument in curly braces, as
- shown in the QDoc comment below. The first argument is not
- interpreted, but specifies the formatting attribute(s) of the tag
- output by QDoc. The second argument is the text to be rendered with
- the special formatting attributes.
-
- For example, we might want to render the first word of each
- element in a numeric list in blue.
-
- \code
- / *!
- Global variables with complex types:
- \list 1
- \li \span {class="variableName"} {mutableComplex1} in globals.cpp at line 14
- \li \span {class="variableName"} {mutableComplex2} in globals.cpp at line 15
- \li \span {class="variableName"} {constComplex1} in globals.cpp at line 16
- \li \span {class="variableName"} {constComplex2} in globals.cpp at line 17
- \endlist
- * /
- \endcode
-
- Class \e {variableName} refers to a clause in your style.css.
-
- \code
- .variableName
- {
- font-family: courier;
- color: blue
- }
- \endcode
-
- Using the \e {variableName} clause shown above, the example is rendered as:
-
- Global variables with complex types:
- \list 1
- \li \span {class="variableName"} {mutableComplex1} in globals.cpp at line 14
- \li \span {class="variableName"} {mutableComplex2} in globals.cpp at line 15
- \li \span {class="variableName"} {constComplex1} in globals.cpp at line 16
- \li \span {class="variableName"} {constComplex2} in globals.cpp at line 17
- \endlist
-
- \note The \b span command does not cause a new paragraph to be
- started.
-
- See also \l {div-command} {\\div}.
-
- \target tt-command
- \section1 \\tt (teletype font)
-
- The \\tt command renders its argument in a monospace font. This
- command behaves just like the \l {c-command} {\\c} command, except
- that \\tt allows you to nest QDoc commands within the argument
- (e.g. \l {e-command} {\\e}, \l {b-command} {\\b} and \l
- {underline-command} {\\underline}).
-
- \code
- / *!
- After having populated the main container with
- child widgets, \c setupUi() scans the main container's list of
- slots for names with the form
- \tt{on_\e{objectName}_\e{signalName}().}
- * /
- \endcode
-
- QDoc renders this as:
-
- \quotation
- After having populated the main container with
- child widgets, \c setupUi() scans the main container's list of
- slots for names with the form
- \tt{on_\e{objectName}_\e{signalName}().}
- \endquotation
-
- If the text to be rendered in the code font contains spaces, enclose the
- entire text in curly brackets.
-
- \code
- \tt {QLineEdit::QLineEdit(const QString &contents, QWidget *parent) :QWidget(parent)}
- \endcode
-
- QDoc renders this as:
-
- \quotation
- \tt {QLineEdit::QLineEdit(const QString &contents, QWidget *parent) :QWidget(parent)}
- \endquotation
-
- See also \l {c-command} {\\c}.
-
- \target b-command
- \section1 \\b
-
- The \\b command renders its argument in bold font. This command used
- to be called \\bold.
-
- \code
- / *!
- This is regular text; \b {this text is
- rendered using the \\b command}.
- * /
- \endcode
-
- QDoc renders this as:
-
- \quotation
- This is regular text; \b {this text is rendered using
- the \\b command}.
- \endquotation
-
- \target e-command
- \section1 \\e (emphasis, italics) \span {class="newStuff"} {(new 5/3/2012)}
-
- The \\e command renders its argument in a special font, normally italics. This
- command used to be called \\i, which is now deprecated. Use \e for italics.
-
- If the argument contains spaces or other punctuation, enclose the
- argument in curly brackets.
-
- \code
- / *!
- Here, we render \e {a few words} in italics.
- * /
- \endcode
-
- QDoc renders this as:
-
- \quotation
- Here, we render \e {a few words} in italics.
- \endquotation
-
- If you want to use other QDoc commands within an argument that
- contains spaces, you always need to enclose the argument in
- braces. But QDoc is smart enough to count parentheses [3], so you
- don't need braces in cases like this:
-
- \code
- / *!
- An argument can sometimes contain whitespaces,
- for example: \e QPushButton(tr("A Brand New Button"))
- * /
- \endcode
-
- QDoc renders this as:
-
- \quotation
- An argument can sometimes contain whitespaces,
- for example: \e QPushButton(tr("A Brand New Button"))
- \endquotation
-
- Finally, trailing punctuation is not included in an argument [4],
- nor is "'s" [5]
-
- \raw HTML
- <table align="center" cellpadding="2"
- cellspacing="1" border="0">
- <tr valign="top" bgcolor="#a2c511">
- <th></th>
- <th>QDoc Syntax</th>
- <th>Generated Documentation</th>
- </tr>
-
- <tr valign="top" bgcolor="#d0d0d0">
- <td>1</td>
- <td>A variation of a command button is a \e menu
- button.</td>
- <td>A variation of a command button is a <i>menu</i>
- button.</td>
- </tr>
-
- <tr valign="top" bgcolor="#c0c0c0">
- <td>2</td>
- <td>The QPushButton widget provides a
- \e {command button}.</td>
- <td>The QPushButton widget provides a
- <i>command button</i>.</td>
- </tr>
-
- <tr valign="top" bgcolor="#d0d0d0">
- <td>3</td>
- <td>Another class of buttons are option buttons
- \e (see QRadioButton).</td>
- <td>Another class of buttons are option buttons
- <i> (see QRadioButton)</i>.</td>
- </tr>
-
- <tr valign="top" bgcolor="#c0c0c0">
- <td>4</td>
- <td>A push button emits the signal \e clicked().</td>
- <td>A push button emits the signal <i>clicked</i>().</td>
- </tr>
-
- <tr valign="top" bgcolor="#d0d0d0">
- <td>5</td>
- <td>The \e QPushButton's checked property is
- false by default.</td>
- <td>The <i>QPushButton</i>'s checked property is
- false by default.</td>
- </tr>
-
- </table>
- \endraw
-
- \target sub-command
- \section1 \\sub
-
- The \\sub command renders its argument lower than the baseline of
- the regular text, using a smaller font.
-
- \code
- / *!
- Definition (Range): Consider the sequence
- {x\sub n}\sub {n > 1} . The set
-
- {x\sub 2, x\sub 3, x\sub 4, ...} = {x\sub n ; n = 2, 3, 4, ...}
-
- is called the range of the sequence.
- * /
- \endcode
-
- QDoc renders this as:
-
- \quotation
- Definition (Range): Consider the sequence
- {x\sub n}\sub {n > 1} . The set
-
- {x\sub 2, x\sub 3, x\sub 4, ...} = {x\sub n ; n = 2, 3, 4, ...}
-
- is called the range of the sequence.
- \endquotation
-
- If the argument contains spaces or other punctuation, enclose the
- argument in curly brackets.
-
- \target sup-command
- \section1 \\sup
-
- The \\sup command renders its argument higher than
- the baseline of the regular text, using a smaller font.
-
- \code
- / *!
- The series
-
- 1 + a + a\sup 2 + a\sup 3 + a\sup 4 + ...
-
- is called the \i {geometric series}.
- * /
- \endcode
-
- QDoc renders this as:
-
- \quotation
- The series
-
- 1 + a + a\sup 2 + a\sup 3 + a\sup 4 + ...
-
- is called the \e {geometric series}.
- \endquotation
-
- If the argument contains spaces or other punctuation, enclose the
- argument in curly brackets.
-
- \target uicontrol-command
- \section1 \\uicontrol
-
- The \\uicontrol command is used to mark content as being used for UI
- control elements. When using HTML, the output is rendered in bold.
- When using DITA XML the content is enclosed in a \c{uicontrol} tag.
-
- \sa \\b
-
- \target underline-command
- \section1 \\underline
-
- The \\underline command renders its argument underlined.
-
- \code
- / *!
- The \underline {F}ile menu gives the users the possibility
- to edit an existing file, or save a new or modified
- file, and exit the application.
- * /
- \endcode
-
- QDoc renders this as:
-
- \quotation
- The \underline {F}ile menu gives the users the possibility
- to edit an existing file, or save a new or modified
- file, and exit the application.
- \endquotation
-
- If the argument contains spaces or other punctuation, enclose the
- argument in curly brackets.
-
- \target backslash-command
- \section1 \\\\ (double backslash)
-
- The \\\\ command expands to a double backslash.
-
- QDoc commands always start with a single backslash. To display a
- single backslash in the text you need to type two backslashes. If
- you want to display two backslashes, you need to type four.
-
- \code
- / *!
- The \\\\ command is useful if you want a
- backslash to appear verbatim, for example,
- writing C:\\windows\\home\\.
- * /
- \endcode
-
- QDoc renders this as:
-
- \quotation
- The \\\\ command is useful if you want a
- backslash to appear verbatim, for example,
- writing C:\\windows\\home\\.
- \endquotation
-
- However, if you want your text to appear in a monospace font as
- well, you can use the \l {c-command} {\\c} command instead, which
- accepts and renders the backslash as any other character. For
- example:
-
- \code
- / *!
- The \\c command is useful if you want a
- backslash to appear verbatim, and the word
- that contains it written in a monospace font,
- like this: \c {C:\windows\home\}.
- * /
- \endcode
-
- QDoc renders this as:
-
- \quotation
- The \\c command is useful if you want a
- backslash to appear verbatim, and the word
- that contains it written in a monospace font,
- like this: \c {C:\windows\home\}.
- \endquotation
-
-*/
-
-
-/*!
- \page 05-qdoc-commands-documentstructure.html
- \previouspage Text Markup
- \contentspage QDoc Manual
- \nextpage Including Code Inline
-
- \title Document Structure
-
- The document structuring commands are for dividing your document
- into sections. QDoc supports six kinds of sections: \c \part, \c
- \chapter, \c \section1, \c \section2, \c \section3, and \c
- \section4. The \c \section1..4 commands are the most useful. They
- correspond to the traditional section, subsection, etc used in
- outlining.
-
- \target part-command
- \section1 \\part
-
- The \\part command is intended for use in a large document, like a
- book.
-
- In general a document structuring command considers everything
- that follows it until the first line break as its argument. The
- argument is rendered as the unit's title. If the title needs to be
- spanned over several lines, make sure that each line (except the
- last one) is ended with a backslash.
-
- In total, there are six levels of sections in QDoc: \c \part, \c
- \chapter, \c \section1, \c \section2, \c \section3 and \c
- \section4. \c \section1 to \c \section4 correspond to the
- traditional section, subsection, subsubsection and
- subsubsubsection.
-
- There is a strict ordering of the section units:
-
- \code
- part
- |
- chapter
- |
- section1
- |
- section2
- |
- section3
- |
- section4
- \endcode
-
- For example, a \c section1 unit can only appear as the top level
- section or inside a \c chapter unit. Skipping a section unit, for
- example from \c part to \c section1, is not allowed.
-
- You can \e begin with either of the three: \c part, \c chapter or
- \c section1.
-
-
- \code
- / *!
- \part Basic Qt
-
- This is the first part.
-
-
- \chapter Getting Started
-
- This is the first part's first chapter.
-
-
- \section1 Hello Qt
-
- This is the first chapter's first section.
-
-
- \section1 Making Connections
-
- This is the first chapter's second section.
-
-
- \section1 Using the Reference Documentation
-
- This is the first chapter's third section.
-
-
- \chapter Creating Dialogs
-
- This is the first part's second chapter.
-
-
- \section1 Subclassing QDialog
-
- This is the second chapter's first section.
-
- ...
-
-
- \part Intermediate Qt
-
- This is the second part.
-
-
- \chapter Layout Management
-
- This is the second part's first chapter.
-
-
- \section1 Basic Layouts
-
- This is the first chapter's first section.
-
- ...
- * /
- \endcode
-
- QDoc renders this as:
-
- \quotation
- \raw HTML
- <a name="Basic Qt">
- <h1>Basic Qt</h1>
- </a>
- <p>This is the first part.</p>
-
- <a name="Getting started">
- <h2>Getting Started</h2>
- </a>
- This is the first part's first chapter.</p>
-
- <a name="Hello Qt">
- <h3>Hello Qt</h3>
- </a>
- <p>This is the first chapter's first section.</p>
-
- <a name="Making Connections">
- <h3>Making Connections</h3>
- </a>
- <p>This is the first chapter's second section.</p>
-
- <a name="Using the Reference Documentation">
- <h3>Using the Reference Documentation</h3>
- </a>
- <p>This is the first chapter's third section.</p>
-
- <a name="Creating Dialogs">
- <h2>Creating Dialogs</h2>
- </a>
- <p>This is the first part's second chapter.</p>
-
- <a name="Subclassing QDialog">
- <h3>Subclassing QDialog</h3>
- </a>
- <p>This is the second chapter's first section.</p>
-
- ...
-
- <a name="Intermediate Qt">
- <h1>Intermediate Qt</h1>
- </a>
- <p>This is the second part.</p>
-
- <a name="Layout Management">
- <h2>Layout Management</h2>
- </a>
- <p>This is the second part's first chapter.</p>
-
- <a name="Basic Layouts">
- <h3>Basic Layouts</h3>
- </a>
- <p>This is the first chapter's first section.</p>
-
- ...
-
- \endraw
- \endquotation
-
- Each section is a logical unit in the document. The section
- heading appears in the automatically generated table of contents
- that normally appears in the upper right-hand corner of the page.
-
- \target chapter-command
- \section1 \\chapter
-
- The \\chapter command is intended for use in
- larger documents, and divides the document into chapters.
-
- See \l{part} {\\part} for an explanation of the various
- section units, command argument, and rendering.
-
- \target sectionOne-command
- \section1 \\section1
-
- The \\section1 command starts a new section.
-
- See \l{part} {\\part} for an explanation of the various
- section units, command argument, and rendering.
-
- \target sectionTwo-command
- \section1 \\section2
-
- The \\section2 command starts a new section.
-
- See \l{part} {\\part} for an explanation of the various
- section units, command argument, and rendering.
-
- \target sectionThree-command
- \section1 \\section3
-
- The \\section3 command starts a new section.
-
- See \l{part} {\\part} for an explanation of the various
- section units, command argument, and rendering.
-
- \target sectionFour-command
- \section1 \\section4
-
- The \\section4 command starts a new section.
-
- See \l{part} {\\part} for an explanation of the various
- section units, command argument, and rendering.
-
-*/
-
-
-/*!
- \page 06-qdoc-commands-includecodeinline.html
- \previouspage Document Structure
- \contentspage QDoc Manual
- \nextpage Including External Code
-
- \title Including Code Inline
-
- The following commands are used to render source code without
- formatting. The source code begins on a new line, rendered in the
- code.
-
- \b{Note:} Although all these commands are for rendering C++
- code, the
- \l{07-0-qdoc-commands-includingexternalcode.html#snippet-command}
- {\\snippet} and
- \l{07-0-qdoc-commands-includingexternalcode.html#codeline-command}
- {\\codeline} commands are preferred over the others. These
- commands allow equivalent code snippets for other Qt language
- bindings to be substituted for the C++ snippets in the
- documentation.
-
- \target code-command
- \section1 \\code
-
- The \\code and \\endcode commands enclose a snippet of source code.
-
- \note The \l {c-command} {\\c} command can be used for short code
- fragments within a sentence. The \\code command is for longer code
- snippets. It renders the code verbatim in a separate paragraph in
- the code font.
-
- When processing any of the \\code, \l {newcode-command} {\\newcode} or \l
- {oldcode-command} {\\oldcode} commands, QDoc removes all
- indentation that is common for the verbatim code blocks within a
- \c{/}\c{*!} ... \c{*}\c{/} comment before it adds the standard
- indentation. For that reason the recommended style is to use 8
- spaces for the verbatim code contained within these commands
-
- \note This doesn't apply to externally quoted code using the \l
- {quotefromfile-command} {\\quotefromfile} or \l
- {quotefile-command} {\\quotefile} command.
-
- \code
- / *!
- \code
- #include <QApplication>
- #include <QPushButton>
-
- int main(int argc, char *argv[])
- {
- ...
- }
- \ endcode
- * /
- \endcode
-
- QDoc renders this as:
-
- \code
- #include <QApplication>
- #include <QPushButton>
-
- int main(int argc, char *argv[])
- {
- ...
- }
- \endcode
-
- Other QDoc commands are disabled within \\code... \\endcode, and
- the special character '\\' is accepted and rendered like the rest
- of the code.
-
- To include code snippets from an external file, use the
- \l{07-0-qdoc-commands-includingexternalcode.html#snippet-command}
- {\\snippet} and
- \l{07-0-qdoc-commands-includingexternalcode.html#codeline-command}
- {\\codeline} commands.
-
- See also \l {c-command} {\\c}, \l
- {07-0-qdoc-commands-includingexternalcode.html#quotefromfile-command}
- {\\quotefromfile}, \l{newcode-command} {\\newcode}, and \l {oldcode-command}
- {\\oldcode}.
-
- \target newcode-command
- \section1 \\newcode
-
- The \\newcode, \\oldcode, and \\endcode commands enable you to
- show how to port a snippet of code to a new version of an API.
-
- The \\newcode command and its companion the \\oldcode command are
- a convenience combination of the \l {code-command} {\\code} commands:
- this combination provides a text relating the two code snippets to each
- other.
-
- The \\newcode command requires a preceding \\oldcode statement.
-
- Like the \l{code-command}{\\code} command, the \\newcode command renders its
- code on a new line in the documentation using a monospace font and the
- standard indentation.
-
- \code
- / *!
- \oldcode
- if (printer->setup(parent))
- ...
- \newcode
- QPrintDialog dialog(printer, parent);
- if (dialog.exec())
- ...
- \ endcode
- * /
- \endcode
-
- QDoc renders this as:
-
- \quotation
- \oldcode
- if (printer->setup(parent))
- ...
- \newcode
- QPrintDialog dialog(printer, parent);
- if (dialog.exec())
- ...
- \endcode
- \endquotation
-
- Other QDoc commands are disabled within \\oldcode ... \\endcode,
- and the '\\' character doesn't need to be escaped.
-
- \target oldcode-command
- \section1 \\oldcode
-
- The \\oldcode command requires a corresponding
- \\newcode statement; otherwise QDoc fails to parse the command
- and emits a warning.
-
- See also \l {newcode-command} {\\newcode}.
-
- \target qml-command
- \section1 \\qml
-
- The \\qml and \\endqml commands enclose a snippet of QML source
- code. Currently, QDoc handles \\qml and \\endqml in exactly the same
- way as \\code and \\endcode.
-
- \code
- / *!
- \qml
- import QtQuick 1.0
-
- Row {
- Rectangle {
- width: 100; height: 100
- color: "blue"
- transform: Translate { y: 20 }
- }
- Rectangle {
- width: 100; height: 100
- color: "red"
- transform: Translate { y: -20 }
- }
- }
- \endqml
- * /
- \endcode
-
- QDoc renders this as:
-
- \qml
- import QtQuick 1.0
-
- Row {
- Rectangle {
- width: 100; height: 100
- color: "blue"
- transform: Translate { y: 20 }
- }
- Rectangle {
- width: 100; height: 100
- color: "red"
- transform: Translate { y: -20 }
- }
- }
- \endqml
-*/
-
-
-/*!
- \page 07-0-qdoc-commands-includingexternalcode.html
- \previouspage Including Code Inline
- \contentspage QDoc Manual
- \nextpage Creating Links
-
- \title Including External Code
-
- The following commands enable you to include code snippets from
- external files. You can make QDoc include the complete contents of
- a file, or you can quote specific parts of the file and skip
- others. The typical use of the latter is to quote a file chunk by
- chunk.
-
- \b{Note:} Although all these commands are for rendering C++
- code, the
- \l{07-0-qdoc-commands-includingexternalcode.html#snippet-command}
- {\\snippet} and
- \l{07-0-qdoc-commands-includingexternalcode.html#codeline-command}
- {\\codeline} commands are preferred over the others. These
- commands allow equivalent code snippets for other Qt language
- bindings to be substituted for the C++ snippets in the
- documentation.
-
- \target quotefile-command
- \section1 \\quotefile
-
- The \\quotefile command expands to the complete contents of the
- file given as argument.
-
- The command considers the rest of the line as part of its
- argument, make sure to follow the file name with a line break.
-
- The file's contents is rendered in a separate paragraph, using a
- monospace font and the standard indentation. The code is shown
- verbatim.
-
- \code
- / *!
- This is a simple "Hello world" example:
-
- \quotefile examples/main.cpp
-
- It contains only the bare minimum you need
- to get a Qt application up and running.
- * /
- \endcode
-
- QDoc renders this as:
-
- \quotation
- This is a simple "Hello world" example:
-
- \quotefile examples/main.cpp
-
- It contains only the bare minimum you need to get a Qt
- application up and running.
- \endquotation
-
- See also \l {quotefromfile-command} {\\quotefromfile} and
- \l {code-command} {\\code}.
-
-
- \target quotefromfile-command
- \section1 \\quotefromfile
-
- The \\quotefromfile command opens the file given as argument for
- quoting.
-
- The command considers the rest of the line as part of its
- argument, make sure to follow the file name with a line break.
-
- The command is intended for use when quoting parts from file with
- the walkthrough commands: \l {printline-command} {\\printline}, \l
- {printto-command} {\\printto}, \l {printuntil-command}
- {\\printuntil}, \l {skipline-command} {\\skipline}, \l
- {skipto-command} {\\skipto}, \l {skipuntil-command}
- {\\skipuntil}. This enables you to quote specific portions of a
- file.
-
- \code
- / *!
- The whole application is contained within
- the \c main() function:
-
- \quotefromfile examples/main.cpp
-
- \skipto main
- \printuntil app(argc, argv)
-
- First we create a QApplication object using
- the \c argc and \c argv parameters.
-
- \skipto QPushButton
- \printuntil resize
-
- Then we create a QPushButton, and give it a reasonable
- size using the QWidget::resize() function.
-
- ...
- * /
- \endcode
-
- QDoc renders this as:
-
- \quotation
- The whole application is contained within
- the \c main() function:
-
- \quotefromfile examples/main.cpp
-
- \skipto main
- \printuntil app(argc, argv)
-
- First we create a QApplication object using the \c argc
- and \c argv parameters.
-
- \skipto QPushButton
- \printuntil resize
-
- Then we create a QPushButton, and give it a reasonable
- size using the QWidget::resize() function.
-
- ...
- \endquotation
-
- QDoc remembers which file it is quoting from, and the current
- position in that file (see \l {file} {\\printline} for more
- information). There is no need to "close" the file.
-
- See also \l {quotefile-command} {\\quotefile}, \l {code-command}
- {\\code} and \l {dots} {\\dots}.
-
- \target printline-command
- \section1 \\printline
-
- The \\printline command expands to the line from the current
- position to the next non-blank line of the current source file.
-
- To ensure that the documentation remains synchronized with the
- source file, a substring of the line must be specified as an
- argument to the command. Note that the command considers the rest
- of the line as part of its argument, make sure to follow the
- substring with a line break.
-
- The line from the source file is rendered as a separate paragraph,
- using a monospace font and the standard indentation. The code is
- shown verbatim.
-
- \code
- / *!
- There has to be exactly one QApplication object
- in every GUI application that uses Qt.
-
- \quotefromfile examples/main.cpp
-
- \printline QApplication
-
- This line includes the QApplication class
- definition. QApplication manages various
- application-wide resources, such as the
- default font and cursor.
-
- \printline QPushButton
-
- This line includes the QPushButton class
- definition. The QPushButton widget provides a command
- button.
-
- \printline main
-
- The main function...
- * /
- \endcode
-
- QDoc renders this as:
-
- \quotation
- There has to be exactly one QApplication object
- in every GUI application that uses Qt.
-
- \quotefromfile examples/main.cpp
-
- \skipto QApplication
- \printline QApplication
-
- This line includes the QApplication class
- definition. QApplication manages various
- application-wide resources, such as the
- default font and cursor.
-
- \printline QPushButton
-
- This line includes the QPushButton class
- definition. The QPushButton widget provides a command
- button.
-
- \printline main
-
- The main function...
- \endquotation
-
- \target file
-
- QDoc reads the file sequentially. To move the current position
- forward you can use either of the \l {skipline-command}
- {\\skip...} commands. To move the current position backward, you
- can use the \l {quotefromfile-command} {\\quotefromfile} command
- again.
-
- \target substring
-
- If the substring argument is surrounded by slashes it is
- interpreted as a \l {QRegExp}{regular expression}.
-
- \code
- / *!
- \quotefromfile examples/mainwindow.cpp
-
- \skipto closeEvent
- \printuntil /^\}/
-
- Close events are sent to widgets that the users want to
- close, usually by clicking \c File|Exit or by clicking
- the \c X title bar button. By reimplementing the event
- handler, we can intercept attempts to close the
- application.
- * /
- \endcode
-
- QDoc renders this as:
-
- \quotation
- \quotefromfile examples/mainwindow.cpp
-
- \skipto closeEvent
- \printuntil /^\}/
-
- Close events are sent to widgets that the users want to
- close, usually by clicking \c File|Exit or by clicking
- the \c X title bar button. By reimplementing the event
- handler, we can intercept attempts to close the
- application.
- \endquotation
-
- (\l {widgets/scribble} {The complete example file...})
-
- The regular expression \c /^\}/ makes QDoc print until the first
- '}' character occurring at the beginning of the line without
- indentation. /.../ encloses the regular expression, and '^' means
- the beginning of the line. The '}' character must be escaped since
- it is a special character in regular expressions.
-
- QDoc will emit a warning if the specified substring or regular
- expression cannot be located, i.e. if the source code has changed.
-
- See also \l {printto-command} {\\printto} and \l
- {printuntil-command} {\\printuntil}.
-
- \target printto-command
- \section1 \\printto
-
- The \\printto command expands to all the lines from the current
- position up to and \e excluding the next line containing a given
- substring.
-
- The command considers the rest of the line as part of its
- argument, make sure to follow the substring with a line break. The
- command also follows the same conventions for \l {file}
- {positioning} and \l {substring} {argument} as the \l
- {printline-command} {\\printline} command.
-
- The lines from the source file are rendered in a separate
- paragraph, using a monospace font and the standard
- indentation. The code is shown verbatim.
-
- \code
- / *!
- The whole application is contained within the
- \c main() function:
-
- \quotefromfile examples/main.cpp
- \printto hello
-
- First we create a QApplication object using the \c argc and
- \c argv parameters...
- * /
- \endcode
-
- QDoc renders this as:
-
- \quotation
- The whole application is contained within the
- \c main() function:
-
- \quotefromfile examples/main.cpp
- \skipto main
- \printto hello
-
- First we create a QApplication object using the \c argc
- and \c argv parameters...
- \endquotation
-
- See also \l {printline-command} {\\printline} and \l
- {printuntil-command} {\\printuntil}.
-
- \target printuntil-command
- \section1 \\printuntil
-
- The \\printuntil command expands to all the lines from the current
- position up to and \e including the next line containing a given
- substring.
-
- The command considers the rest of the line as part of its
- argument, make sure to follow the substring with a line break. The
- command also follows the same conventions for \l {file}
- {positioning} and \l {substring} {argument} as the \l
- {printline-command} {\\printline} command.
-
- The lines from the source file are rendered in a separate
- paragraph, using a monospace font and the standard
- indentation. The code is shown verbatim.
-
- \code
- / *!
- The whole application is contained within the
- \c main() function:
-
- \quotefromfile examples/main.cpp
- \skipto main
- \printuntil hello
-
- First we create a QApplication object using the
- \c argc and \c argv parameters, then we create
- a QPushButton.
- * /
- \endcode
-
- QDoc renders this as:
-
- \quotation
- The whole application is contained within the
- \c main() function:
-
- \quotefromfile examples/main.cpp
- \skipto main
- \printuntil hello
-
- First we create a \l
- {http://doc.qt.io/qt-5/qapplication.html} {QApplication}
- object using the \c argc and \c argv parameters, then we
- create a \l
- {http://doc.qt.io/qt-5/qpushbutton.html} {QPushButton}.
- \endquotation
-
- See also \l {printline-command} {\\printline} and \l
- {printto-command} {\\printto}.
-
- \target skipline-command
- \section1 \\skipline
-
- The \\skipline command ignores the next non-blank line in the
- current source file.
-
- Doc reads the file sequentially, and the \\skipline command is
- used to move the current position (omitting a line of the source
- file). See the remark about \l {file} {file positioning} above.
-
- The command considers the rest of the line as part of its
- argument, make sure to follow the substring with a line break. The
- command also follows the same conventions for \l {substring}
- {argument} as the \l {printline-command} {\\printline} command,
- and it is used in conjunction with the \l {quotefromfile-command}
- {\\quotefromfile} command.
-
- \code
- / *!
- QPushButton is a GUI push button that the user
- can press and release.
-
- \quotefromfile examples/main.cpp
- \skipline QApplication
- \printline QPushButton
-
- This line includes the QPushButton class
- definition. For each class that is part of the
- public Qt API, there exists a header file of
- the same name that contains its definition.
- * /
- \endcode
-
- QDoc renders this as:
-
- \quotation
- \l
- QPushButton is a GUI push button that the user
- can press and release.
-
- \quotefromfile examples/main.cpp
- \skipto QApplication
- \skipline QApplication
- \printline QPushButton
-
- This line includes the QPushButton class
- definition. For each class that is part of the public
- Qt API, there exists a header file of the same name
- that contains its definition.
- \endquotation
-
- See also \l {skipto-command} {\\skipto}, \l {skipuntil-command}
- {\\skipuntil} and \l {dots} {\\dots}.
-
- \target skipto-command
- \section1 \\skipto
-
- The \\skipto command ignores all the lines from the current
- position up to and \e excluding the next line containing a given
- substring.
-
- QDoc reads the file sequentially, and the \\skipto command is used
- to move the current position (omitting one or several lines of the
- source file). See the remark about \l {file} {file positioning}
- above.
-
- The command considers the rest of the line as part of its
- argument, make sure to follow the substring with a line break.
-
- The command also follows the same conventions for \l {substring}
- {argument} as the \l {printline-command} {\\printline} command,
- and it is used in conjunction with the \l {quotefromfile-command}
- {\\quotefromfile} command.
-
- \code
- / *!
- The whole application is contained within
- the \c main() function:
-
- \quotefromfile examples/main.cpp
- \skipto main
- \printuntil }
-
- First we create a QApplication object. There
- has to be exactly one such object in
- every GUI application that uses Qt. Then
- we create a QPushButton, resize it to a reasonable
- size...
- * /
- \endcode
-
- QDoc renders this as:
-
- \quotation
- The whole application is contained within
- the \c main() function:
-
- \quotefromfile examples/main.cpp
- \skipto main
- \printuntil }
-
- First we create a QApplication object. There has to be
- exactly one such object in every GUI application that
- uses Qt. Then we create a QPushButton, resize it to a
- reasonable size ...
- \endquotation
-
- See also \l {skipline-command} {\\skipline}, \l
- {skipuntil-command} {\\skipuntil} and \l {dots} {\\dots}.
-
- \target skipuntil-command
- \section1 \\skipuntil
-
- The \\skipuntil command ignores all the lines from the current
- position up to and \e including the next line containing a given
- substring.
-
- QDoc reads the file sequentially, and the \\skipuntil command is
- used to move the current position (omitting one or several lines
- of the source file). See the remark about \l {file} {file
- positioning} above.
-
- The command considers the rest of the line as part of its
- argument, make sure to follow the substring with a line break.
-
- The command also follows the same conventions for \l {substring}
- {argument} as the \l {printline-command} {\\printline} command,
- and it is used in conjunction with the \l {quotefromfile-command}
- {\\quotefromfile} command.
-
- \code
- / *!
- The first thing we did in the \c main() function
- was to create a QApplication object \c app.
-
- \quotefromfile examples/main.cpp
- \skipuntil show
- \dots
- \printuntil }
-
- In the end we must remember to make \c main() pass the
- control to Qt. QCoreApplication::exec() will return when
- the application exits...
- * /
- \endcode
-
- QDoc renders this as:
-
- \quotation
- The first thing we did in the \c main() function was to
- create a QApplication object \c app.
-
- \quotefromfile examples/main.cpp
- \skipuntil show
- \dots
- \printuntil }
-
- In the end we must remember to make \c main() pass the
- control to Qt. QCoreApplication::exec()
- will return when the application exits...
- \endquotation
-
- See also \l {skipline-command} {\\skipline}, \l {skipto-command}
- {\\skipto} and \l {dots} {\\dots}.
-
- \target dots-command
- \section1 \\dots
-
- The \\dots command indicates that parts of the source file have
- been omitted when quoting a file.
-
- The command is used in conjunction with the \l
- {quotefromfile-command} {\\quotefromfile} command, and should be
- stated on its own line. The dots are rendered on a new line, using
- a monospace font.
-
- \code
- / *!
- \quotefromfile examples/main.cpp
- \skipto main
- \printuntil {
- \dots
- \skipuntil exec
- \printline }
- * /
- \endcode
-
- QDoc renders this as:
-
- \quotefromfile examples/main.cpp
- \skipto main
- \printuntil {
- \dots
- \skipuntil exec
- \printline }
-
- The default indentation is 4 spaces, but this can be adjusted
- using the command's optional argument.
-
- \code
- / *!
- \dots 0
- \dots
- \dots 8
- \dots 12
- \dots 16
- * /
- \endcode
-
- QDoc renders this as:
-
- \dots 0
- \dots
- \dots 8
- \dots 12
- \dots 16
-
- See also \l {skipline-command} {\\skipline}, \l {skipto-command}
- {\\skipto} and \l {skipuntil-command} {\\skipuntil}.
-
- \target snippet-command
- \section1 \\snippet
-
- The \\snippet command causes a code snippet to be included
- verbatim as preformatted text, which may be syntax highlighted.
-
- Each code snippet is referenced by the file that holds it and by
- a unique identifier for that file. Snippet files are typically
- stored in a \c{snippets} directory inside the documentation
- directory (for example, \c{$QTDIR/doc/src/snippets}).
-
- For example, the following documentation references a snippet in a
- file residing in a subdirectory of the documentation directory:
-
- \code
- \snippet snippets/textdocument-resources/main.cpp Adding a resource
- \endcode
-
- The text following the file name is the unique identifier for the
- snippet. This is used to delimit the quoted code in the relevant
- snippet file, as shown in the following example that corresponds to
- the above \c{\\snippet} command:
-
- \dots
- \code
- QImage image(64, 64, QImage::Format_RGB32);
- image.fill(qRgb(255, 160, 128));
-
- //! [Adding a resource]
- document->addResource(QTextDocument::ImageResource,
- QUrl("mydata://image.png"), QVariant(image));
- //! [Adding a resource]
- \endcode
- \dots
-
- \target codeline-command
- \section1 \\codeline
-
- The \\codeline command inserts a blank line of preformatted
- text. It is used to insert gaps between snippets without closing
- the current preformatted text area and opening a new one.
-
-*/
-
-
-/*!
- \page 08-qdoc-commands-creatinglinks.html
- \previouspage Including External Code
- \contentspage QDoc Manual
- \nextpage Including Images
-
- \title Creating Links
-
- These commands are for creating hyperlinks to classes, functions,
- examples, and other targets.
-
- \target l-command
- \section1 \\l (link)
-
- The \\l link command is used to create a hyperlink to many
- different kinds of targets. The command's general syntax is:
-
- \code
- \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://doc.qt.io/qt-5/}
- {Qt 5.0 Documentation} carefully.
- * /
- \endcode
-
- QDoc renders this as:
-
- \quotation
- Read the \l {http://doc.qt.io/qt-5/}
- {Qt 5.0 Documentation} carefully.
- \endquotation
-
- If the link target is equivalent to the link text, the second
- argument can be omitted.
-
- For example, if you have documentation like:
-
- \code
- / *!
- \target assertions
-
- Assertions make some statement about the text at the
- point where they occur in the regexp, but they do not
- match any characters.
-
- ...
-
- Regexps are built up from expressions, quantifiers, and
- \l {assertions} {assertions}.
- * /
- \endcode
-
- You can simplify this as follows:
-
- \code
- / *!
- \target assertions
-
- Assertions make some statement about the text at the
- point where they occur in the regexp, but they do not
- match any characters.
-
- ...
-
- Regexps are built up from expressions, quantifiers, and
- \l assertions.
- * /
- \endcode
-
- For the one-parameter version, the braces can often be omitted.
- The \\l command supports several ways of linking:
-
- \list
-
- \li \c {\l QWidget} - The name of a class documented with the \l
- {class-command} {\\class} command.
-
- \li \c {\l QWidget::sizeHint()} - The signature of a function without
- parameters. If a matching function without parameters can't be found,
- the link is satisfied with the first matching function found.
-
- \li \c {\l QWidget::removeAction(QAction* action)} - The signature
- of a function with parameters. If an exact match is not found, the
- link is not satisfied and qdoc reports a \e {Can't link to...} error.
-
- \li \c {\l <QtGlobal>} - The subject of a \l {headerfile-command}
- {\\headerfile} command.
-
- \li \c {\l widgets/wiggly} - The relative path used in an \l
- {example-command} {\\example} command.
-
- \li \c {\l {QWidget Class Reference}} - The title used in a
- \l {title-command} {\\title} command.
-
- \li \c {\l {Introduction to QDoc}}- The text from one of the
- \l{part-command} {\\part}, \l{chapter} {\\chapter}, or \l
- {sectionOne-command} {\\section} commands.
-
- \li \c {\l fontmatching} - The argument of a \l {target-command}
- {\\target} command.
-
- \li \c {\l {Shared Classes}} - A keyword named in a \l
- {keyword-command} {\\keyword} command.
-
- \li \c {\l http://qt-project.org/} - A URL.
-
- \endlist
-
- QDoc also tries to make a link out of any word that doesn't
- resemble a normal English word, for example, Qt class names or
- functions, like QWidget or QWidget::sizeHint(). In these cases,
- the \\l command can actually be omitted, but by using the command,
- you ensure that QDoc will emit a warning if it cannot find the
- link target. In addition, if you only want the function name to
- appear in the link, you can use the following syntax:
-
- \list
- \li \c {\l {QWidget::} {sizeHint()}}
- \endlist
-
- QDoc renders this as:
-
- \quotation
- \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}.
-
-
- \target sa-command
- \section1 \\sa (see also)
-
- The \\sa command defines a list of links that will be rendered in
- a separate "See also" section at the bottom of the documentation
- unit.
-
- The command takes a comma-separated list of links as its
- argument. If the line ends with a comma, you can continue
- the list on the next line. The general syntax is:
-
- \code
- \sa {the first link}, {the second link},
- {the third link}, ...
- \endcode
-
- QDoc will automatically try to generate "See also" links
- interconnecting a property's various functions. For example, a
- setVisible() function will automatically get a link to visible()
- and vice versa.
-
- In general, QDoc will generate "See also" links that interconnect
- the functions that access the same property. It recognizes four
- different syntax versions:
-
- \list
- \li \c property()
- \li \c setProperty()
- \li \c isProperty()
- \li \c hasProperty()
- \endlist
-
- The \\sa command supports the same kind of links as the \l
- {l-command} {\\l} command.
-
- \code
- / *!
- Appends the actions \a actions to this widget's
- list of actions.
-
- \sa removeAction(), QMenu, addAction()
- * /
- void QWidget::addActions(QList<QAction *> actions)
- {
- ...
- }
- \endcode
-
- QDoc renders this as:
-
- \quotation
- \b {void QWidget::addActions ( QList<QAction*>
- \e actions )}
-
- Appends the actions \e actions to this widget's list of
- actions.
-
- See also \l {QWidget::removeAction()} {removeAction()},
- \l QMenu, and \l {QWidget::addAction()} {addAction()}.
- \endquotation
-
- See also \l {l-command} {\\l}, \l {target-command} {\\target} and
- \l {keyword-command} {\\keyword}.
-
-
- \target target-command
- \section1 \\target
-
- The \\target command names a place in the documentation that you
- can link to using the \l {l-command} {\\l (link)} and \l
- {sa-command} {\\sa (see also)} commands.
-
- The text up to the line break becomes the target name. Be sure to
- follow the target name with a line break. Curly brackets are not
- required around the target name, but they may be required when the
- target name is used in a link command. See below.
-
- \code
- / *!
- \target capturing parentheses
- \section1 Capturing Text
-
- Parentheses allow us to group elements together so that
- we can quantify and capture them.
-
- ...
- * /
- \endcode
-
- The target name \e{capturing parentheses} can be linked from
- within the same document containing the target in the following way:
-
- \list
- \li \c {\l {capturing parentheses}} (from within the same QDoc comment)
- \endlist
-
- \note The brackets in the link example are required because the
- target name contains spaces.
-
- See also \l {l-command} {\\l}, \l {sa-command} {\\sa} and \l
- {keyword-command} {\\keyword}.
-
- \target keyword-command
- \section1 \\keyword
-
- The \\keyword command names a place in the documentation that you
- can link to using the \l {l-command} {\\l (link)} and \l
- {sa-command} {\\sa (see also)} commands.
-
- The \\keyword command is like the \l {target-command} {\\target}
- command, except when linking to keyword the link goes to the top of
- the QDoc comment where the \\keyword appears in. If you want to
- create a link target to a \c section unit within a \\page, use
- \\target instead. A keyword can be linked from anywhere using a
- simple syntax.
-
- Keywords must be unique over all the documents processed during
- the QDoc run. The command uses the rest of the line as its
- argument. Be sure to follow the keyword with a line break.
-
-
- \code
- / *!
- \class QRegExp
- \reentrant
- \brief The QRegExp class provides pattern
- matching using regular expressions.
- \ingroup tools
- \ingroup misc
- \ingroup shared
-
- \keyword regular expression
-
- Regular expressions, or "regexps", provide a way to
- find patterns within text.
-
- ...
- * /
- \endcode
-
- The location marked with the keyword can be linked to with:
-
- \code
- / *!
- When a string is surrounded by slashes, it is
- interpreted as a \l {QRegExp}{regular expression}.
- * /
- \endcode
-
- QDoc renders this as:
-
- \quotation
- When a string is surrounded by slashes, it is
- interpreted as a \l {regular expression}.
- \endquotation
-
- If the keyword text contains spaces, the brackets are required.
-
- See also \l {l-command} {\\l (link)}, \l {sa-command} {\\sa (see
- also)} and \l {target-command} {\\target}.
-
-*/
-
-
-/*!
- \page 09-qdoc-commands-includingimages.html
- \previouspage Creating Links
- \contentspage QDoc Manual
- \nextpage Tables and Lists
-
- \title Including Images
-
- The graphic commands makes it possible to include images in the
- documentation. The images can be rendered as separate paragraphs,
- or within running text.
-
- \target image-command
- \section1 \\image
-
- The \\image command expands to the image specified by its first
- argument, and renders it centered as a separate paragraph.
-
- The command takes two arguments. The first argument is the name of
- the image file. The second argument is optional and is a simple
- description of the image, equivalent to the HTML alt="" in an image
- tag. The description is used for tooltips and for browsers that don't
- support images, like the Lynx text browser.
-
- The remaining text \e{after} the file name is the optional,
- description argument. Be sure to follow the file name or the
- description with a line break. Curly brackets are required if the
- description argument spans multiple lines.
-
- \code
- / *!
- Qt is a C++ toolkit for cross-platform GUI application development.
-
- \image happyguy.jpg "Happy guy"
-
- Qt provides single-source portability across Microsoft
- Windows, OS X, Linux, and all major commercial Unix
- variants. It is also available for embedded devices.
- * /
- \endcode
-
- QDoc renders this as:
-
- \quotation
- Qt is a C++ toolkit for cross-platform GUI application development.
-
- \image happyguy.jpg image "Happy guy"
-
- Qt provides single-source portability across Microsoft
- Windows, OS X, Linux, and all major commercial Unix
- variants. It is also available for embedded devices.
- \endquotation
-
- See also \l {inlineimage-command} {\\inlineimage} and \l
- {caption-command} {\\caption}.
-
- \target inlineimage-command
- \section1 \\inlineimage
-
- The \\inlineimage command expands to the image specified by its
- argument. The image is rendered inline with the rest of the text.
-
- The command takes two arguments. The first argument is the name of
- the image file. The second argument is optional and is a simple
- description of the image, equivalent to the HTML alt="" in an image
- tag. The description is used for tooltips, and for when a browser
- doesn't support images, like the Lynx text browser.
-
- The most common use of the \\inlineimage command is in lists and
- tables. Here is an example of including inline images in a list:
-
- \code
- / *!
- \list 1
- \li \inlineimage happy.gif Oh so happy!
- \li \inlineimage happy.gif Oh so happy!
- \li \inlineimage happy.gif Oh so happy!
- \endlist
- * /
- \endcode
-
- QDoc renders this as:
-
- \list 1
- \li \inlineimage happy.gif Oh so happy!
- \li \inlineimage happy.gif Oh so happy!
- \li \inlineimage happy.gif Oh so happy!
- \endlist
-
- Here is an example of including inline images in a table:
-
- \code
- / *!
- \table
- \header
- \li Qt
- \li Qt Creator
- \row
- \li \inlineimage happy.gif Oh so happy!
- \li \inlineimage happy.gif Oh so happy!
- \row
- \li \inlineimage happy.gif Oh so happy!
- \li \inlineimage happy.gif Oh so happy!
- \endtable
- * /
- \endcode
-
- QDoc renders this as:
-
- \raw HTML
- <table align="center" cellpadding="2"
- cellspacing="1" border="0">
- <tr valign="top" bgcolor="#a2c511">
- <th>Qt</th>
- <th>Qt Creator</th>
- </tr>
- <tr valign="top" bgcolor="#f0f0f0">
- <td><img src="images/happy.gif" alt="Oh so happy!" />
- </td>
- <td><img src="images/happy.gif" alt="Oh so happy!" />
- </td>
- </tr>
- <tr valign="top" bgcolor="#f0f0f0">
- <td><img src="images/happy.gif" alt="Oh so happy!"/>
- </td>
- <td><img src="images/happy.gif" alt="Oh so happy!" />
- </td>
- </tr>
- </table>
- \endraw
-
- The command can also be used to insert an image inline with the
- text.
-
- \code
- / *!
- \inlineimage training.jpg Qt Training
- The Qt Programming course is offered as a
- five day Open Enrollment Course. The classes
- are open to the public. Although the course is open
- to anyone who wants to learn, attendees should
- have significant experience in C++ development
- to derive maximum benefit from the course.
- * /
- \endcode
-
- QDoc renders this as:
-
- \quotation
- \inlineimage training.jpg Qt Training
- The Qt Programming course is offered as a
- five day Open Enrollment Course. The classes
- are open to the public. Although the course is open
- to anyone who wants to learn, attendees should
- have significant experience in C++ development
- to derive maximum benefit from the course.
- \endquotation
-
- See also \l {image-command} {\\image} and \l {caption-command} {\\caption}.
-
- \target caption-command
- \section1 \\caption
-
- The \\caption command provides a caption for an image.
-
- The command takes all the text up to the end of the paragraph to
- be the caption. Experiment until you get the effect you want.
-
- \code
- / *!
- \table 100%
- \row
- \li \image windowsvista-pushbutton.png
- \caption The QPushButton widget provides a command button.
- \li \image windowsvista-toolbutton.png
- \caption The QToolButton class provides a quick-access button to commands
- or options, usually used inside a QToolBar.
- \endtable
- * /
- \endcode
-
- QDoc renders this as:
-
- \table 100%
- \row
- \li \image windowsvista-pushbutton.png
- \caption The QPushButton widget provides a command button.
- \li \image windowsvista-toolbutton.png
- \caption The QToolButton class provides a quick-access button to commands
- or options, usually used inside a QToolBar.
- \endtable
-
- See also \l {image-command} {\\image} and \l {inlineimage-command}
- {\\inlineimage}
-*/
-
-
-/*!
- \page 10-qdoc-commands-tablesandlists.html
- \previouspage Including Images
- \contentspage QDoc Manual
- \nextpage Special Content
-
- \title Tables and Lists
-
- These commands enable creating lists and tables. A list is
- rendered left aligned as a separate paragraph. A table is rendered
- centered as a separate paragraph. The table width depends on the
- width of its contents.
-
- \target table-command
- \section1 \\table
-
- The \\table and \\endtable commands delimit the contents of a
- table.
-
- The command accepts a single argument specifying the table's width
- as a percentage of the page width:
-
- \code
- / *!
- \table 100 %
-
- ...
-
- \endtable
- * /
- \endcode
-
- The code above ensures that the table will fill all available
- space. If the table's width is smaller than 100 %, the table will
- be centered in the generated documentation.
-
- A table can contain headers, rows and columns. A row starts with a
- \l {row-command} {\\row} command and consists of cells, each of which
- starts with an \l {li-command} {\\li} command. There is also a \l
- {header-command} {\\header} command which is a special kind of row
- that has a special format.
-
- \code
- / *!
- \table
- \header
- \li Qt Core Feature
- \li Brief Description
- \row
- \li \l {Signal and Slots}
- \li Signals and slots are used for communication
- between objects.
- \row
- \li \l {Layout Management}
- \li The Qt layout system provides a simple
- and powerful way of specifying the layout
- of child widgets.
- \row
- \li \l {Drag and Drop}
- \li Drag and drop provides a simple visual
- mechanism which users can use to transfer
- information between and within applications.
- \endtable
- * /
- \endcode
-
- QDoc renders this as:
-
- \raw HTML
- <table align="center" cellpadding="2"
- cellspacing="1" border="0">
- <tr valign="top" bgcolor="#a2c511">
- <th>Qt Core Feature</th>
- <th>Brief Description</th>
- </tr>
-
- <tr valign="top" bgcolor="#d0d0d0">
- <td>
- <a href="http://doc.qt.io/qt-5/signalsandslots.html">
- Signals and Slots</a>
- </td>
- <td>Signals and slots are used for communication
- between objects.</td>
- </tr>
-
- <tr valign="top" bgcolor="#c0c0c0">
- <td>
- <a href="http://doc.qt.io/qt-5/layout.html">
- Layout Management</a></td>
- <td>The Qt layout system provides a simple
- and powerful way of specifying the layout
- of child widgets.</td>
- </tr>
-
- <tr valign="top" bgcolor="#d0d0d0">
- <td>
- <a href="http://doc.qt.io/qt-5/dnd.html">
- Drag and Drop</a></td>
- <td>Drag and drop provides a simple visual
- mechanism which users can use to transfer
- information between and within applications.</td>
- </tr>
-
- </table>
- \endraw
-
- You can also make cells span several rows and columns. For
- example:
-
- \code
- / *!
- \table
- \header
- \li {3,1} This header cell spans three columns,
- but only one row.
- \row
- \li {2, 1} This table cell spans two columns,
- but only one row
- \li {1, 2} This table cell spans only one column,
- but two rows.
- \row
- \li A regular table cell
- \li A regular table cell
- \endtable
- * /
- \endcode
-
- QDoc renders this as:
-
- \raw HTML
- <table align="center" cellpadding="2" cellspacing="1"
- border="0">
-
- <tr valign="top" bgcolor="#a2c511">
- <th colspan="3" rowspan=" 1">
- This header cell spans three columns, but only one row.
- </th>
- </tr>
-
- <tr valign="top" bgcolor="#d0d0d0">
- <td colspan="2" rowspan=" 1">
- This table cell spans two columns, but only one row.
- </td>
- <td rowspan=" 2">
- This table cell spans only one column, but two rows.
- </td>
- </tr>
-
- <tr valign="top" bgcolor="#c0c0c0">
- <td>A regular table cell</td>
- <td>A regular table cell</td>
- </tr>
-
- </table>
- \endraw
-
- See also \l {header-command} {\\header}, \l {row-command} {\\row} and \l {li-command} {\\li}.
-
- \target header-command
- \section1 \\header
-
- The \\header command indicates that the following table cells are
- the current table's column headers.
-
- The command can only be used within the \l{table-command}
- {\\table...\\endtable} commands. A header can contain several
- cells. A cell is created with the \l {li-command} {\\li} command.
-
- A header cell's text is centered within the table cell and
- rendered using a bold font.
-
- \code
- / *!
- \table
- \header
- \li Qt Core Feature
- \li Brief Description
- \row
- \li \l {Signal and Slots}
- \li Signals and slots are used for communication
- between objects.
- \endtable
- * /
- \endcode
-
- QDoc renders this as:
-
- \raw HTML
- <table align="center" cellpadding="2"
- cellspacing="1" border="0">
- <tr valign="top" bgcolor="#a2c511">
- <th>Qt Core Feature</th>
- <th>Brief Description</th>
- </tr>
-
- <tr valign="top" bgcolor="#d0d0d0">
- <td>
- <a href="http://doc.qt.io/qt-5/signalsandslots.html">
- Signals and Slots</a>
- </td>
- <td>Signals and slots are used for communication
- between objects.</td>
- </tr>
- </table>
- \endraw
-
- See also \l {table-command} {\\table}, \l {row-command} {\\row} and \l {li-command} {\\li}.
-
- \target row-command
- \section1 \\row
-
- The \\row command begins a new row in a table. The \l {li-command}
- {\\li items} that belong in the new row will immediately follow the
- \\row.
-
- The command can only be used within the \l{table-command}
- {\\table...\\endtable} commands. A row can contain several
- cells. A cell is created with the \l {li-command} {\\li} command.
-
- The background cell color of each row alternates between two
- shades of grey, making it easier to distinguish the rows from each
- other. The cells' contents is left aligned.
-
- \code
- / *!
- \table
- \header
- \li Qt Core Feature
- \li Brief Description
- \row
- \li \l {Signal and Slots}
- \li Signals and slots are used for communication
- between objects.
- \row
- \li \l {Layout Management}
- \li The Qt layout system provides a simple
- and powerful way of specifying the layout
- of child widgets.
- \row
- \li \l {Drag and Drop}
- \li Drag and drop provides a simple visual
- mechanism which users can use to transfer
- information between and within applications.
- \endtable
- * /
- \endcode
-
- QDoc renders this as:
-
- \raw HTML
- <table align="center" cellpadding="2"
- cellspacing="1" border="0">
- <tr valign="top" bgcolor="#a2c511">
- <th>Qt Core Feature</th>
- <th>Brief Description</th>
- </tr>
-
- <tr valign="top" bgcolor="#d0d0d0">
- <td>
- <a href="http://doc.qt.io/qt-5/signalsandslots.html">
- Signals and Slots</a>
- </td>
- <td>Signals and slots are used for communication
- between objects.</td>
- </tr>
-
- <tr valign="top" bgcolor="#c0c0c0">
- <td>
- <a href="http://doc.qt.io/qt-5/layout.html">
- Layout Management</a></td>
- <td>The Qt layout system provides a simple
- and powerful way of specifying the layout
- of child widgets.</td>
- </tr>
-
- <tr valign="top" bgcolor="#d0d0d0">
- <td>
- <a href="http://doc.qt.io/qt-5/dnd.html">
- Drag and Drop</a></td>
- <td>Drag and drop provides a simple visual
- mechanism which users can use to transfer
- information between and within applications.</td>
- </tr>
-
- </table>
- \endraw
-
- See also \l {table-command} {\\table}, \l {header-command}
- {\\header}, and \l {li-command} {\\li}.
-
- \target value-command
- \section1 \\value
-
- The \\value command starts the documentation of a C++ enum item.
-
- The command's first argument is the enum item. Then follows its
- associated description. The description argument ends at the next
- blank line or \\value. The arguments are rendered within a table.
-
- The documentation will be located in the associated class, header
- file or namespace documentation. See the \l {enum-command}
- {\\enum} documentation for an example.
-
- \note Since Qt 5.4, \\value command can also be used outside the
- \l {enum-command} {\\enum} topic. In this case, QDoc renders a
- two-column table listing the constant name (taken as-is from the
- first argument) and its description. This can be used, for
- example, in \l {qmlproperty-command}{\\qmlproperty} topic for
- documenting acceptable values for a QML enumeration property.
-
- See also \l {enum-command} {\\enum} and \l {omitvalue-command} {\\omitvalue}.
-
- \target omitvalue-command
- \section1 \\omitvalue
-
- The \\omitvalue command excludes a C++ enum item from the
- documentation.
-
- The command's only argument is the name of the enum item that will
- be omitted. See the \l {enum-command} {\\enum} documentation for
- an example.
-
- See also \l {enum-command} {\\enum} and \l {value-command}
- {\\value}.
-
- \target list-command
- \section1 \\list
-
- The \\list and \\endlist commands delimit a list of items.
-
- Create each list item with the \l {li-command} {\\li} command. A
- list always contains one or more items. Lists can be nested. For
- example:
-
- \code
- / *!
- \list
- \li Qt Reference Documentation: Getting Started
- \list
- \li How to Learn Qt
- \li Installation
- \list
- \li Qt/X11
- \li Qt/Windows
- \li Qt/Mac
- \li Qt/Embedded
- \endlist
- \li Tutorial and Examples
- \endlist
- \endlist
- * /
- \endcode
-
- QDoc renders this as:
-
- \list
- \li Qt Reference Documentation: Getting Started
- \list
- \li How to Learn Qt
- \li Installation
- \list
- \li Qt/X11
- \li Qt/Windows
- \li Qt/Mac
- \li Qt/Embedded
- \endlist
- \li Tutorial and Examples
- \endlist
- \endlist
-
- The \\list command takes an optional argument providing
- alternative appearances for the list items.
-
- \code
- / *!
- \list
- \li How to Learn Qt
- \li Installation
- \li Tutorial and Examples
- \endlist
- * /
- \endcode
-
- QDoc renders the list items with bullets (the default):
-
- \list
- \li How to Learn Qt
- \li Installation
- \li Tutorial and Examples
- \endlist
-
- \warning There appears to be a bug in qdoc here. If you include
- any of the argument types, you get a numeric list. We're looking
- into it.
-
- If you provide 'A' as an argument to the \\list command, the
- bullets are replaced with characters in alphabetical order:
-
- \list A
- \li How to Learn Qt
- \li Installation
- \li Tutorial and Examples
- \endlist
-
- If you replace 'A' with '1', the list items are numbered in
- ascending order:
-
- \list 1
- \li How to Learn Qt
- \li Installation
- \li Tutorial and Examples
-
- \endlist
-
- If you provide 'i' as the argument, the bullets are replaced with
- roman numerals:
-
- \list i
- \li How to Learn Qt
- \li Installation
- \li Tutorial and Examples
- \endlist
-
- Finally, you can make the list items appear with roman numbers
- following in ascending order if you provide 'I' as the optional
- argument:
-
- \list I
- \li How to Learn Qt
- \li Installation
- \li Tutorial and Examples
- \endlist
-
- You can also make the listing start at any character or number by
- simply provide the number or character you want to start at. For
- example:
-
- \code
- / *!
- \list G
- \li How to Learn Qt
- \li Installation
- \li Tutorial and Examples
- \endlist
- * /
- \endcode
-
- \note This doesn't work in DITA XML, so don't use it because it
- produces a DITA XML file that doesn't validate. There probably is
- a way to do this in DITA, so if we figure it out, we will put it
- in. But this capability is not used anywhere other than right
- here, so it probably isn't important. For now, if you use this
- option, qdoc will ignore it and produce a list without it.
-
- QDoc renders this as:
-
- \list G
- \li How to Learn Qt
- \li Installation
- \li Tutorial and Examples
- \endlist
-
- See also \l {li-command} {\\li}.
-
- \target li-command
- \section1 \\li (table cell, list item)
-
- The \\li command marks a table cell or a list item. This command
- is only used in \l{table-command} {tables} and \l{list-command}
- {lists}.
-
- It considers everything as its argument until the next \\li command, until the
- next \l {table-command} {\\endtable}, or \l {list-command} {\\endlist}
- command. See \l {table-command} {\\table} and \l {list-command} {\\list}
- for examples.
-
- If the command is used within a table, you can also specify
- how many rows or columns the item should span.
-
- \code
- / *!
- \table
- \header
- \li {3,1} This header cell spans three columns
- but only one row.
- \row
- \li {2, 1} This table item spans two columns
- but only one row
- \li {1, 2} This table item spans only one column,
- but two rows.
- \row
- \li A regular table item
- \li A regular table item
- \endtable
- * /
- \endcode
-
- QDoc renders this as:
-
- \raw HTML
- <table align="center" cellpadding="2" cellspacing="1"
- border="0">
-
- <tr valign="top" bgcolor="#a2c511">
- <th colspan="3" rowspan=" 1">
- This header cell spans three columns, but only one row.
- </th>
- </tr>
-
- <tr valign="top" bgcolor="#d0d0d0">
- <td colspan="2" rowspan=" 1">
- This table item spans two columns, but only one row.
- </td>
- <td rowspan=" 2">
- This table item spans only one column, but two rows.
- </td>
- </tr>
-
- <tr valign="top" bgcolor="#c0c0c0">
- <td>A regular table item</td>
- <td>A regular table item</td>
- </tr>
-
- </table>
- \endraw
-
- If not specified, the item will span one column and one row.
-
- See also \l {table-command} {\\table}, \l {header-command}
- {\\header}, and \l {list-command} {\\list}.
-
-*/
-
-
-/*!
- \page 11-qdoc-commands-specialcontent.html
- \previouspage Tables and Lists
- \contentspage QDoc Manual
- \nextpage Miscellaneous
-
- \title Special Content
-
- The document contents commands identify parts of the documentation,
- parts with a special rendering, conceptual meaning or
- function.
-
- \target quotation-command
- \section1 \\quotation
-
- The \\quotation and \\endquotation commands delimit a long quotation.
-
- The text in the delimited block is surrounded by
- \b{<blockquote>} and \b{</blockquote>} in the html output,
- e.g.:
-
- \code
- / *!
- Although the prospect of a significantly broader market is
- good news for Firstlogic, the notion also posed some
- challenges. Dave Dobson, director of technology for the La
- Crosse, Wisconsin-based company, said:
-
- \quotation
- As our solutions were being adopted into new
- environments, we saw an escalating need for easier
- integration with a wider range of enterprise
- applications.
- \endquotation
- * /
- \endcode
-
- The text in the \b{\\quotation} block will appear in the generated HTML as:
-
- \code
- <blockquote>
- <p>As our solutions were being adopted into new environments,
- we saw an escalating need for easier integration with a wider
- range of enterprise applications.</p>
- </blockquote>
- \endcode
-
- The built-in style sheet for most browsers will render the
- contents of the <blockquote> tag with left and right
- indentations. The example above would be rendered as:
-
- \quotation
- As our solutions were being adopted into new
- environments, we saw an escalating need for easier
- integration with a wider range of enterprise
- applications.
- \endquotation
-
- But you can redefine the \b{<blockquote>} tag in your style.css file.
-
- \target footnote-command
- \section1 \\footnote
-
- The \\footnote and \\endfootnote commands delimit a footnote.
-
- The footnote is rendered at the bottom of the page.
-
- \warning The \b{\\footnote} and \b{\\endfootnote} commands
- have not been implemented. The footnote is rendered as a regular
- HTML paragraph.
-
- \target note-command
- \section1 \\note
-
- The \\note command defines a new paragraph preceded by "Note:"
- in bold.
-
- \target tableofcontents-command
- \section1 \\tableofcontents
-
- The \\tableofcontents command has been disabled because QDoc
- now generates a table of contents automatically.
-
- The automatically generated table of contents appears in the upper
- righthand corner of the page.
-
- \target brief-command
- \section1 \\brief
-
- The \\brief command introduces a one-sentence description of a
- class, namespace, header file, property, or variable.
-
- The brief text is used to introduce the documentation of the
- associated object, and in lists generated using the \l
- {generatelist-command} {\\generatelist} command and the \l
- {annotatedlist-command} {\\annotatedlist} command.
-
- The \\brief command can be used in two significant different ways:
- \l {brief class} {One for classes, namespaces and header files},
- and \l {brief-property} {one for properties and variables}.
-
- \target brief-property
-
- When the \\brief command is used to describe a property or a
- variable, the brief text must be a sentence fragment starting with
- "whether" (for a boolean property or variable) or starting with
- "the" (for any other property or variable).
-
- For example the boolean QWidget::isWindow property:
-
- \code
- / *!
- \property QWidget::isActiveWindow
- \brief Whether this widget's window is the active window
-
- The active window is the window that contains the widget that
- has keyboard focus.
-
- When popup windows are visible, this property is \c true
- for both the active window \e and the popup.
-
- \sa activateWindow(), QApplication::activeWindow()
- * /
- \endcode
-
- and the QWidget::geometry property
-
- \code
- / *!
- \property QWidget::geometry
- \brief The geometry of the widget relative to its parent and
- excluding the window frame
-
- When changing the geometry, the widget, if visible,
- receives a move event (moveEvent()) and/or a resize
- event (resizeEvent()) immediately.
-
- ...
-
- \sa frameGeometry(), rect(), ...
- * /
- \endcode
-
- QDoc renders this as:
-
- \quotation
- \raw HTML
- <h3>geometry :
- <a href="http://doc.qt.io/qt-5/qrect.html">QRect</a>
- </h3>
- \endraw
-
- This property holds the geometry of the widget relative
- to its parent and excluding the window frame.
-
- ...
-
- Access functions:
- \list
- \li \b {const QRect & geometry () const}
- \li \b {void setGeometry ( int x, int y, int w, int h )}
- \li \b {void setGeometry ( const QRect & )}
- \endlist
-
- See also \l
- {QWidget::frameGeometry()} {frameGeometry()}, \l
- {QWidget::rect()} {rect()}, ...
- \endquotation
-
- \target brief class
-
- When the \\brief command is used to describe a class, we recommend
- using a complete sentence like this:
-
- \code
- The <classname> class is|provides|contains|specifies...
- \endcode
-
- \warning Do not repeat your detailed description with the same sentence as
- the brief statement will be the first paragraph of the detailed
- description.
-
- \code
- / *!
- \class PreviewWindow
- \brief The PreviewWindow class is a custom widget
- displaying the names of its currently set
- window flags in a read-only text editor.
-
- The PreviewWindow class inherits QWidget. The widget
- displays the names of its window flags set with the
- setWindowFlags() function. It is also provided with a
- QPushButton that closes the window.
-
- ...
-
- \sa QWidget
- * /
- \endcode
-
- QDoc renders this as:
-
- \quotation
- \raw HTML
- <h1>PreviewWindow Class Reference</h1>
- \endraw
-
- The PreviewWindow class is a custom widget displaying
- the names of its currently set window flags in a
- read-only text editor. \l {preview window} {More...}
-
- \raw HTML
- <h3>Properties</h3>
- \endraw
-
- \list
- \li 52 properties inherited from QWidget
- \li 1 property inherited from QObject
- \endlist
-
- \raw HTML
- <h3>Public Functions</h3>
- \endraw
-
- \list
- \li \l {constructor} {PreviewWindow}(QWidget *parent = 0)
- \li void \l {function} {setWindowFlags}(Qt::WindowFlags flags)
- \endlist
-
- \list
- \li 183 public functions inherited from QWidget
- \li 28 public functions inherited from QObject
- \endlist
-
- \raw HTML
- <h3>Public Slots</h3>
- \endraw
-
- \list
- \li 17 public slots inherited from QWidget
- \li 1 public slot inherited from QObject
- \endlist
-
- \raw HTML
- <h3>Additional Inherited Members</h3>
- \endraw
-
- \list
- \li 1 signal inherited from QWidget
- \li 1 signal inherited from QObject
- \li 4 static public members inherited from QWidget
- \li 4 static public members inherited from QObject
- \li 39 protected functions inherited from QWidget
- \li 7 protected functions inherited from QObject
- \endlist
-
- \target preview window
-
- \raw HTML
- <hr />
- <h2>Detailed Description</h2>
- \endraw
-
- The PreviewWindow class is a custom widget displaying
- the names of its currently set window flags in a
- read-only text editor.
-
- The PreviewWindow class inherits QWidget. The widget
- displays the names of its window flags set with the \l
- {function} {setWindowFlags()} function. It is also
- provided with a QPushButton that closes the window.
-
- ...
-
- See also QWidget.
-
- \raw HTML
- <hr />
- <h2>Member Function Documentation</h2>
- \endraw
-
- \target constructor
- \raw HTML
- <h3>PreviewWindow(QWidget *parent = 0)</h3>
- \endraw
-
- Constructs a preview window widget with \e parent.
-
- \target function
- \raw HTML
- <h3>setWindowFlags(Qt::WindowFlags flags)</h3>
- \endraw
-
- Sets the widgets flags using the
- QWidget::setWindowFlags() function.
-
- Then runs through the available window flags,
- creating a text that contains the names of the flags
- that matches the flags parameter, displaying
- the text in the widgets text editor.
- \endquotation
-
- Using \\brief in a \l{namespace-command}{\\namespace}:
-
- \code
- / *!
- \namespace Qt
-
- \brief The Qt namespace contains miscellaneous identifiers
- used throughout the Qt library.
- * /
- \endcode
-
- Using \\brief in a \l{headerfile-command}{\\headerfile}:
-
- \code
- / *!
- \headerfile <QtGlobal>
- \title Global Qt Declarations
-
- \brief The <QtGlobal> header file provides basic
- declarations and is included by all other Qt headers.
-
- \sa <QtAlgorithms>
- * /
- \endcode
-
- See also \l{property-command} {\\property}, \l{class-command}
- {\\class}, \l{namespace-command} {\\namespace} and
- \l{headerfile-command} {\\headerfile}.
-
- \target legalese-command
- \section1 \\legalese
-
- The \\legalese and \\endlegalese commands delimit a license agreement.
-
- In the generated HTML, the delimited text is surrounded by a \b
- {<div class="LegaleseLeft">} and \b {</div>} tags.
-
- An example of a license agreement enclosed in \\legalese
- and \\endlegalese:
-
- \code
- / *!
- \legalese
- Copyright 1996 Daniel Dardailler.
-
- Permission to use, copy, modify, distribute, and sell this
- software for any purpose is hereby granted without fee,
- provided that the above copyright notice appear in all
- copies and that both that copyright notice and this
- permission notice appear in supporting documentation, and
- that the name of Daniel Dardailler not be used in
- advertising or publicity pertaining to distribution of the
- software without specific, written prior permission. Daniel
- Dardailler makes no representations about the suitability of
- this software for any purpose. It is provided "as is"
- without express or implied warranty.
-
- Modifications Copyright 1999 Matt Koss, under the same
- license as above.
- \endlegalese
- * /
- \endcode
-
- It will appear in the generated HTML as:
-
- \code
- <div class="LegaleseLeft">
- <p>Copyright 1996 Daniel Dardailler.</p>
- <p>Permission to use, copy, modify, distribute, and sell
- this software for any purpose is hereby granted without fee,
- provided that the above copyright notice appear in all
- copies and that both that copyright notice and this
- permission notice appear in supporting documentation, and
- that the name of Daniel Dardailler not be used in
- advertising or publicity pertaining to distribution of the
- software without specific, written prior permission. Daniel
- Dardailler makes no representations about the suitability of
- this software for any purpose. It is provided "as is"
- without express or implied warranty.</p>
-
- <p>Modifications Copyright 1999 Matt Koss, under the same
- license as above.</p>
- </div>
- \endcode
-
- If the \\endlegalese command is omitted, QDoc will process the
- \\legalese command but considers the rest of the documentation
- page as the license agreement.
-
- Ideally, the license text is located with the licensed code.
-
- Elsewhere, the documentation identified as \e{\\legalese} command
- can be accumulated using \l {generatelist-command} {\\generatelist}
- with \c {legalese-command} as the argument. This is useful for
- generating an overview of the license agreements associated with
- the source code.
-
- \target warning-command
- \section1 \\warning
-
- The \\warning command prepends "Warning:" to the command's
- argument, in bold font.
-
- \code
- / *!
- Qt::HANDLE is a platform-specific handle type
- for system objects. This is equivalent to
- \c{void *} on Windows and OS X, and to
- \c{unsigned long} on X11.
-
- \warning Using this type is not portable.
- * /
- \endcode
-
- QDoc renders this as:
-
- \quotation
- Qt::HANDLE is a platform-specific handle type
- for system objects. This is equivalent to
- \c{void *} on Windows and OS X, and to
- \c{unsigned long} on X11.
-
- \warning Using this type is not portable.
- \endquotation
-
-*/
-
-
-/*!
- \page 12-0-qdoc-commands-miscellaneous.html
- \previouspage Special Content
- \contentspage QDoc Manual
- \nextpage Creating DITA Maps
-
- \title Miscellaneous
-
- These commands provide miscellaneous functions connected to the
- visual appearance of the documentation, and to the process of
- generating the documentation.
-
- \target annotatedlist-command
- \section1 \\annotatedlist
-
- The \\annotatedlist command expands to a list of the members of a
- group, each member listed with its \e {brief} text. Below is an
- example from the Qt Reference Documentation:
-
- \code
- / *!
- ...
- \section1 Drag and Drop Classes
-
- These classes deal with drag and drop and the necessary mime type
- encoding and decoding.
-
- \annotatedlist draganddrop
-
- * /
- \endcode
-
- This generates a list of all the C++ classes and/or QML types in
- the \e{draganddrop} group. A C++ class or QML type in the
- \e{draganddrop} group will have \e{\\ingroup draganddrop} in its
- \e{\\class} or \e{\\qmltype} comment.
-
-
- \target generatelist-command
- \section1 \\generatelist
-
- The \\generatelist command expands to a list of links to the
- documentation entities in a group. Below is an example from the Qt
- Reference Documentation:
-
- \code
- / *!
- \page classes.html
- \title All Classes
-
- For a shorter list that only includes the most
- frequently used classes, see \l{Qt's Main Classes}.
-
- \generatelist classes Q
- * /
- \endcode
-
- This generates the \e {All Classes} page. The command accepts the
- following arguments:
-
- \target table example
- \section2 \c annotatedclasses
-
- The \c annotatedclasses argument provides a table containing the
- names of all the classes, and a description of each class. Each
- class name is a link to the class's reference documentation. For
- example:
-
- \table
- \row
- \li QDial
- \li Rounded range control (like a speedometer or potentiometer)
- \row
- \li QDialog
- \li The base class of dialog windows
- \row
- \li QDir
- \li Access to directory structures and their contents
- \endtable
-
- A C++ class is documented with the \l {class-command} {\\class}
- command. The annotation for the class is taken from the argument
- of the class comment's \l {brief-command} {\\brief} command.
-
- \target list example
- \section2 \c {classes <prefix>}
-
- The \c classes argument provides a complete alphabetical list of
- the classes. The second argument, \c{<prefix>}, is the common
- prefix for the class names. The class names will be sorted on the
- character that follows the common prefix. e.g. The common prefix
- for the Qt classes is \c Q. The common prefix argument is
- optional. If no common prefix is provided, the class names will
- be sorted on their first character.
-
- Each class name becomes a link to the class's reference
- documentation. This command is used to generate the
- \e {All Classes} page this way:
-
- \code
- / *!
- \page classes.html
- \title All Classes
- \ingroup classlists
-
- \brief Alphabetical list of classes.
-
- This is a list of all Qt classes. For a list of the classes
- provided for compatibility with Qt3, see \l{Qt3 Support
- Classes}. For classes that have been deprecated, see the
- \l{Obsolete Classes} list.
-
- \generatelist classes Q
- * /
- \endcode
-
- A C++ class is documented with the \l {class-command} {\\class}
- command.
-
- \section2 \c classesbymodule
-
- When this argument is used, a second argument is required, which
- specifies the module whose classes are to be listed. QDoc
- generates a table containing those classes. Each class is listed
- with the text of its \l{brief-command} {\\brief} command.
-
- For example, this command can be used on a module page as follows:
-
- \code
- / *!
- \page phonon-module.html
- \module Phonon
- \title Phonon Module
- \ingroup modules
-
- \brief Contains namespaces and classes for multimedia functionality.
-
- \generatelist{classesbymodule Phonon}
-
- ...
-
- * /
- \endcode
-
- Each class that is a member of the specified module must be marked
- with the \l {inmodule-command} {\\inmodule} command in its \\class
- comment.
-
- \section2 \c qmltypesbymodule
-
- Similar to \c classesbymodule argument, but used for listing the
- QML types from the QML module specified with the second argument.
-
- \note Support for this argument was introduced in QDoc 5.6.
-
- \section2 \c jstypesbymodule
-
- Similar to \c classesbymodule argument, but used for listing the
- JavaScript types from the module specified with the second argument.
-
- \note Support for this argument was introduced in QDoc 5.6.
-
- \section2 \c compatclasses
-
- The \c compatclasses argument generates a list in alphabetical
- order of the support classes. It is normally used only to
- generate the Qt3 Support Classes page this way:
-
- \code
- / *!
- \page compatclasses.html
- \title Qt3 Support Classes
- \ingroup classlists
-
- \brief Enable porting of code from Qt 3 to Qt 4.
-
- These are the classes that Qt provides for compatibility with Qt
- 3. Most of these are provided by the Qt3Support module.
-
- \generatelist compatclasses
- * /
- \endcode
-
- A support class is identified in the \\class comment with the \l
- {compat-command} {\\compat} command.
-
- \section2 \c functionindex
-
- The \c functionindex argument provides a complete alphabetical
- list of all the documented member functions. It is normally used
- only to generate the \e {Qt function index} page
- this way:
-
- \code
- / *!
- \page functions.html
- \title All Functions
- \ingroup funclists
-
- \brief All documented Qt functions listed alphabetically with a
- link to where each one is declared.
-
- This is the list of all documented member functions and global
- functions in the Qt API. Each function has a link to the
- class or header file where it is declared and documented.
-
- \generatelist functionindex
- * /
- \endcode
-
- \section2 \c legalese
-
- The \c legalese argument tells QDoc to generate a complete list of
- licenses in the documentation. Each license is identified using
- the \l {legalese-command} {\\legalese} command. This command is
- used to generate the \e {Qt license information}
- page this way:
-
- \code
- / *!
- \page licenses.html
- \title Other Licenses Used in Qt
- \ingroup licensing
- \brief Information about other licenses used for Qt components and third-party code.
-
- Qt contains some code that is not provided under the
- \l{GNU General Public License (GPL)},
- \l{GNU Lesser General Public License (LGPL)} or the
- \l{Qt Commercial Edition}{Qt Commercial License Agreement}, but rather under
- specific licenses from the original authors. Some pieces of code were developed
- by The Qt Company and others originated from third parties.
- This page lists the licenses used, names the authors, and links
- to the places where it is used.
-
- The Qt Company gratefully acknowledges these and other contributions
- to Qt. We recommend that programs that use Qt also acknowledge
- these contributions, and quote these license statements in an
- appendix to the documentation.
-
- See also: \l{Licenses for Fonts Used in Qt for Embedded Linux}
-
- \generatelist legalese
- * /
- \endcode
-
- \section2 \c overviews
-
- The \c overviews argument is used to tell QDoc to generate a list
- by concatenating the contents of all the \l {group-command}
- {\\group} pages. Qt uses it to generate the \e {overviews} page
- this way:
-
- \code
- / *!
- \page overviews.html
-
- \title All Overviews and HOWTOs
-
- \generatelist overviews
- * /
- \endcode
-
- \section2 \c related
-
- The \c related argument is used in combination with the \l
- {group-command} {\\group} and \l {ingroup-command} {\\ingroup}
- commands to list all the overviews related to a specified
- group. For example, the page for the \e {Programming with Qt}
- page is generated this way:
-
- \code
- / *!
- \group qt-basic-concepts
- \title Programming with Qt
-
- \brief The basic architecture of the Qt cross-platform application and UI framework.
-
- Qt is a cross-platform application and UI framework for
- writing web-enabled applications for desktop, mobile, and
- embedded operating systems. This page contains links to
- articles and overviews explaining key components and
- techniuqes used in Qt development.
-
- \generatelist {related}
- * /
- \endcode
-
- Each page listed on this group page contains the command:
-
- \code
- \ingroup qt-basic-concepts
- \endcode
-
- \target if-command
- \section1 \\if
-
- The \\if command and the corresponding \\endif command
- enclose parts of a QDoc comment that only will be included if
- the condition specified by the command's argument is true.
-
- The command reads the rest of the line and parses it as an C++ #if
- statement.
-
- \code
- / *!
- \if defined(opensourceedition)
-
- \b{Note:} This edition is for the development of
- \l{Qt Open Source Edition} {Free and Open Source}
- software only; see \l{Qt Commercial Editions}.
-
- \endif
- * /
- \endcode
-
- This QDoc comment will only be rendered if the \c
- opensourceedition preprocessor symbol is defined, and specified in
- the \l {defines-variable} {defines} variable in the configuration
- file to make QDoc process the code within #ifdef and #endif:
-
- \code
- defines = opensourceedition
- \endcode
-
- You can also define the preprocessor symbol manually on the
- command line. For more information see the documentation of the \l
- {defines-variable} {defines} variable.
-
- See also \l{endif-command} {\\endif}, \l{else-command} {\\else},
- \l {defines-variable} {defines} and \l {falsehoods-variable}
- {falsehoods}.
-
- \target endif-command
- \section1 \\endif
-
- The \\endif command and the corresponding \\if command
- enclose parts of a QDoc comment that will be included if
- the condition specified by the \l {if-command} {\\if} command's
- argument is true.
-
- For more information, see the documentation of the \l {if-command}
- {\\if} command.
-
- See also \l{if-command} {\\if}, \l{else-command} {\\else}, \l
- {defines-variable} {defines} and \l {falsehoods-variable}
- {falsehoods}.
-
- \target else-command
- \section1 \\else
-
- The \\else command specifies an alternative if the
- condition in the \l {if-command} {\\if} command is false.
-
- The \\else command can only be used within \l {if-command}
- {\\if...\\endif} commands, but is useful when there is only two
- alternatives.
-
- \code
- / *!
- The Qt 3 support library is provided to keep old
- source code working.
-
- In addition to the \c Qt3Support classes, Qt 4 provides
- compatibility functions when it's possible for an old
- API to cohabit with the new one.
-
- \if !defined(QT3_SUPPORT)
- \if defined(QT3_SUPPORTWARNINGS)
- The compiler emits a warning when a
- compatibility function is called. (This works
- only with GCC 3.2+ and MSVC 7.)
- \else
- To use the Qt 3 support library, you need to
- have the line QT += qt3support in your .pro
- file (qmake automatically define the
- QT3_SUPPORT symbol, turning on compatibility
- function support).
-
- You can also define the symbol manually (for example,
- if you don't want to link against the \c
- Qt3Support library), or you can define \c
- QT3_SUPPORT_WARNINGS instead, telling the
- compiler to emit a warning when a compatibility
- function is called. (This works only with GCC
- 3.2+ and MSVC 7.)
- \endif
- \endif
- * /
- \endcode
-
- If the \c QT3_SUPPORT is defined, the comment will be rendered
- like this:
-
- \quotation
- The Qt 3 support library is provided to keep old source
- code working.
-
- In addition to the Qt3Support classes, Qt 4 provides
- compatibility functions when it's possible for an old
- API to cohabit with the new one.
- \endquotation
-
- If \c QT3_SUPPORT is not defined but \c QT3_SUPPORT_WARNINGS is
- defined, the comment will be rendered like this:
-
- \quotation
- The Qt 3 support library is provided to keep old source
- code working.
-
- In addition to the Qt3Support classes, Qt 4 provides
- compatibility functions when it's possible for an old
- API to cohabit with the new one.
-
- The compiler emits a warning when a compatibility
- function is called. (This works only with GCC 3.2+ and
- MSVC 7.)
- \endquotation
-
- If none of the symbols are defined, the comment will be
- rendered as
-
- \quotation
- The Qt 3 support library is provided to keep old
- source code working.
-
- In addition to the \c Qt3Support classes, Qt 4 provides
- compatibility functions when it's possible for an old
- API to cohabit with the new one.
-
- To use the Qt 3 support library, you need to have the
- line QT += qt3support in your .pro file (qmake
- automatically define the QT3_SUPPORT symbol, turning on
- compatibility function support).
-
- You can also define the symbol manually (e.g., if you
- don't want to link against the \c Qt3Support library),
- or you can define \c QT3_SUPPORT_WARNINGS instead,
- telling the compiler to emit a warning when a
- compatibility function is called. (This works only with
- GCC 3.2+ and MSVC 7.)
- \endquotation
-
- See also \l{if-command} {\\if}, \l{endif-command} {\\endif}, \l
- {defines-variable} {defines} and \l {falsehoods-variable}
- {falsehoods}.
-
- \target include-command
- \section1 \\include
-
- The \\include command sends all or part of the file specified by
- its first argument to the QDoc input stream to be processed as a
- QDoc comment snippet. This command is often assigned the alias,
- \e {input}, in the QDoc configuration file, for example \e {alias.include
- = input}.
-
- The command is useful when some snippet of commands and text is to
- be used in multiple places in the documentation. In that case,
- move the snippet into a separate file and use the \\include
- command wherever you want to insert the snippet into the
- documentation. To prevent QDoc from reading the file as a
- stand-alone page of documentation, we recommend that you use the
- \c .qdocinc extension for these \e {include} files.
-
- The command can have either one or two arguments. The first
- argument is always a file name. The contents of the file must be
- QDoc input, in other words, a sequence of QDoc commands and text, but
- without the enclosing QDoc comment \c{/}\c{*!} ... \c{*}\c{/} delimiters.
- If you want to include the entire named file, don't use the second
- argument. If you want to include only part of the file, see the
- \l{2-argument-form}{two argument form} below. Here is an example
- of the one argument form:
-
- \code
- / *!
- \page corefeatures.html
- \title Core Features
-
- \include examples/signalandslots.qdocinc
- \include examples/objectmodel.qdocinc
- \include examples/layoutmanagement.qdocinc
- * /
- \endcode
-
- QDoc renders this page \l{corefeatures.html} {as shown here}.
-
- \target 2-argument-form}
- \section2 \\include filename snippet-identifier
-
- It is a waste of time to make a separate \c .qdocinc file for every
- QDoc include snippet you want to use in multiple places in the
- documentation, especially given that you probably have to put the
- copyright/license notice in every one of these files. So if you
- have a large number of snippets to be included, you can put them all in a
- single file if you want, and surround each one with:
- \code
- //! [snippet-id1]
-
- QDoc commands and text...
-
- //! [snippet-id1]
-
- //! [snippet-id2]
-
- More QDoc commands and text...
-
- //! [snippet-id2]
- \endcode
-
- Then you can use the two-argument form of the command:
-
- \code
- \input examples/signalandslots.qdocinc snippet-id2
- \input examples/objectmodel.qdocinc another-snippet-id
- \endcode
-
- It works as expected. The sequence of QDoc commands and text found
- between the two tags with the same name as the second argument is
- sent to the QDoc input stream. You can even nest these snippets,
- although it's not clear why you would want to do that.
-
- \target meta-command
- \section1 \\meta
-
- The \\meta command is mainly used for including metadata in DITA
- XML files. It is also used when generating HTML output for specifying
- the \e maintainer(s) of a C++ class.
-
- The command has two arguments: the first argument is the name of the
- metadata attribute, and the second argument is the
- value for the attribute. Each argument should be enclosed in curly
- brackets, as shown in this example:
-
- \code
- / *!
- \class QWidget
- \brief The QWidget class is the base class of all user interface objects.
-
- \ingroup basicwidgets
-
- \meta {technology} {User Interface}
- \meta {platform} {OS X 10.6}
- \meta {platform} {Symbian}
- \meta {platform} {MeeGo}
- \meta {audience} {user}
- \meta {audience} {programmer}
- \meta {audience} {designer}
- * /
- \endcode
-
- When running QDoc to generate HTML, the example above will have no
- effect on the generated output, but if you run QDoc to generate
- DITA XML, the example will generate the following:
-
- \code
- <?xml version="1.0" encoding="UTF-8"?>
- <!DOCTYPE cxxClass PUBLIC "-//NOKIA//DTD DITA C++ API Class Reference Type v0.6.0//EN" "dtd/cxxClass.dtd">
- <!--qwidget.cpp-->
- <cxxClass id="id-9a14268e-6b09-4eee-b940-21a00a0961df">
- <apiName>QWidget</apiName>
- <shortdesc>the QWidget class is the base class of all user interface objects.</shortdesc>
- <prolog>
- <author>Qt Development Frameworks</author>
- <publisher>Qt Project</publisher>
- <copyright>
- <copyryear year="2015"/>
- <copyrholder>Qt Project</copyrholder>
- </copyright>
- <permissions view="all"/>
- <metadata>
- <audience type="designer"/>
- <audience type="programmer"/>
- <audience type="user"/>
- <category>Class reference</category>
- <prodinfo>
- <prodname>Qt Reference Documentation</prodname>
- <vrmlist>
- <vrm version="4" release="7" modification="3"/>
- </vrmlist>
- <component>QtGui</component>
- </prodinfo>
- <othermeta name="platform" content="MeeGo"/>
- <othermeta name="platform" content="Symbian"/>
- <othermeta name="platform" content="OS X 10.6"/>
- <othermeta name="technology" content="User Interface"/>
- </metadata>
- </prolog>
- \endcode
-
- In the example output, several values have been set using default
- values obtained from the QDoc configuration file. See \l
- {Generating DITA XML Output} for details.
-
- \target noautolist-command
- \section1 \\noautolist
-
- The \\noautolist command indicates that the annotated list of C++
- classes or QML types, which is automatically generated at the
- bottom of the C++ or QML module page should be omitted, because
- the classes or types have been listed manually. This command can
- also be used with the \l {group-command}{\\group} command to omit
- the list of group members, when they are listed manually.
-
- The command must stand on its own line. See \l {Qt Sensors QML Types} for
- an example. The page is generated from \c {qtsensors5.qdoc}. There you will
- find a qdoc comment containing the \c{\qmlmodule} command for the QtSensors
- module. The same qdoc comment contains two \c {\annotated-list} commands to
- list the QML types in two separate groups. The QML types have been divided
- into these two groups because it makes more sense to list them this way than
- it does to list them in a single alphabetical list. At the bottom of the
- comment, \c {\noautolist} has been used to tell qdoc not to generate the
- automatic annotated list.
-
- This command was introduced in QDoc 5.6.
-
- \target omit-command
- \section1 \\omit
-
- The \\omit command and the corresponding \\endomit command
- delimit parts of the documentation that you want QDoc to skip. For
- example:
-
- \code
- / *!
- \table
- \row
- \li Basic Widgets
- \li Basic GUI widgets such as buttons, comboboxes
- and scrollbars.
-
- \omit
- \row
- \li Component Model
- \li Interfaces and helper classes for the Qt
- Component Model.
- \endomit
-
- \row
- \li Database Classes
- \li Database related classes, e.g. for SQL databases.
- \endtable
- * /
- \endcode
-
- QDoc renders this as:
-
- \raw HTML
- <table align="center" cellpadding="2"
- cellspacing="1" border="0">
-
- <tr valign="top" bgcolor="#d0d0d0">
- <td>Basic Widgets</td>
- <td>Basic GUI widgets such as buttons, comboboxes
- and scrollbars.</td>
- </tr>
-
- <tr valign="top" bgcolor="#c0c0c0">
- <td>Database Classes</td>
- <td>Database related classes, e.g. for SQL databases.</td>
- </tr>
- </table>
- \endraw
-
- \target raw-command
- \section1 \\raw \span {class="newStuff"} {(avoid)}
-
- The \\raw command and the corresponding
- \\endraw command delimit a block of raw mark-up language code.
-
- \note Avoid using this command if possible, because it generates
- DITA XML code that causes problems. If you are trying to generate
- special table or list behavior, try to get the behavior you want
- using the \l {span-command} {\\span} and \l {div-command} {\\div}
- commands in your \l {table-command} {\\table} or \l {list-command}
- {\\list}.
-
- The command takes an argument specifying the code's format.
- Currently, the only supported format is HTML.
-
- The \\raw command is useful if you want some special HTML effects
- in your documentation.
-
- \code
- / *!
- Qt has some predefined QColor objects.
-
- \raw HTML
- <style type="text/css" id="colorstyles">
- #color-blue { background-color: #0000ff; color: #ffffff }
- #color-darkBlue { background-color: #000080; color: #ffffff }
- #color-cyan { background-color: #00ffff; color: #000000 }
- </style>
-
- <p>
- <tt id="color-blue">Blue(#0000ff)</tt>,
- <tt id="color-darkBlue">dark blue(#000080)</tt> and
- <tt id="color-cyan">cyan(#00ffff)</tt>.
- </p>
- \endraw
- * /
- \endcode
-
- QDoc renders this as:
-
- \quotation
- Qt has some predefined QColor objects.
-
- \raw HTML
- <style type="text/css" id="colorstyles">
- #color-blue { background-color: #0000ff; color: #ffffff }
- #color-darkBlue { background-color: #000080; color: #ffffff }
- #color-cyan { background-color: #00ffff; color: #000000 }
- </style>
-
- <p>
- <tt id="color-blue">Blue(#0000ff)</tt>,
- <tt id="color-darkBlue">dark blue(#000080)</tt> and
- <tt id="color-cyan">cyan(#00ffff)</tt>.
- </p>
- \endraw
- \endquotation
-
- \note But you can achieve the exact same thing using qdoc
- commands. In this case, all you have to do is include the color
- styles in your style.css file. Then you can write:
-
- \code
- \tt {\span {id="color-blue"} {Blue(#0000ff)}},
- \tt {\span {id="color-darkBlue"} {dark blue(#000080)}} and
- \tt {\span {id="color-cyan"} {cyan(#00ffff)}}.
- \endcode
-
- ...which is rendered as:
-
- \tt {\span {id="color-blue"} {Blue(#0000ff)}},
- \tt {\span {id="color-darkBlue"} {dark blue(#000080)}} and
- \tt {\span {id="color-cyan"} {cyan(#00ffff)}}.
-
- \target unicode-command
- \section1 \\unicode
-
- The \\unicode command allows you to insert an arbitrary Unicode
- character in the document.
-
- The command takes an argument specifying the character as an
- integer. By default, base 10 is assumed, unless a '0x' or '0'
- prefix is specified (for base 16 and 8, respectively). For
- example:
-
- \code
- O G\unicode{0xEA}nio e as Rosas
-
- \unicode 0xC0 table en famille avec 15 \unicode 0x20AC par jour
-
- \unicode 0x3A3 \e{a}\sub{\e{i}}
- \endcode
-
- QDoc renders this as:
-
- \quotation
- O G\unicode{0xEA}nio e as Rosas
-
- \unicode 0xC0 table en famille avec 15 \unicode 0x20AC par jour
-
- \unicode 0x3A3 \e{a}\sub{\e{i}}
- \endquotation
-*/
-
diff --git a/src/tools/qdoc/doc/qdoc-manual-qdocconf.qdoc b/src/tools/qdoc/doc/qdoc-manual-qdocconf.qdoc
deleted file mode 100644
index 69980c1e18..0000000000
--- a/src/tools/qdoc/doc/qdoc-manual-qdocconf.qdoc
+++ /dev/null
@@ -1,1714 +0,0 @@
-/****************************************************************************
-**
-** Copyright (C) 2015 The Qt Company Ltd.
-** Contact: http://www.qt.io/licensing/
-**
-** This file is part of the documentation of the Qt Toolkit.
-**
-** $QT_BEGIN_LICENSE:FDL$
-** Commercial License Usage
-** Licensees holding valid commercial Qt licenses may use this file in
-** accordance with the commercial license agreement provided with the
-** Software or, alternatively, in accordance with the terms contained in
-** a written agreement between you and The Qt Company. For licensing terms
-** and conditions see http://www.qt.io/terms-conditions. For further
-** information use the contact form at http://www.qt.io/contact-us.
-**
-** GNU Free Documentation License Usage
-** Alternatively, this file may be used under the terms of the GNU Free
-** Documentation License version 1.3 as published by the Free Software
-** Foundation and appearing in the file included in the packaging of
-** this file. Please review the following information to ensure
-** the GNU Free Documentation License version 1.3 requirements
-** will be met: http://www.gnu.org/copyleft/fdl.html.
-** $QT_END_LICENSE$
-**
-****************************************************************************/
-
-/*!
- \page 21-0-qdoc-configuration.html
- \previouspage Creating DITA Maps
- \contentspage QDoc Manual
- \nextpage Generic Configuration Variables
-
- \title The QDoc Configuration File
-
- Before running QDoc, you must create a QDoc configuration file to
- tell QDoc where to find the source files that contain the QDoc
- comments. The pathname to your configuration file is passed to
- QDoc on the command line:
-
- \quotation
- \c {/current/dir$ ../../bin/qdoc ./config.qdocconf}
- \endquotation
-
- \section1 General Description
-
- The configuration file is a list of entries of the form \e
- {"variable = value"}. Using the configuration variables, you can
- define where QDoc should find the various source files, images and
- examples, where to put generated documentation etc. The
- configuration file can also contain directives like \c
- include. For an example, see \l {minimal-qdocconf}{a minimal qdocconf file}.
-
- You can also use configuration variables to get QDoc to support
- \l{Supporting Derived Projects} {derived projects}, i.e QDoc can
- generate links in your project's documentation to elements in the
- Qt online documentation. See the \l {Supporting Derived projects}
- section.
-
- The value of a configuration variable can be set using either '='
- or '+='. The difference is that '=' overrides the previous value,
- while '+=' adds a new value to the current one.
-
- Some configuration variables accept a list of strings as their
- value, for example:
- \l {sourcedirs-variable}
- {\c{sourcedirs}}, while others accept only a single string. Double
- quotes around a value string are optional, but including them allows
- you to use special characters like '=' and ' \" ' within the value
- string, for example:
-
- \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:
-
- \badcode
- sourcedirs = kernel \
- tools \
- widgets
- \endcode
-
- \section1 Configuration Variables
-
- \section1 Variable List
-
- \list
- \li \l {alias-variable} {alias}
- \li \l {Cpp.ignoredirectives-variable} {Cpp.ignoredirectives}
- \li \l {Cpp.ignoretokens-variable} {Cpp.ignoretokens}
- \li \l {defines-variable} {defines}
- \li \l {edition-variable} {edition}
- \li \l {exampledirs-variable} {exampledirs}
- \li \l {examples-variable} {examples}
- \li \l {examples.fileextensions-variable} {examples.fileextensions}
- \li \l {excludedirs-variable} {excludedirs}
- \li \l {excludefiles-variable} {excludefiles}
- \li \l {extraimages-variable} {extraimages}
- \li \l {falsehoods-variable} {falsehoods}
- \li \l {headerdirs-variable} {headerdirs}
- \li \l {headers-variable} {headers}
- \li \l {headers.fileextensions-variable} {headers.fileextensions}
- \li \l {HTML.footer-variable} {HTML.footer}
- \li \l {HTML.postheader-variable} {HTML.postheader}
- \li \l {HTML.style-variable} {HTML.style}
- \li \l {imagedirs-variable} {imagedirs}
- \li \l {images-variable} {images}
- \li \l {images.fileextensions-variable} {images.fileextensions}
- \li \l {language-variable} {language}
- \li \l {macro-variable} {macro}
- \li \l {manifestmeta-variable} {manifestmeta}
- \li \l {outputdir-variable} {outputdir}
- \li \l {outputformats-variable} {outputformats}
- \li \l {outputprefixes-variable} {outputprefixes}
- \li \l {outputsuffixes-variable} {outputsuffixes}
- \li \l {sourcedirs-variable} {sourcedirs}
- \li \l {sources-variable} {sources}
- \li \l {sources.fileextensions-variable} {sources.fileextensions}
- \li \l {spurious-variable} {spurious}
- \li \l {tabsize-variable} {tabsize}
- \li \l {version-variable} {version}
- \li \l {versionsym-variable} {versionsym}
- \endlist
-
- \section1 Categories
-
- \list
- \li \l {Generic Configuration Variables}
- \li \l {C++ Specific Configuration Variables}
- \li \l {HTML Specific Configuration Variables}
- \endlist
-
- \section1 Configuration File Examples
-
- \list
- \li A minimum configuration file: \l minimum.qdocconf
- \li The Qt configuration file: \l qtgui.qdocconf
- \endlist
-*/
-
-
-/*!
- \page 22-qdoc-configuration-generalvariables.html
- \previouspage The QDoc Configuration File
- \contentspage QDoc Manual
- \nextpage Creating Help Project Files
-
- \title Generic Configuration Variables
-
- With the general QDoc configuration variables, you can define
- where QDoc will find the various source files it needs to generate
- the documentation, as well as the directory to put the generated
- documentation. You can also do some minor manipulation of QDoc
- itself, controlling its output and processing behavior.
-
- \target alias-variable
- \section1 alias
-
- The \c alias variable renames a QDoc command.
-
- The general syntax is \tt {alias.\e{original-command-name} = \e
- temporary-command-name}.
-
- \badcode
- alias.e = i
- \endcode
-
- This renames the built-in command \\e (italics) to be \\i. The \c
- alias variable is often used for compatibility reasons.
-
- See also \l {macro-variable} {macro}.
-
- \target codeindent-variable
- \section1 codeindent
-
- The \c codeindent variable specifies the level of indentation that
- QDoc uses when writing code snippets.
-
- QDoc originally used a hard-coded value of four spaces for code
- indentation to ensure that code snippets could be easily
- distinguished from surrounding text. Since we can use \l{HTML
- Specific Configuration Variables#HTML.stylesheets} {stylesheets}
- to adjust the appearance of certain types of HTML elements, this
- level of indentation is not always required.
-
- \target codeprefix-variable
- \target codesuffix-variable
- \section1 codeprefix, codesuffix
-
- The \c codeprefix and \c codesuffix variables specify a pair of
- strings that each code snippet is enclosed in.
-
- \target defines-variable
- \section1 defines
-
- The \c defines variable specifies the C++ preprocessor symbols
- that QDoc will recognize and respond to.
-
- When a preprocessor symbol is specified using the \c defines
- variable, you can also use the \l {if-command} {\\if} command to
- enclose documentation that only will be included if the
- preprocessor symbol is defined.
-
- The values of the variable are regular expressions (see QRegExp
- for details). By default, no symbol is defined, meaning that code
- protected with #ifdef...#endif will be ignored.
-
- \badcode
- defines = Q_QDOC \
- QT_.*_SUPPORT \
- QT_.*_LIB \
- QT_COMPAT \
- QT3_SUPPORT \
- Q_OS_.* \
- Q_BYTE_ORDER \
- __cplusplus
- \endcode
-
- This ensures that QDoc will process the code that requires these
- symbols to be defined. For example:
-
- \code
- #ifdef Q_OS_WIN
- HDC getDC() const;
- void releaseDC(HDC) const;
- #endif
- \endcode
-
- 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
- line using the -D option. For example:
-
- \badcode
- currentdirectory$ qdoc -Dconsoleedition qtgui.qdocconf
- \endcode
-
- In this case the -D option ensures that the \c consoleedition
- preprocessor symbol is defined when QDoc processes the source
- files defined in the qtgui.qdocconf file.
-
- See also \l {falsehoods-variable} {falsehoods} and \l {if-command} {\\if}.
-
- \target edition-variable
- \section1 edition
-
- The \c edition variable specifies which modules are included in
- each edition of a package, and provides QDoc with information to
- provide class lists for each edition.
-
- This feature is mostly used when providing documentation for Qt
- packages.
-
- The \c edition variable is always used with a particular edition
- name to define the modules for that edition:
-
- \badcode
- edition.Console = QtCore QtNetwork QtSql QtXml
- edition.Desktop = QtCore QtGui QtNetwork QtOpenGL QtSql QtXml \
- QtDesigner QtAssistant Qt3Support QAxContainer \
- QAxServer
- edition.DesktopLight = QtCore QtGui Qt3SupportLight
- \endcode
-
- In the above examples, the \c Console edition only includes the
- contents of four modules. Only the classes from these modules will
- be used when the \l{Miscellaneous#generatelist-command}
- {generatelist} command is used to generate a list of classes for
- this edition:
-
- \badcode
- \generatelist{classesbyedition Console}
- \endcode
-
- \target exampledirs-variable
- \section1 exampledirs
-
- The \c exampledirs variable specifies the directories containing
- the source code of the example files.
-
- The \l {examples-variable} {examples} and \l
- {exampledirs-variable} {exampledirs} variables are used by the \l
- {quotefromfile-command} {\\quotefromfile}, \l {quotefile-command}
- {\\quotefile} and \l {example-command} {\\example} commands. If
- both the \l {examples-variable} {examples} and \l
- {exampledirs-variable} {exampledirs} variables are defined, QDoc
- will search in both, first in \l {examples-variable} {examples}
- then in \l {exampledirs-variable} {exampledirs}.
-
- QDoc will search through the directories in the specified order,
- and accept the first matching file it finds. It will only search
- in the specified directories, \e not in subdirectories.
-
- \badcode
- exampledirs = $QTDIR/doc/src \
- $QTDIR/examples \
- $QTDIR \
- $QTDIR/qmake/examples
-
- examples = $QTDIR/examples/widgets/analogclock/analogclock.cpp
- \endcode
-
- When processing
-
- \badcode
- \quotefromfile widgets/calculator/calculator.cpp
- \endcode
-
- QDoc will see if there is a file called \c calculator.cpp
- listed as a value in the \l {examples-variable} {\c examples} variable. If
- there isn't, it will search in the \c exampledirs variable, and
- first see if there exists a file called
-
- \badcode
- $QTDIR/doc/src/widgets/calculator/calculator.cpp
- \endcode
-
- If it doesn't, QDoc will continue looking for a file called
-
- \badcode
- $QTDIR/examples/widgets/calculator/calculator.cpp
- \endcode
-
- and so forth.
-
- See also \l {examples-variable}{examples}.
-
- \target examples-variable
- \section1 examples
-
- The \c examples variable allows you to specify individual example
- files in addition to those located in the directories specified by
- the \l {exampledirs-variable} {\c exampledirs} variable.
-
- The \c examples and \l {exampledirs-variable} {\c exampledirs}
- variables are used by the \l {quotefromfile-command}
- {\\quotefromfile}, \l {quotefile-command} {\\quotefile} and \l
- {example-command} {\\example} commands. If both the \c examples and \l
- {exampledirs-variable} {\c exampledirs} variables are defined,
- QDoc will search in both, first in \c examples then in \l
- {exampledirs-variable} {\c exampledirs}.
-
- QDoc will search through the values listed for the \c examples
- variable, in the specified order, and accept the first one it
- finds.
-
- For an extensive example, see the \l {exampledirs-variable} {\c
- 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:
-
- \badcode
- \quotefromfile calculator.cpp
- \endcode
-
- See also \l {exampledirs-variable} {exampledirs}.
-
- \target examples.fileextensions-variable
- \section1 examples.fileextensions
-
- The \c examples.fileextensions variable specifies the file
- extensions that qdoc will look for when collecting example files
- for display in the documentation.
-
- The default extensions are *.cpp, *.h, *.js, *.xq, *.svg, *.xml
- and *.ui.
-
- The extensions are given as standard wildcard expressions. You
- can add a file extension to the filter using '+='. For example:
-
- \badcode
- examples.fileextensions += *.qrc
- \endcode
-
- See also \l{headers.fileextensions}.
-
- \target excludedirs-variable
- \section1 excludedirs
-
- The \c excludedirs variable is for listing directories that should \e{not}
- be processed by qdoc, even if the same directories are included by the
- \l {sourcedirs-variable} {sourcedirs} or \l {headerdirs-variable} {headerdirs}
- variables.
-
- For example:
-
- \badcode
- sourcedirs = src/corelib
- excludedirs = src/corelib/tmp
- \endcode
-
- When executed, QDoc will exclude the listed directories from
- further consideration. Files in these directories will not be
- read by qdoc.
-
- See also \l {excludefiles-variable} {excludefiles}.
-
- \target excludefiles-variable
- \section1 excludefiles
-
- The \c excludefiles variable allows you to specify individual files
- that should \e{not} be processed by qdoc.
-
- \badcode
- excludefiles += $QT_CORE_SOURCES/../../src/widgets/kernel/qwidget.h \
- $QT_CORE_SOURCES/../../src/widgets/kernel/qwidget.cpp
- \endcode
-
- If you include the above in your qdocconf file for qtbase, there
- will be no qwidget.html generated for html and no qwidget.xml
- generated for DITA XML.
-
- See also \l {excludedirs-variable} {excludedirs}.
-
- \target extraimages-variable
- \section1 extraimages
-
- The \c extraimages variable tells QDoc to incorporate specific
- images in the generated documentation.
-
- QDoc will not recognize images used within HTML (or any other
- markup language). If we want the images to be copied from the
- directories specified by \l {imagedirs} {\c imagedirs} (the images
- in question must be located in these directories) to the output
- directory, we must specify the images using the \c extraimages
- variable.
-
- The general syntax is \tt {extraimages.\e{format} = \e image}. The
- file extension is optional.
-
- For example, in \l qtgui.qdocconf we use a couple of images within
- the HTML.postheader variable which value is pure HTML. For that
- reason, these images are specified using the \c extraimages
- variable:
-
- \badcode
- extraimages.HTML = qt-logo
- \endcode
-
- See also \l images and \l imagedirs.
-
- \target falsehoods-variable
- \section1 falsehoods
-
- The \c falsehoods variable defines the truth value of specified
- preprocessor symbols as false.
-
- If this variable is not set for a preprocessor symbol, QDoc
- assumes its truth value is true. The exception is '0', which value
- always is false.
-
- QDoc will recognize, and is able to evaluate, the following
- preprocessor syntax:
-
- \code
- #ifdef NOTYET
- ...
- #endif
-
- #if defined (NOTYET)
- ...
- #end if
- \endcode
-
- However, faced with unknown syntax like
-
- \code
- #if NOTYET
- ...
- #endif
- \endcode
-
- QDoc will evaluate it as true by default, \e unless the
- preprocessor symbol is specified within the \c falsehoods variable
- entry:
-
- \badcode
- falsehoods = NOTYET
- \endcode
-
- See also \l defines.
-
- \target generateindex-variable
- \section1 generateindex
-
- The \c generateindex variable contains a boolean value that
- specifies whether to generate an index file when HTML
- documentation is generated.
-
- By default, an index file is always generated with HTML
- documentation, so this variable is typically only used when
- disabling this feature (by setting the value to \c false) or when
- enabling index generation for the WebXML output (by setting the
- value to \c true).
-
- \target headerdirs-variable
- \section1 headerdirs
-
- The \c headerdirs variable specifies the directories containing
- the header files associated with the \c .cpp source files used in
- the documentation.
-
- \badcode
- headerdirs = $QTDIR/src \
- $QTDIR/extensions/activeqt \
- $QTDIR/extensions/motif \
- $QTDIR/tools/designer/src/lib/extension \
- $QTDIR/tools/designer/src/lib/sdk \
- $QTDIR/tools/designer/src/lib/uilib
- \endcode
-
- When executed, the first thing QDoc will do is to read through the
- headers specified in the \l {headers} {\c headers} variable, and
- the ones located in the directories specified in the \c headerdir
- variable (including all subdirectories), building an internal
- structure of the classes and their functions.
-
- Then it will read through the sources specified in the \l
- {sources-variable} {\c sources}, and the ones located in the
- directories specified in the \l {sourcedirs-variable} {\c
- sourcedirs} varible (including all subdirectories), merging the
- documentation with the structure it retrieved from the header
- files.
-
- If both the \c headers and \c headerdirs variables are defined,
- QDoc will read through both, first \l {headers} {\c headers} then
- \c headerdirs.
-
- In the specified directories, QDoc will only read the files with
- the \c fileextensions specified in the \l {headers.fileextensions}
- {\c headers.fileextensions} variable. The default extensions are
- *.ch, *.h, *.h++, *.hh, *.hpp, and *.hxx". The files specified by
- \l {headers} {\c headers} will be read without taking into account
- their fileextensions.
-
- See also \l headers and \l headers.fileextensions.
-
- \target headers-variable
- \section1 headers
-
- The \c headers variable allows you to specify individual header
- files in addition to those located in the directories specified by
- the \l {headerdirs} {\c headerdirs} variable.
-
- \badcode
- headers = $QTDIR/src/gui/widgets/qlineedit.h \
- $QTDIR/src/gui/widgets/qpushbutton.h
- \endcode
-
- When processing the \c headers variable, QDoc behaves in the same
- way as it does when processing the \l {headerdirs} {\c headerdirs}
- variable. For more information, see the \l {headerdirs} {\c
- headerdirs} variable.
-
- See also \l headerdirs.
-
- \target headers.fileextensions-variable
- \section1 headers.fileextensions
-
- The \c headers.fileextensions variable specify the extension used
- by the headers.
-
- When processing the header files specified in the \l {headerdirs}
- {\c headerdirs} variable, QDoc will only read the files with the
- fileextensions specified in the \c headers.fileextensions
- variable. In this way QDoc avoids spending time reading irrelevant
- files.
-
- The default extensions are *.ch, *.h, *.h++, *.hh, *.hpp, and
- *.hxx.
-
- The extensions are given as standard wildcard expressions. You
- can add a file extension to the filter using '+='. For example:
-
- \badcode
- header.fileextensions += *.H
- \endcode
-
- \warning The above assignment may not work as described.
-
- See also \l headerdirs.
-
- \target imagedirs-variable
- \section1 imagedirs
-
- The \c imagedirs variable specifies the directories containing the
- images used in the documentation.
-
- The \l {images} {\c images} and \c imagedirs variables are used by
- the \l {image-command} {\\image} and \l {inlineimage-command}
- {\\inlineimage} commands. If both the \l {images} {\c images} and
- \c imagedirs variables are defined, QDoc will search in both. First
- in \l {images} {\c images}, then in \c imagedirs.
-
- QDoc will search through the directories in the specified order,
- and accept the first matching file it finds. It will only search
- in the specified directories, \e not in subdirectories.
-
- \badcode
- imagedirs = $QTDIR/doc/src/images \
- $QTDIR/examples
-
- images = $QTDIR/doc/src/images/calculator-example.png
- \endcode
-
- When processing
-
- \badcode
- \image calculator-example.png
- \endcode
-
- QDoc will then see if there is a file called
- calculator-example.png listed as a value in the \c images
- variable. If there isn't, it will search in the \c imagedirs
- variable for:
-
- \badcode
- $QTDIR/doc/src/images/calculator-example.png
- \endcode
-
- If the file doesn't exist, QDoc will look for a file called
-
- \badcode
- $QTDIR/examples/calculator-example.png
- \endcode
-
- You can filter the images in an image directory using the \l
- {images.fileextensions} {\c images.fileextensions} variable. The
- general idea behind the \l {images.fileextensions} {\c images.fileextensions}
- variable is to enable different image format for different output format.
-
- \warning The \l {images.fileextensions} {\c images.fileextensions}
- variable's functionality is preliminary since QDoc at this point
- only supports HTML.
-
- See also \l images and \l images.fileextensions.
-
- \target images-variable
- \section1 images
-
- The \c images variable allows you to specify individual image
- files in addition to those located in the directories specified by
- the \l {imagedirs} {\c imagedirs} variable.
-
- \badcode
- images = $QTDIR/doc/src/images/calculator-example.png
- \endcode
-
- When processing the \c images variable, QDoc behaves in the same
- way as it does when processing the \l {imagedirs} {\c imagedirs}
- variable. For more information, see the \l {imagedirs} {\c
- imagedirs} variable.
-
- See also \l imagedirs and \l images.fileextensions.
-
- \target images.fileextensions-variable
- \section1 images.fileextensions
-
- The images.fileextensions variable filters the files within an
- image directory.
-
- The variable's values (the extensions) are given as standard
- wildcard expressions. The general syntax is: \tt
- {images.fileextensions.\e{format} = *.\e{extension}}.
-
- The idea is to enable different image format for different output
- format.
-
- \badcode
- images.fileextensions.HTML = *.png
- images.fileextensions.LOUT = *.eps
- \endcode
-
- Then, when processing the \l {image-command} {\\image} and \l
- {inlineimage-command} {\\inlineimage} commands, QDoc will only
- search for files with extensions specified in the variable
- containing the list of output formats.
-
- \warning This is only a preliminary functionality since QDoc at this
- point only supports HTML.
-
- The default extensions for HTML are *.png, *.jpg, *.jpeg, and
- *.gif.
-
- You can add a file extension to the filter using '+='. For
- example:
-
- \badcode
- images.fileextensions.HTML += *.eps
- \endcode
-
- See also \l imagedirs and \l images.
-
- \target language-variable
- \section1 language
-
- The \c language variable specifies the language of the source code
- that is used in the documentation.
-
- Currently, C++ is the only language that QDoc understands. It is
- also the default language, and doesn't really need to be
- specified. However, a possible example of a language variable
- statement:
-
- \badcode
- language = Cpp
- \endcode
-
- This identifies C++ as the language of the Qt source code.
-
- \target macro-variable
- \section1 macro
-
- The \c macro variable is used to create your own simple QDoc
- commands. The syntax is \tt {macro.\e{command} = \e{definition}},
- where the definition is written using QDoc syntax.
-
- A macro variable can be restricted for use in one type of output
- generation. By appending \c {.HTML} to the macro name, for
- example, the macro is only used when generating HTML output. By
- appending \c {.DITAXML} to the macro name, the macro is only used
- when generating DITA XML.
-
- \badcode
- macro.gui = "\\b"
- macro.raisedaster.HTML = "<sup>*</sup>"
- \endcode
-
- The first macro defines the \\gui command to render its argument
- using a bold font. The second macro defines the \\raisedaster
- command to render a superscript asterisk, but only when generating
- HTML.
-
- A macro can also take up to seven parameters:
-
- \badcode
- macro.hello = "Hello \1!"
- \endcode
-
- Parameters are passed to macros the same way as to other commands:
-
- \badcode
- \hello World
- \endcode
-
- See also \l {alias-variable} {alias}.
-
- \target manifestmeta-variable
- \section1 manifestmeta
-
- The \c manifestmeta variable specifies additional meta-content
- for the example manifest files generated by QDoc.
-
- See the \l{Manifest Meta Content} section for more information.
-
- \target naturallanguage-variable
- \section1 naturallanguage
-
- The \c naturallanguage variable specifies the natural language
- used for the documentation generated by qdoc.
-
- \badcode
- naturallanguage = zh-Hans
- \endcode
-
- By default, the natural language is \c en for compatibility with
- legacy documentation.
-
- qdoc will add the natural language information to the HTML it
- generates, using the \c lang and \c xml:lang attributes.
-
- See also \l {sourceencoding-variable} {sourceencoding},
- \l {outputencoding-variable} {outputencoding},
- \l{http://www.w3.org/TR/xhtml1/#C_7}
- {C.7. The lang and xml:lang Attributes} and
- \l{http://www.w3.org/TR/i18n-html-tech-lang/#ri20040429.113217290}
- {Best Practice 13: Using Hans and Hant codes}.
-
- \target outputdir-variable
- \section1 outputdir
-
- The \c outputdir variable specifies the directory where QDoc will
- put the generated documentation.
-
- \badcode
- outputdir = $QTDIR/doc/html
- \endcode
-
- locates the generated Qt reference documentation in
- $QTDIR/doc/html. For example, the documentation of the QWidget
- class is located in
-
- \badcode
- $QTDIR/doc/html/qwidget.html
- \endcode
-
- The associated images will be put in an \c images subdirectory.
-
- \warning When running QDoc multiple times using the same output
- directory, all files from the previous run will be lost.
-
- \target outputencoding-variable
- \section1 outputencoding
-
- The \c outputencoding variable specifies the encoding used for the
- documentation generated by qdoc.
-
- \badcode
- outputencoding = UTF-8
- \endcode
-
- By default, the output encoding is \c ISO-8859-1 (Latin1) for
- compatibility with legacy documentation. When generating
- documentation for some languages, particularly non-European
- languages, this is not sufficient and an encoding such as UTF-8 is
- required.
-
- qdoc will encode HTML using this encoding and generate the correct
- declarations to indicate to browsers which encoding is being
- used. The \l naturallanguage configuration variable should also be
- specified to provide browsers with a complete set of character
- encoding and language information.
-
- See also \l outputencoding and \l naturallanguage.
-
- \target outputformats-variable
- \section1 outputformats
-
- The \c outputformats variable specifies the format of
- the generated documentation.
-
- Currently, QDoc only supports the HTML format. It is also
- the default format, and doesn't need to be specified.
-
- \target outputprefixes-variable
- \section1 outputprefixes
-
- The \c outputprefixes variable specifies a mapping between types of files
- and the prefixes to prepend to the HTML file names in the generated
- documentation.
-
- \badcode
- outputprefixes = QML JS
- outputprefixes.QML = uicomponents-
- outputprefixes.JS = uicomponents-
- \endcode
-
- By default, files containing the API documentation for QML types
- are prefixed with "qml-", and javaScript types with "js-". In the
- above example, the prefix \c "uicomponents" is used instead for
- both.
-
- The output prefix is applied to file names for documentation on
- QML and JS types.
-
- \target outputsuffixes-variable
- \section1 outputsuffixes
-
- The \c outputsuffixes variable specifies a mapping between types of
- files and module name suffixes to append to the HTML file names.
-
- \badcode
- outputsuffixes = QML
- outputsuffixes.QML = -tp
- \endcode
-
- Given a QML module name \e FooBar and the default
- \l {outputprefixes-variable}{output prefix} ("qml-"), the file name of
- the generated HTML page for a QML type \e FooWidget would be
- \c qml-foobar-tp-foowidget.html.
-
- By default, no suffix is used. The output suffix, if defined, is applied
- to file names for documentation on QML and JS types, and their respective
- module pages.
-
- The \c outputsuffixes variable was introduced in QDoc 5.6.
-
- \target qhp-variable
- \section1 qhp
-
- The \c qhp variable is used to define the information to be
- written out to Qt Help Project (\c{qhp}) files.
-
- See the \l{Creating Help Project Files} chapter for information
- about this process.
-
- \target sourcedirs-variable
- \section1 sourcedirs
-
- The \c sourcedirs variable specifies the directories containing
- the \c .cpp or \c .qdoc files used in the documentation.
-
- \badcode
- sourcedirs += .. \
- ../../../examples/gui/doc/src
- \endcode
-
- When executed, the first thing QDoc will do is to read through the
- headers specified in the \l {header-command} {\c header} variable,
- and the ones located in the directories specified in the \c
- headerdir variable (including all subdirectories), building an
- internal structure of the classes and their functions.
-
- Then it will read through the sources specified in the \l
- {sources} {\c sources}, and the ones located in the directories
- specified in the \l {sourcedirs} {\c sourcedirs} variable
- (including all subdirectories), merging the documentation with the
- structure it retrieved from the header files.
-
- If both the \c sources and \c sourcedirs variables are defined,
- QDoc will read through both, first \l {sources} {\c sources} then
- \c sourcedirs.
-
- In the specified directories, QDoc will only read the files with
- the \c fileextensions specified in the \l {sources.fileextensions}
- {\c sources.fileextensions} variable. The default extensions are
- *.c++, *.cc, *.cpp and *.cxx. The files specified by \l {sources}
- {\c sources} will be read independent of their fileextensions.
-
- See also \l {sources-variable} {sources} and
- \l {sources.fileextensions-variable} {sources.fileextensions}.
-
- \target sourceencoding-variable
- \section1 sourceencoding
-
- The \c sourceencoding variable specifies the encoding used for the
- source code and documentation.
-
- \badcode
- sourceencoding = UTF-8
- \endcode
-
- By default, the source encoding is \c ISO-8859-1 (Latin1) for
- compatibility with legacy documentation. For some languages,
- particularly non-European languages, this is not sufficient and an
- encoding such as UTF-8 is required.
-
- Although qdoc will use the encoding to read source and
- documentation files, limitations of C++ compilers may prevent you
- from using non-ASCII characters in source code comments. In cases
- like these, it is possible to write API documentation completely
- in documentation files.
-
- See also \l {naturallanguage-variable} {naturallanguage} and
- \l {outputencoding-variable} {outputencoding}.
-
- \target sources-variable
- \section1 sources
-
- The \c sources variable allows you to specify individual source
- files in addition to those located in the directories specified by
- the \l {sourcedirs-variable} {sourcedirs} variable.
-
- \badcode
- sources = $QTDIR/src/gui/widgets/qlineedit.cpp \
- $QTDIR/src/gui/widgets/qpushbutton.cpp
- \endcode
-
- When processing the \c sources variable, QDoc behaves in the same
- way as it does when processing the \l {sourcedirs-variable}
- {sourcedirs} variable. For more information, see the \l
- {sourcedirs-variable} {sourcedirs} variable.
-
- See also \l {sourcedirs-variable} {sourcedirs}.
-
- \target sources.fileextensions-variable
- \section1 sources.fileextensions
-
- The \c sources.fileextensions variable filters the files within a
- source directory.
-
- When processing the source files specified in the \l {sourcedirs}
- {\c sourcedirs} variable, QDoc will only read the files with the
- fileextensions specified in the \c sources.fileextensions
- variable. In this way QDoc avoid spending time reading irrelevant
- files.
-
- The default extensions are *.c++, *.cc, *.cpp and *.cxx.
-
- The extensions are given as standard wildcard expressions. You
- can add a file extension to the filter using '+='. For example:
-
- \badcode
- sources.fileextensions += *.CC
- \endcode
-
- \warning The above assignment may not work as described.
-
- See also \l {sourcedirs-variable} {sourcedirs} and \l
- (sources-variable} {sources}.
-
-
- \target spurious-variable
- \section1 spurious
-
- The \c spurious variable excludes specified QDoc warnings from the
- output. The warnings are specified using standard wildcard
- expressions.
-
- \badcode
- spurious = "Cannot find .*" \
- "Missing .*"
- \endcode
-
- makes sure that warnings matching either of these expressions,
- will not be part of the output when running QDoc. For example
- would the following warning be omitted from the output:
-
- \badcode
- src/opengl/qgl_mac.cpp:156: Missing parameter name
- \endcode
-
- \target syntaxhighlighting
- \section1 syntaxhighlighting
-
- The \c syntaxhighlighting variable specifies whether QDoc should
- perform syntax highlighting on source code quoted in the
- documentation it generates.
-
- \badcode
- syntaxhighlighting = true
- \endcode
-
- will enable syntax highlighting for all supported programming
- languages.
-
- \target tabsize-variable
- \section1 tabsize
-
- The \c tabsize variable defines the size of a tab character.
-
- \badcode
- tabsize = 4
- \endcode
-
- will give the tab character the size of 4 spaces. The default
- value of the variable is 8, and doesn't need to be specified.
-
- \target tagfile-variable
- \section1 tagfile
-
- The \c tagfile variable specifies the Doxygen tag file to be
- written when HTML is generated.
-
- \target version-variable
- \section1 version
-
- The \c version variable specifies the version number of the
- documented software.
-
- \badcode
- version = 5.6.0
- \endcode
-
- When a version number is specified (using the \tt{\l version} or
- \tt {\l versionsym} variables in a \c .qdocconf file), it is
- accessible through the corresponding \\version command for use in
- the documentation.
-
- \warning The \\version command's functionality is not fully
- implemented; currently it only works within raw HTML code.
-
- See also \l versionsym.
-
- \target versionsym-variable
- \section1 versionsym
-
- The \c versionsym variable specifies a C++ preprocessor symbol
- that defines the version number of the documented software.
-
- \badcode
- versionsym = QT_VERSION_STR
- \endcode
-
- QT_VERSION_STR is defined in qglobal.h as follows
-
- \badcode
- #define QT_VERSION_STR "4.0.1"
- \endcode
-
- When a version number is specified (using the \tt{\l version} or
- \tt {\l versionsym} variables in a \c .qdocconf file), it is
- accessible through the corresponding \\version command for use in
- the documentation.
-
- \warning The \\version command's functionality is not fully
- implemented. Currently, it only works within raw HTML code.
-
- See also \l {version} {\\version}.
-*/
-
-/*!
- \page 22-creating-help-project-files.html
- \previouspage Generic Configuration Variables
- \contentspage QDoc Manual
- \nextpage C++ Specific Configuration Variables
-
- \title Creating Help Project Files
-
- \section1 Overview
-
- Qt Assistant uses a system for managing Qt documentation that requires
- QDoc to generate inventories of files in a format that is similar to the
- old style DCF format, but with additional features.
-
- QDoc allows configuration variables to be used to specify which pages are
- to be used in each documentation set it generates. These are specified as
- subvariables of the \c qhp variable with each set declared using a unique
- identifier as a subvariable.
-
- For example, the configuration file for the Qt Quick documentation set
- specifies information about the set as subvariables with the
- \c{qhp.QtQuick} prefix:
-
- \badcode
- qhp.projects = QtQuick
-
- qhp.QtQuick.file = qtquick.qhp
- qhp.QtQuick.namespace = org.qt-project.qtquick.$QT_VERSION_TAG
- qhp.QtQuick.virtualFolder = qtquick
- qhp.QtQuick.indexTitle = Qt Quick
- qhp.QtQuick.indexRoot =
-
- qhp.QtQuick.filterAttributes = qtquick $QT_VERSION qtrefdoc
- qhp.QtQuick.customFilters.Qt.name = QtQuick $QT_VERSION
- qhp.QtQuick.customFilters.Qt.filterAttributes = qtquick $QT_VERSION
-
- qhp.QtQuick.subprojects = qmltypes classes examples
-
- qhp.QtQuick.subprojects.qmltypes.title = QML Types
- qhp.QtQuick.subprojects.qmltypes.indexTitle = Qt Quick QML Types
- qhp.QtQuick.subprojects.qmltypes.selectors = qmlclass
- qhp.QtQuick.subprojects.qmltypes.sortPages = true
-
- qhp.QtQuick.subprojects.classes.title = Classes
- qhp.QtQuick.subprojects.classes.title = C++ Classes
- qhp.QtQuick.subprojects.classes.indexTitle = Qt Quick C++ Classes
- qhp.QtQuick.subprojects.classes.selectors = class fake:headerfile
- qhp.QtQuick.subprojects.classes.sortPages = true
-
- qhp.QtQuick.subprojects.examples.title = Examples
- qhp.QtQuick.subprojects.examples.indexTitle = Qt Quick Examples and Tutorials
- qhp.QtQuick.subprojects.examples.selectors = fake:example
- \endcode
-
- The documentation set may include one or more subprojects, which are added
- to the table of contents under the name specified by \c title. The page
- in the documentation referred to by the \c indexTitle acts as the index page
- for the subproject. The page types to list under the subproject are specified
- by \c selectors. The entries are alphabetically sorted if \c sortPages is set
- to \c true.
-
- \section2 Using Selectors
-
- The \c selectors property specifies which page types are listed under the
- table of contents entry for a subproject. Multiple selectors can be listed,
- separated by whitespace.
-
- \table
- \header \li Selector \li Description
- \row \li \c namespace \li Namespaces
- \row \li \c class \li Classes
- \row \li \c qmltype \li QML Types
- \row \li \c qmlclass \li Alias for \c qmltype.
- \row \li \c module \li C++ Modules
- \row \li \c qmlmodule \li QML Modules
- \row \li \c doc[:subtype] \li Documentation pages with a specified
- \c subtype. Multiple subtypes can be
- listed as a comma-separated list.
- \row \li \c fake \li Alias for \c doc.
- \row \li \c group[:groupname] \li Documentation pages for members of a
- specified group, as added using the
- \l {ingroup-command}
- {\\ingroup} groupname command.
- Multiple group names can be listed as
- a comma-separated list.
- (Introduced in QDoc 5.6).
- \endtable
-
- Available subtypes for the \c doc selector:
-
- \table
- \header \li Subtype \li Description
- \row \li \c example \li Examples
- \row \li \c headerfile \li Header files
- \row \li \c page \li Documentation pages defined with the
- \l {page-command} {\\page} command.
- \endtable
-
- For example, the following configuration would select example pages and
- pages that include the \c {\ingroup tutorials} command:
-
- \badcode
- qhp.QtQuickControls.subprojects = examples
- qhp.QtQuickControls.subprojects.examples.title = Examples and Tutorials
- qhp.QtQuickControls.subprojects.examples.indexTitle = Qt Quick Controls Examples
- qhp.QtQuickControls.subprojects.examples.selectors = doc:example group:tutorials
- qhp.QtQuickControls.subprojects.examples.sortPages = true
- \endcode
-
- \section2 Adding Table of Contents
-
- To create a table of contents for a manual, create a subproject with
- a \c{type} property and set it to \c{manual}. The page in the documentation
- referred to by the \c{indexTitle} property must contain a list of links
- that acts as a table of contents for the whole manual. QDoc will take the
- information in this list and create a table of contents for the subproject.
-
- For example, the configuration file for Qt Creator defines only one
- subproject for its documentation, including all the documentation in a
- single manual:
-
- \badcode
- qhp.QtCreator.subprojects = manual
- qhp.QtCreator.subprojects.manual.title = Qt Creator Manual
- qhp.QtCreator.subprojects.manual.indexTitle = Qt Creator Manual
- qhp.QtCreator.subprojects.manual.type = manual
- \endcode
-
- In this example, the page entitled "Qt Creator Manual" contains a nested
- list of links to pages in the documentation which is duplicated in
- Qt Assistant's Contents tab.
-*/
-
-/*!
- \page 23-qdoc-configuration-cppvariables.html
- \previouspage Creating Help Project Files
- \contentspage QDoc Manual
- \nextpage HTML Specific Configuration Variables
-
- \title C++ Specific Configuration Variables
-
- The C++ specific configuration variables are provided to avoid
- erroneous documentation due to non-standard C++ constructs.
-
- \target Cpp.ignoredirectives-variable
- \section1 Cpp.ignoredirectives
- The \c Cpp.ignoredirectives variable makes QDoc ignore the
- specified non-standard constructs, within C++ source code.
-
- If not specified by the \tt {\l Cpp.ignoretokens} or \tt {\l
- Cpp.ignoredirectives} variables, non-standard constructs
- (typically macros) can result in erroneous documentation.
-
- \badcode
- Cpp.ignoredirectives = Q_DECLARE_INTERFACE \
- Q_DECLARE_OPERATORS_FOR_FLAGS \
- Q_DECLARE_PRIVATE \
- Q_DECLARE_PUBLIC \
- Q_DISABLE_COPY \
- Q_DUMMY_COMPARISON_OPERATOR \
- Q_ENUMS \
- Q_FLAGS \
- Q_INTERFACES \
- __attribute__
- \endcode
-
- makes sure that when processing the code below, for example, QDoc
- will simply ignore the 'Q_ENUMS' and 'Q_FLAGS' expressions:
-
- \code
- class Q_CORE_EXPORT Qt {
- Q_OBJECT
- Q_ENUMS(Orientation TextFormat BackgroundMode
- DateFormat ScrollBarPolicy FocusPolicy
- ContextMenuPolicy CaseSensitivity
- LayoutDirection ArrowType)
- Q_ENUMS(ToolButtonStyle)
- Q_FLAGS(Alignment)
- Q_FLAGS(Orientations)
- Q_FLAGS(DockWidgetAreas)
-
- public:
- ...
- };
- \endcode
-
- The Q_OBJECT macro, however, is an exception: QDoc recognizes this
- particular non-standard construct, so there is no need specifying
- it using the \tt {\l Cpp.ignoredirectives} variable.
-
- Regarding the Q_CORE_EXPORT macro; see the documentation of the
- \tt {\l Cpp.ignoretokens} variable.
-
- See also \l Cpp.ignoretokens.
-
- \target Cpp.ignoretokens-variable
- \section1 Cpp.ignoretokens
-
- The \c Cpp.ignoretokens variable makes QDoc ignore the specified
- non-standard constructs, within C++ source code.
-
- If not specified by the \tt {\l Cpp.ignoretokens} or \tt {\l
- Cpp.ignoredirectives} variables, non-standard constructs
- (typically macros) can result in erroneous documentation.
-
- In \l qtgui.qdocconf:
-
- \badcode
- Cpp.ignoretokens = QAXFACTORY_EXPORT \
- QM_EXPORT_CANVAS \
- ...
- Q_COMPAT_EXPORT \
- Q_CORE_EXPORT \
- Q_EXPLICIT \
- Q_EXPORT \
- ...
- Q_XML_EXPORT
- \endcode
-
- makes sure that when processing the code below, for example, QDoc
- will simply ignore the 'Q_CORE_EXPORT' expression:
-
- \code
- class Q_CORE_EXPORT Qt {
- Q_OBJECT
- Q_ENUMS(Orientation TextFormat BackgroundMode
- DateFormat ScrollBarPolicy FocusPolicy
- ContextMenuPolicy CaseSensitivity
- LayoutDirection ArrowType)
- Q_ENUMS(ToolButtonStyle)
- Q_FLAGS(Alignment)
- Q_FLAGS(Orientations)
- Q_FLAGS(DockWidgetAreas)
- public:
- ...
- };
- \endcode
-
- Regarding the Q_OBJECT, Q_ENUMS and Q_FLAGS macros; see the
- documentation of the \tt {\l Cpp.ignoredirectives} variable.
-
- See also \l Cpp.ignoredirectives.
-*/
-
-/*!
- \page 24-qdoc-configuration-htmlvariables.html
- \previouspage C++ Specific Configuration Variables
- \contentspage QDoc Manual
- \nextpage Supporting Derived Projects
-
- \title HTML Specific Configuration Variables
-
- The HTML specific configuration variables define the generated
- documentation's style, or define the contents of the
- documentation's footer or postheader. The format of the variable
- values are raw HTML.
-
- \target HTML.footer-variable
- \section1 HTML.footer
-
- The \c HTML.footer variable defines the content of the generated
- HTML documentation's footer.
-
- The footer is rendered at the bottom of the generated
- documentation page.
-
- The variable's value is given as raw HTML code enclosed by
- quotation marks. Note that if the value spans several lines, each
- line needs to be enclosed by quotation marks.
-
- \badcode
- HTML.footer = "<p /><address><hr /><div align=\"center\">\n" \
- ...
- "</tr></table></div></address>"
- \endcode
-
- \target HTML.postheader-variable
- \section1 HTML.postheader
-
- The \c HTML.postheader variable defines the content of the
- generated HTML documentation's postheader.
-
- The header is rendered at the top of the generated documentation
- page.
-
- The variable's value is given as raw HTML enclosed by quotation
- marks. Note that if the value spans several lines, each line needs
- to be enclosed by quotation marks.
-
- \badcode
- HTML.postheader = "<table border=\"0\"..." \
- ...
- "<img src=\"images/qt-logo.png\" \
- "align=\"right\" width=\"203\" height=\"32\""\
- "border=\"0\" />" \
- "</td></tr>" \
- "</table>"
- \endcode
-
- The complete variable entry in \l qtgui.qdocconf provides the
- standard header of the \l {http://doc.qt.io/qt-5/qtgui-index.html}
- {Qt GUI Documentation}.
-
- \target HTML.style-variable
- \section1 HTML.style
-
- The HTML.style variable defines the style for
- the generated HTML documentation.
-
- The variable's value is given as raw HTML enclosed by quotation
- marks. Note that if the value spans several lines, each line needs
- to be enclosed by quotation marks.
-
- \badcode
- HTML.style = "h3.fn,span.fn" \
- "{ margin-left: 1cm; text-indent: -1cm; }\n" \
- "a:link { color: #004faf; text-decoration: none }\n" \
- "a:visited" \
- "{ color: #672967; text-decoration: none }\n" \
- "td.postheader { font-family: sans-serif }\n" \
- "tr.address { font-family: sans-serif }\n" \
- "body { background: #ffffff; color: black; }"
- \endcode
-
- \target HTML.stylesheets-variable
- \section1 HTML.stylesheets
-
- The HTML.stylesheets variable defines a list of stylesheets
- to use for the generated HTML documentation.
-
- Using separate stylesheets for the documentation makes it easier
- to customize and experiment with the style used once the contents
- has been generated. Typically, it is only necessary to define a
- single stylesheet for any set of documentation; for example:
-
- \badcode
- HTML.stylesheets = classic.css
- \endcode
-
- QDoc expects to find stylesheets in the directory containing the
- \l qtgui.qdocconf file, and it will copy those specified to the output
- directory alongside the HTML pages.
-
- \target HTML.tocdepth
- \section1 HTML.tocdepth
-
- The HTML.tocdepth variable defines how many document sections are printed in
- the table of contents. Setting tocdepth to \c 0 disables the table of
- contents while not setting the variable prints all document sections.
-
-*/
-
-/*!
- \page 25-qdoc-configuration-derivedprojects.html
- \previouspage HTML Specific Configuration Variables
- \contentspage QDoc Manual
- \nextpage Example Manifest Files
-
- \title Supporting Derived Projects
-
- Some configuration variables allow you to use QDoc to support
- Qt-based projects. They allow your project to contain links to the
- online Qt documentation, which means that QDoc will be able to
- create links to the class reference documentation, without any
- explicit linking command.
-
- \target description-variable
- \section1 description
-
- The description variable holds a short description of the
- associated project.
-
- See also \l project.
-
- \target indexes-variable
- \section1 indexes
-
- The \c indexes variable lists the index files that will be used to
- generate references.
-
- For example. to make a derived Qt project contain links to the Qt
- Reference documentation, you need to specify the associated index
- file:
-
- \badcode
- indexes = $QTDIR/doc/html/qt.index
- \endcode
-
- See also \l project and \l url.
-
- \target project-variable
- \section1 project
-
- The \c project variable provides a name for the project associated
- with the \c .qdocconf file.
-
- The project's name is used to form a file name for the associated
- project's \e index file.
-
- \badcode
- project = QtCreator
- \endcode
-
- This will cause an index file called \c qtcreator.index to be
- created.
-
- See also \l description and \l indexes.
-
- \target url-variable
- \section1 url
-
- The \c url variable holds the base URL for the reference
- documentation associated with the current project.
-
- The URL is stored in the generated index file for the
- project. When we use the index on its own, QDoc will use this as
- the base URL when constructing links to classes, functions, and
- other things listed in the index.
-
- \badcode
- project = Qt
- description = Qt Reference Documentation
- url = http://doc.qt.io/qt-4.8/
-
- ...
- \endcode
-
- This makes sure that whenever \c qt.index is used to generate
- references to for example Qt classes, the base URL is \c
- http://doc.qt.io/qt-4.8/.
-
- See also \l indexes.
-
- \target howto
- \section1 How to Support Derived Projects
-
- This feature makes use of the comprehensive indexes generated by
- QDoc when it creates the Qt reference documentation.
-
- For example, \l qtgui.qdocconf (the configuration file for Qt)
- contains the following variable definitions:
-
- \badcode
- project = Qt
- description = Qt Reference Documentation
- url = http://doc.qt.io/qt-4.8/
-
- ...
- \endcode
-
- The \l project variable name is used to form a file name for the
- index file; in this case the \c qt.index file is created. The \l
- url is stored in the index file. Afterwards, QDoc will use this
- as the base URL when constructing links to classes, functions,
- and other things listed in the index.
-
-*/
-
-/*!
- \page 26-qdoc-configuration-example-manifest-files.html
- \previouspage Supporting Derived Projects
- \contentspage QDoc Manual
-
- \title Example Manifest Files
-
- QDoc generates XML files that contain information about all documented
- examples and demos. These files, named \c {examples-manifest.xml} and
- \c {demos-manifest.xml}, are used by Qt Creator to present a list of
- examples in its welcome screen and to link to their documentation.
-
- \section1 Manifest XML Structure
-
- A manifest file has the following structure:
-
- \badcode
- <?xml version="1.0" encoding="UTF-8"?>
- <instructionals module="QtGui">
- <examples>
- <example
- name="Analog Clock Window Example"
- docUrl="qthelp://org.qt-project.qtgui.502/qtgui/analogclock.html"
- projectPath="gui/analogclock/analogclock.pro"
- imageUrl="qthelp://org.qt-project.qtgui.502/qtgui/images/analogclock-window-example.png">
- <description><![CDATA[The Analog Clock Window example shows how
- to draw the contents of a custom window.]]></description>
- <tags>analog,clock,window</tags>
- <fileToOpen>gui/analogclock/main.cpp</fileToOpen>
- </example>
- ...
- </examples>
- </instructionals>
- \endcode
-
- Each \c {<example>} element contains information about a name,
- description, the location of the project file and documentation,
- as well as a list of tags associated with the example.
-
- \target metacontent
- \section1 Manifest Meta Content
-
- It is possible to augment the manifest files with additional
- meta-content - that is, extra attributes and tags for selected
- examples, using the \c manifestmeta configuration command.
-
- One use case for meta-content is highlighting a number of prominent
- examples. Another is improving search functionality by adding
- relevant keywords as tags for a certain category of examples.
-
- The examples for which meta-content is applied to is specified using
- one or more filters. Matching examples to filters is done based on
- names, with each example name prefixed with a module name and a
- slash. Simple wildcard matching is supported; by using \c {*} at the
- end it's possible to match multiple examples with a single string.
-
- Example:
-
- \badcode
- manifestmeta.filters = highlighted sql webkit global
-
- manifestmeta.highlighted.names = "QtGui/Analog Clock Window Example" \
- "QtWidgets/Analog Clock Example"
- manifestmeta.highlighted.attributes = isHighlighted:true
-
- manifestmeta.sql.names = "QtSql/*"
- manifestmeta.sql.tags = database,sql
-
- manifestmeta.webkit.names = "QtWebKitExamples/*"
- manifestmeta.webkit.tags = webkit
-
- manifestmeta.global.names = *
- manifestmeta.global.tags = qt5
- \endcode
-
- Above, an \c isHighlighted attribute is added to two examples. If
- the attribute value is omitted, QDoc uses the string \c {true} by
- default. Extra tags are added for Qt WebKit and Qt SQL examples, and
- another tag is applied to all examples by using just \c {*} as the
- match string.
-*/
-/*!
- \page 21-3-qt-dita-xml-output.html
- \previouspage minimum.qdocconf
- \contentspage QDoc Manual
- \nextpage QA Pages
-
- \title Generating DITA XML Output
-
- QDoc can generate \l {http://dita.xml.org} {DITA XML output}.
-
- In your configuration file, set your \c {outputformats} variable
- to \c {DITAXML}, and send the output to an appropriate directory:
-
- \badcode
- outputdir = $QTDIR/doc/ditaxml
- outputformats = DITAXML
- \endcode
-
- And include these macros in your configuration file to prevent
- QDoc from doing some escaping that doesn't validate in XML:
-
- \badcode
- macro.aacute.DITAXML = "&aacute;"
- macro.Aring.DITAXML = "&Aring;"
- macro.aring.DITAXML = "&aring;"
- macro.Auml.DITAXML = "&Auml;"
- macro.br.DITAXML = " "
- macro.BR.DITAXML = " "
- macro.copyright.DITAXML = "&copy;"
- macro.eacute.DITAXML = "&eacute;"
- macro.hr.DITAXML = " "
- macro.iacute.DITAXML = "&iacute;"
- macro.oslash.DITAXML = "&oslash;"
- macro.ouml.DITAXML = "&ouml;"
- macro.raisedaster.DITAXML = "<sup>*</sup>"
- macro.rarrow.DITAXML = "&rarr;"
- macro.reg.DITAXML = "<sup>&reg;</sup>"
- macro.uuml.DITAXML = "&uuml;"
- macro.mdash.DITAXML = "&mdash;"
- macro.emptyspan.DITAXML = " "
- \endcode
-
- You can also set default values for some of the tags in the DITA
- \c {<prolog>} and \c {<metadata>} elements:
-
- \badcode
- dita.metadata.default.author = Qt Development Frameworks
- dita.metadata.default.permissions = all
- dita.metadata.default.publisher = Qt Project
- dita.metadata.default.copyryear = 2015
- dita.metadata.default.copyrholder = Qt Project
- dita.metadata.default.audience = programmer
- \endcode
-
- See the \l {meta-command}
- {\\meta} command for more details on DITA metadata.
-
-*/
-
-
-/*!
- \page 21-1-minimum-qdocconf.html
- \previouspage qtgui.qdocconf
- \contentspage QDoc Manual
- \nextpage Generating DITA XML Output
-
- \title minimum.qdocconf
-
- \quotefile examples/minimum.qdocconf
-*/
-
-/*!
- \page 21-2-qtgui-qdocconf.html
- \previouspage Supporting Derived Projects
- \contentspage QDoc Manual
- \nextpage minimum.qdocconf
-
- \title qtgui.qdocconf
-
- \quotefile files/qtgui.qdocconf
-*/
diff --git a/src/tools/qdoc/doc/qdoc-manual-topiccmds.qdoc b/src/tools/qdoc/doc/qdoc-manual-topiccmds.qdoc
deleted file mode 100644
index 1dfd031633..0000000000
--- a/src/tools/qdoc/doc/qdoc-manual-topiccmds.qdoc
+++ /dev/null
@@ -1,1594 +0,0 @@
-/****************************************************************************
-**
-** Copyright (C) 2015 The Qt Company Ltd.
-** Contact: http://www.qt.io/licensing/
-**
-** This file is part of the documentation of the Qt Toolkit.
-**
-** $QT_BEGIN_LICENSE:FDL$
-** Commercial License Usage
-** Licensees holding valid commercial Qt licenses may use this file in
-** accordance with the commercial license agreement provided with the
-** Software or, alternatively, in accordance with the terms contained in
-** a written agreement between you and The Qt Company. For licensing terms
-** and conditions see http://www.qt.io/terms-conditions. For further
-** information use the contact form at http://www.qt.io/contact-us.
-**
-** GNU Free Documentation License Usage
-** Alternatively, this file may be used under the terms of the GNU Free
-** Documentation License version 1.3 as published by the Free Software
-** Foundation and appearing in the file included in the packaging of
-** this file. Please review the following information to ensure
-** the GNU Free Documentation License version 1.3 requirements
-** will be met: http://www.gnu.org/copyleft/fdl.html.
-** $QT_END_LICENSE$
-**
-****************************************************************************/
-
-/*!
- \page 13-qdoc-commands-topics.html
- \previouspage Command Index
- \contentspage QDoc Manual
- \nextpage Context Commands
-
- \title Topic Commands
-
- A topic command tells QDoc which source code element is being
- documented. Some topic commands allow you to create documentation
- pages that aren't tied to any underlying source code element.
-
- When QDoc processes a QDoc comment, it tries to connect the
- comment to an element in the source code by first looking for a
- topic command that names the source code element. If there is no
- topic command, QDoc tries to connect the comment to the source
- code element that immediately follows the comment. If it can't do
- either of these and if there is no topic command that indicates
- the comment does not have an underlying source code element (e.g.
- \l{page-command} {\\page}), then the comment is discarded.
-
- \target topic argument
-
- The name of the entity being documented is usually the only
- argument for a topic command. Use the complete name. Sometimes
- there can be a second parameter in the argument. See e.g. \l
- {page-command} {\\page}.
-
- \code
- \enum QComboBox::InsertPolicy
- \endcode
-
- The \l {fn-command} {\\fn} command is a special case. For the \l
- {fn-command} {\\fn} command, use the function's signature
- including the class qualifier.
-
- \code
- \fn void QGraphicsWidget::setWindowFlags(Qt::WindowFlags wFlags)
- \endcode
-
- A topic command can appear anywhere in a comment but must stand
- alone on its own line. It is good practice is to let the topic command
- be the first line of the comment. If the argument spans several
- lines, make sure that each line (except the last one) is ended
- with a backslash. Moreover, QDoc counts parentheses, which means
- that if it encounters a '(' it considers everything until the
- closing ')' as its argument.
-
- If a topic command is repeated with different arguments, the
- same documentation will appear for both the units.
-
- \code
- / *!
- \fn void PreviewWindow::setWindowFlags()
- \fn void ControllerWindow::setWindowFlags()
-
- Sets the widgets flags using the QWidget::setWindowFlags()
- function.
-
- Then runs through the available window flags, creating a text
- that contains the names of the flags that matches the flags
- parameter, displaying the text in the widgets text editor.
- * /
- \endcode
-
- The \c PreviewWindow::setWindowFlags() and \c
- ControllerWindow::setWindowFlags() functions will get the same
- documentation.
-
- \target class-command
- \section1 \\class
-
- The \\class command is for documenting a C++ class. The argument
- is the complete name of the class. The command tells QDoc that a
- class is part of the public API, and lets you enter a detailed
- description.
-
- \code
- / *!
- \class QMap::iterator
-
- \brief The QMap::iterator class provides an STL-style
- non-const iterator for QMap and QMultiMap.
-
- QMap features both \l{STL-style iterators} and
- \l{Java-style iterators}. The STL-style iterators ...
- * /
- \endcode
-
- The HTML documentation for the named class is written to a
- \c{.html} file named from the class name, in lower case, and with
- the double colon qualifier(s) replaced with '-'. For example, the
- documentation for the \c QMap::Iterator class is written to \c
- qmap-iterator.html.
-
- \target framework
-
- The file contains the class description from the \\class comment,
- plus the documentation generated from QDoc comments for all the
- class members: a list of the class's types, properties,
- functions, signals, and slots.
-
- In addition to the detailed description of the class, the \\class
- comment typically contains a \l {brief-command} {\\brief} command
- and one or more \l{Markup Commands}. See the \\class command for
- any of the Qt class for examples. Here is a very simple example:
-
- \code
- / *!
- \class PreviewWindow
- \brief The PreviewWindow class is a custom widget.
- displaying the names of its currently set
- window flags in a read-only text editor.
-
- \ingroup miscellaneous
-
- The PreviewWindow class inherits QWidget. The widget
- displays the names of its window flags set with the \l
- {function} {setWindowFlags()} function. It is also
- provided with a QPushButton that closes the window.
-
- ...
-
- \sa QWidget
- * /
- \endcode
-
- The way QDoc renders this \\class will depend a lot on your \c
- {style.css} file, but the general outline of the class reference
- page will look like this:
-
- \quotation
- \raw HTML
- <h1>PreviewWindow Class Reference</h1>
- \endraw
-
- The PreviewWindow class is a custom widget displaying
- the names of its currently set window flags in a
- read-only text editor. \l {preview window} {More...}
-
- \raw HTML
- <h3>Properties</h3>
- \endraw
-
- \list
- \li 52 properties inherited from QWidget
- \li 1 property inherited from QObject
- \endlist
-
- \raw HTML
- <h3>Public Functions</h3>
- \endraw
-
- \list
- \li \l {constructor} {PreviewWindow}(QWidget *parent = 0)
- \li void \l {function} {setWindowFlags}(Qt::WindowFlags flags)
- \endlist
-
- \list
- \li 183 public functions inherited from QWidget
- \li 28 public functions inherited from QObject
- \endlist
-
- \raw HTML
- <h3>Public Slots</h3>
- \endraw
-
- \list
- \li 17 public slots inherited from QWidget
- \li 1 public slot inherited from QObject
- \endlist
-
- \raw HTML
- <h3>Additional Inherited Members</h3>
- \endraw
-
- \list
- \li 1 signal inherited from QWidget
- \li 1 signal inherited from QObject
- \li 4 static public members inherited from QWidget
- \li 4 static public members inherited from QObject
- \li 39 protected functions inherited from QWidget
- \li 7 protected functions inherited from QObject
- \endlist
-
- \target preview window
-
- \raw HTML
- <hr />
- <h2>Detailed Description</h2>
- \endraw
-
- The PreviewWindow class is a custom widget displaying
- the names of its currently set window flags in a
- read-only text editor.
-
- The PreviewWindow class inherits QWidget. The widget
- displays the names of its window flags set with the \l
- {function} {setWindowFlags()} function. It is also
- provided with a QPushButton that closes the window.
-
- ...
-
- See also QWidget.
-
- \raw HTML
- <hr />
- <h2>Member Function Documentation</h2>
- \endraw
-
- \target constructor
- \raw HTML
- <h3>PreviewWindow(QWidget *parent = 0)</h3>
- \endraw
-
- Constructs a preview window widget with \e parent.
-
- \target function
- \raw HTML
- <h3>setWindowFlags(Qt::WindowFlags flags)</h3>
- \endraw
-
- Sets the widgets flags using the
- QWidget::setWindowFlags() function.
-
- Then runs through the available window flags,
- creating a text that contains the names of the flags
- that matches the flags parameter, displaying
- the text in the widgets text editor.
- \endquotation
-
- \target enum-command
- \section1 \\enum
-
- The \\enum command is for documenting a C++ enum type. The
- argument is the full name of the enum type.
-
- The enum values are documented in the \\enum comment using the \l
- {value-command} {\\value} command. If an enum value is not
- documented with \\value, QDoc emits a warning. These warnings can
- be avoided using the \l {omitvalue-command} {\\omitvalue} command
- to tell QDoc that an enum value should not be documented. The enum
- documentation will be included on the class reference page, header
- file page, or namespace page where the enum type is defined. For
- example, consider the enum type \c {Corner} in the Qt namespace:
-
- \code
- enum Corner {
- TopLeftCorner = 0x00000,
- TopRightCorner = 0x00001,
- BottomLeftCorner = 0x00002,
- BottomRightCorner = 0x00003
- #if defined(QT3_SUPPORT) && !defined(Q_MOC_RUN)
- ,TopLeft = TopLeftCorner,
- TopRight = TopRightCorner,
- BottomLeft = BottomLeftCorner,
- BottomRight = BottomRightCorner
- #endif
- };
- \endcode
-
- This enum can be cocumented this way:
-
- \code
- / *!
- \enum Qt::Corner
-
- This enum type specifies a corner in a rectangle:
-
- \value TopLeftCorner
- The top-left corner of the rectangle.
- \value TopRightCorner
- The top-right corner of the rectangle.
- \value BottomLeftCorner
- The bottom-left corner of the rectangle.
- \value BottomRightCorner
- The bottom-right corner of the rectangle.
-
- \omitvalue TopLeft
- \omitvalue TopRight
- \omitvalue BottomLeft
- \omitvalue BottomRight
- * /
- \endcode
-
- Note the inclusion of the namespace qualifier. QDoc will render
- this enum type in \c {qt.html} like this:
-
- \quotation
- \raw HTML
- <h3 class="fn"><a name="Corner-enum"></a>enum Qt::Corner</h3>
-
- <p>This enum type specifies a corner in a rectangle:</p>
-
- <table border="1" cellpadding="2" cellspacing="1" width="100%">
- <tr>
- <th width="25%">Constant</th>
- <th width="15%">Value</th>
- <th width="60%">Description</th>
- </tr>
-
- <tr>
- <td valign="top"><tt>Qt::TopLeftCorner</tt></td>
- <td align="center" valign="top"><tt>0x00000</tt></td>
- <td valign="top">The top-left corner of the rectangle.</td>
- </tr>
-
- <tr>
- <td valign="top"><tt>Qt::TopRightCorner</tt></td>
- <td align="center" valign="top"><tt>0x00001</tt></td>
- <td valign="top">The top-right corner of the rectangle.</td>
- </tr>
-
- <tr>
- <td valign="top"><tt>Qt::BottomLeftCorner</tt></td>
- <td align="center" valign="top"><tt>0x00002</tt></td>
- <td valign="top">The bottom-left corner of the rectangle.</td>
- </tr>
-
- <tr>
- <td valign="top"><tt>Qt::BottomRightCorner</tt></td>
- <td align="center" valign="top"><tt>0x00003</tt></td>
- <td valign="top">The bottom-right corner of the rectangle.</td>
- </tr>
-
- </table>
- \endraw
- \endquotation
-
- See also \l {value-command} {\\value} and \l {omitvalue-command} {\\omitvalue}.
-
- \target example-command
- \section1 \\example
-
- The \\example command is for documenting an example. The argument
- is the example's path relative to omne of the paths listed in the
- \l {exampledirs-variable} {exampledirs} variable in the QDoc
- configuration file.
-
- The documentation page will be output to \c {path-to-example}.html.
- QDoc will add a list of all the example's source files at the top
- of the page.
-
- For example, if \l {exampledirs-variable} {exampledirs} contains
- \c $QTDIR/examples/widgets/imageviewer, then
-
- \code
- / *!
- \example widgets/imageviewer
- \title ImageViewer Example
- \subtitle
-
- The example shows how to combine QLabel and QScrollArea
- to display an image.
-
- ...
- * /
- \endcode
-
- QDoc renders this example in widgets-imageviewer.html:
-
- \quotation
- \raw HTML
- <center><h1>Image Viewer Example</h1></center>
- \endraw
-
- Files:
- \list
- \li \l{http://doc.qt.io/qt-5/qtwidgets-widgets-imageviewer-imageviewer-cpp.html}
- {widgets/imageviewer/imageviewer.cpp}
- \li \l{http://doc.qt.io/qt-5/qtwidgets-widgets-imageviewer-imageviewer-h.html}
- {widgets/imageviewer/imageviewer.h}
- \li \l{http://doc.qt.io/qt-5/qtwidgets-widgets-imageviewer-main-cpp.html}
- {widgets/imageviewer/main.cpp}
- \endlist
-
- The example shows how to combine QLabel and QScrollArea
- to display an image.
-
- ...
- \endquotation
-
- \target externalpage-command
- \section1 \\externalpage
-
- The \\externalpage command assigns a title to an external URL.
-
- \code
- / *!
- \externalpage http://doc.qt.io/
- \title Qt Documentation Site
- * /
- \endcode
-
- This allows you to include a link to the external page in your
- documentation this way:
-
- \code
- / *!
- At the \l {Qt Documentation Site} you can find the latest
- documentation for Qt, Qt Creator, the Qt SDK and much more.
- * /
- \endcode
-
- QDoc renders this as:
-
- \quotation
- At the \l {http://doc.qt.io/}{Qt Documentation Site}
- you can find the latest documentation for Qt, Qt Creator, the Qt SDK
- and much more.
- \endquotation
-
- To achieve the same result without using the \\externalpage
- command, you would have to hard-code the address into your
- documentation:
-
- \code
- / *!
- At the \l {http://doc.qt.io/}{Qt Documentation Site}
- you can find the latest documentation for Qt, Qt Creator, the Qt SDK
- and much more.
- * /
- \endcode
-
- The \\externalpage command makes it easier to maintain the
- documentation. If the address changes, you only need to change the
- argument of the \\externalpage command.
-
- \target fn-command
- \section1 \\fn (function)
-
- The \\fn command is for documenting a function. The argument is
- the function's signature, including its return type, const-ness,
- and list of formal arguments with types. If the named function
- doesn't exist, QDoc emits a warning.
-
- \note The \\fn command is QDoc's default command: when no
- topic command can be found in a QDoc comment, QDoc tries to tie
- the documentation to the following code as if it is the
- documentation for a function. Hence, it is normally not necessary
- to include this command when documenting a function, if the
- function's QDoc comment is written immediately above the function
- implementation in the \c .cpp file. But it must be present when
- documenting an inline function in the \c .cpp file that is
- implemented in the \c .h file.
-
- \code
- / *!
- \fn bool QToolBar::isAreaAllowed(Qt::ToolBarArea area) const
-
- Returns \c true if this toolbar is dockable in the given
- \a area; otherwise returns \c false.
- * /
- \endcode
-
- QDoc renders this as:
-
- \quotation
- \raw HTML
- <h3>bool QToolBar::isAreaAllowed(Qt::ToolBarArea area) const
- </h3>
- \endraw
-
- Returns \c true if this toolbar is dockable in the given
- \a area; otherwise returns \c false.
- \endquotation
-
- See also \l {overload-command} {\\overload}.
-
- \target group-command
- \section1 \\group
-
- The \\group command creates a separate page that lists the classes
- belonging to the group. The argument is the group name.
-
- A class is included in a group by using the \l {ingroup-command}
- {\\ingroup} command. Overview pages can also be related to a group
- using the same command, but the list of overview pages must be
- requested explicitly using the \l {generatelist-command}
- {\\generatelist} command (see example below).
-
- The \\group command is typically followed by a \l {title-command}
- {\\title} command and a short introduction to the group. The
- HTML page for the group is written to a \c {.html} file put in
- <lower-case>\e{group}.html.
-
- Each class name is listed as a link to the class reference page
- followed by the text from the class's \l {brief-command} {\\brief}
- texts.
-
- \code
- / *!
- \group io
-
- \title Input/Output and Networking
-
- These classes are used to handle input and output to
- and from external devices, processes, files etc., as
- well as manipulating files and directories.
- * /
- \endcode
-
- QDoc generates a group page in \c{io.html} that will look
- like this:
-
- \quotation
- \raw HTML
-
- <h1>Input/Output and Networking</h1>
-
- <p>These classes are used to handle input and output
- to and from external devices, processes, files etc., as
- well as manipulating files and directories.</p>
-
- <p>
- <table width="100%">
- <tr valign="top" bgcolor="#e0e0e0">
- <td><b>
- <a href="http://doc.qt.io/qt-5/qabstractsocket.html">QAbstractSocket</a>
- </b></td>
- <td>
- The base functionality common to all socket types
- </td></tr>
-
- <tr valign="top" bgcolor="#e0e0e0">
- <td><b>
- <a href="http://doc.qt.io/qt-5/qbuffer.html">QBuffer</a>
- </b></td>
- <td>
- QIODevice interface for a QByteArray
- </td></tr>
-
- <tr valign="top" bgcolor="#e0e0e0">
- <td><b>
- <a href="http://doc.qt.io/qt-5/qclipboard.html">QClipboard</a>
- </b></td>
- <td>
- Access to the window system clipboard
- </td></tr>
- </table>
- \endraw
- \endquotation
-
- Note that overview pages related to the group, must be listed
- explicitly using the \l {generatelist-command} {\\generatelist}
- command with the \c related argument.
-
- \code
- / *!
- \group architecture
-
- \title Architecture
-
- These documents describe aspects of Qt's architecture
- and design, including overviews of core Qt features and
- technologies.
-
- \generatelist{related}
- * /
- \endcode
-
- See also \l {ingroup-command} {\\ingroup} and \l
- {generatelist-command} {\\generatelist}.
-
- \target headerfile-command
- \section1 \\headerfile
-
- The \\headerfile command is for documenting the global functions,
- types and macros that are declared in a header file, but not in a
- namespace. The argument is the name of the header file. The HTML
- page is written to a \c {.html} file constructed from the header
- file argument.
-
- The documentation for a function, type, or macro that is declared
- in the header file being documented, is included in the header file
- page using the \l {relates-command} {\\relates} command.
-
- If the argument doesn't exist as a header file, the \\headerfile
- command creates a documentation page for the header file anyway.
-
- \code
- / *!
- \headerfile <QtAlgorithms>
-
- \title Generic Algorithms
-
- \brief The <QtAlgorithms> header file provides
- generic template-based algorithms.
-
- Qt provides a number of global template functions in \c
- <QtAlgorithms> that work on containers and perform
- well-know algorithms.
- * /
- \endcode
-
- QDoc generates a header file page \c{qtalgorithms.html} that looks
- like this:
-
- \quotation
- \raw HTML
- <center><h1>&lt;QtAlgorithms&gt; -
- Generic Algorithms</h1></center>
- <p>The <QtAlgorithms> header file provides generic
- template-based algorithms.
- <a href="13-qdoc-commands-topics.html#header-command">More...</a>
- </p>
-
- <h3>Functions</h3>
- <ul>
- <li>RandomAccessIterator
- <a href="http://doc.qt.io/qt-5/qtalgorithms-obsolete.html#qBinaryFind">qBinaryFind</a></b>
- (RandomAccessIterator begin, RandomAccessIterator end,
- const T & value)</li>
- <li>...</li></ul>
- <hr />
- \endraw
-
- \target header
-
- \raw HTML
- <h2>Detailed Description</h2>
- <p>The <QtAlgorithms> header file provides generic
- template-based algorithms. </p>
- \endraw
-
- Qt provides a number of global template functions in \c
- <QtAlgorithms> that work on containers and perform
- well-know algorithms.
-
- ...
- \endquotation
-
- \target macro-command
- \section1 \\macro
-
- The \\macro command is for documenting a C++ macro. The argument
- is the macro in one of three styles: function-like macros like
- Q_ASSERT(), declaration-style macros like Q_PROPERTY(), and macros
- without parentheses like Q_OBJECT.
-
- The \\macro comment must contain a \l {relates-command}
- {\\relates} command that attaches the macro comment to a class,
- header file, or namespace. Otherwise, the documentation will be
- lost. Here are three example macro comments followed by what they
- might look like in \c {qtglobal.html} or \c {qobject.html}:
-
- \code
- / *!
- \macro void Q_ASSERT(bool test)
- \relates <QtGlobal>
-
- Prints a warning message containing the source code
- file name and line number if \a test is false.
-
- ...
-
- \sa Q_ASSERT_X(), qFatal(), {Debugging Techniques}
- * /
- \endcode
-
- \quotation
- \raw HTML
- <h3>void Q_ASSERT ( bool <i>test</i> )</h3>
- \endraw
-
- Prints a warning message containing the source code
- file name and line number if \a test is false.
-
- ...
-
- See also Q_ASSERT_X(), qFatal() and \l {Debugging Techniques}.
-
- \endquotation
-
- \code
- / *!
- \macro Q_PROPERTY(...)
- \relates QObject
-
- This macro declares a QObject property. The syntax is:
-
- ...
-
- \sa {Qt's Property System}
- * /
- \endcode
-
- \quotation
- \raw HTML
- <h3>Q_PROPERTY ( ... )</h3>
- \endraw
-
- This macro declares a QObject property. The syntax is:
-
- ...
-
- See also \l {Qt's Property System}.
- \endquotation
-
- \code
- / *!
- \macro Q_OBJECT
- \relates QObject
-
- The Q_OBJECT macro must appear in the private section
- of a class definition that declares its own signals and
- slots, or that uses other services provided by Qt's
- meta-object system.
-
- ...
-
- \sa {Meta-Object System}, {Signals and Slots}, {Qt's
- Property System}
- * /
- \endcode
-
- \quotation
- \raw HTML
- <h3>Q_OBJECT</h3>
- \endraw
-
- The Q_OBJECT macro must appear in the private section
- of a class definition that declares its own signals and
- slots or that uses other services provided by Qt's
- meta-object system.
-
- ...
-
- See also \l {Meta-Object System}, \l {Signals &
- Slots} and \l {Qt's Property System}.
- \endquotation
-
- \target module-command
- \section1 \\module
-
- The \\module creates a page that lists the classes belonging to
- the module specified by the command's argument. A class included
- in the module by including the \l {inmodule-command} {\\inmodule}
- command in the \\class comment.
-
- The \\module command is typically followed by a \l {title-command}
- {\\title} and a \l {brief-command} {\\brief} command. Each class
- is listed as a link to the class reference page followed by the
- text from the class's \l {brief-command} {\\brief} command. For
- example:
-
- \code
- / *!
- \module QtNetwork
-
- \title Qt Network Module
-
- \brief Contains classes for writing TCP/IP clients and servers.
-
- The network module provides classes to make network
- programming easier and portable. It offers both
- high-level classes such as QNetworkAccessManager that
- implements application-level protocols, and
- lower-level classes such as QTcpSocket, QTcpServer, and
- QUdpSocket.
- * /
- \endcode
-
- QDoc renders this in \c {qtnetwork.html} like this:
-
- \quotation
- \raw HTML
- <h1><center>Qt Network Module</center></h1>
- \endraw
-
- The Qt Network module offers classes that allow you to
- write TCP/IP clients and servers.\l {module
- details} {More...}
-
- \raw HTML
- <p>
- <table width="100%">
- <tr valign="top" bgcolor="#d0d0d0">
- <td><b>
- <a href="http://doc.qt.io/qt-5/qabstractsocket.html">QAbstractSocket</a>
- </b></td>
- <td>
- The base functionality common to all socket types
- </td></tr>
-
- <tr valign="top" bgcolor="#d0d0d0">
- <td><b>
- <a href="http://doc.qt.io/archives/qt-4.7/qftp.html">QFtp</a>
- </b></td>
- <td>
- Implementation of the FTP protocol
- </td></tr>
-
- <tr valign="top" bgcolor="#d0d0d0">
- <td>...</td>
- <td>...</td>
- </tr>
- </table>
-
- <p><hr /></p>
- \endraw
-
- \target module details
-
- \raw HTML
- <h2>Detailed Description</h2>
-
- <p>
- The Qt Network module offers classes that allow you to
- write TCP/IP clients and servers.
- </p>
-
- <p>
- The network module provides classes to make network
- programming easier and portable. It offers both
- high-level classes such as QNetworkAccessManager that
- implements application-level protocols, and
- lower-level classes such as QTcpSocket, QTcpServer, and
- QUdpSocket.
- </p>
- \endraw
-
- ...
-
- \endquotation
-
- The \l {noautolist-command} {\\noautolist} command can be used here
- to omit the automatically generated list of classes at the end.
-
- See also \l {inmodule-command} {\\inmodule}
-
- \target namespace-command
- \section1 \\namespace
-
- The \\namespace command is for documenting the contents of the C++
- namespace named as its argument. The documentation outline QDoc
- generates for a namespace is similar to the outline it generates
- for a C++ class.
-
- \code
- / *!
- \namespace Qt
-
- \brief Contains miscellaneous identifiers used throughout the Qt library.
- * /
- \endcode
-
- QDoc renders this in \c{qt.html} like this:
-
- \quotation
- \raw HTML
- <center><h1>Qt Namespace Reference</h1></center>
- <p>The Qt namespace contains miscellaneous
- identifiers used throughout the Qt library.
- <a href="13-qdoc-commands-topics.html#name">More...</a>
- </p>
-
- <pre>#include &lt;Qt&gt;</pre>
- <ul>
- <li>
- <a href="http://doc.qt.io/archives/qt-4.7/qt-qt3.html">
- Qt 3 support members</a></li>
- </ul>
-
-
- <h3>Types</h3>
- <ul>
- <li>flags
- <a href="http://doc.qt.io/archives/qt-4.7/qt.html#AlignmentFlag-enum">Alignment</a></b></li>
- <li>...</li></ul>
- <hr />
- \endraw
-
- \target name
-
- \raw HTML
- <h2>Detailed Description</h2>
- <p>Contains miscellaneous identifiers
- used throughout the Qt library.</p>
- \endraw
-
- ...
- \endquotation
-
- \target page-command
- \section1 \\page
-
- The \\page command is for creating a stand-alone documentation
- page. The argument can consist of two parts separated by a
- space. The first part is the name of the file where QDoc should
- store the page. The second part, if present, is a word that
- specifies the page type. Currently, the second part can be one of
- the following list of words:
-
- \list
-
- \li faq - A frequently asked question.
-
- \li howto - A user guide on how to use some components of the
- software.
-
- \li example - A page that describes a working example.
-
- \li overview - For text pages that provide an overview of some
- important subject.
-
- \li tutorial - For text pages that are part of a tutorial.
-
- \li api - This is the type of page used for C++ class references and
- QML type references. You should never use this one for the pages
- you write, because this one is reserved for qdoc.
-
- \endlist
-
- The page title is set using the \l {title-command} {\\title}
- command.
-
- \code
- / *!
- \page aboutqt.html
-
- \title About Qt
-
- Qt is a C++ toolkit for cross-platform GUI
- application development. Qt provides single-source
- portability across Microsoft Windows, OS X, Linux,
- and all major commercial Unix variants.
-
- Qt provides application developers with all the
- functionality needed to build applications with
- state-of-the-art graphical user interfaces. Qt is fully
- object-oriented, easily extensible, and allows true
- component programming.
-
- ...
- * /
- \endcode
-
- QDoc renders this page in \c {aboutqt.html}.
-
- \target property-command
- \section1 \\property
-
- The \\property command is for documenting a Qt property. The
- argument is the full property name.
-
- A property is defined using the Q_PROPERTY() macro. The macro
- takes as arguments the property's name and its set, reset and get
- functions.
-
- \code
- Q_PROPERTY(QString state READ state WRITE setState)
- \endcode
-
- The set, reset and get functions don't need to be documented,
- documenting the property is sufficient. QDoc will generate a list
- of the access function that will appear in the property
- documentation which in turn will be located in the documentation
- of the class that defines the property.
-
- The \\property command comment typically includes a \l
- {brief-command} {\\brief} command. For properties the \l
- {brief-command} {\\brief} command's argument is a sentence
- fragment that will be included in a one line description of the
- property. The command follows the same rules for the \l
- {brief-property} {description} as the \l {variable-command}
- {\\variable} command.
-
- \code
- / *!
- \property QPushButton::flat
- \brief Whether the border is disabled.
-
- This property's default is false.
- * /
- \endcode
-
- QDoc includes this in \c {qpushbutton.html} like this:
-
- \quotation
- \raw HTML
- <h3>flat : bool</h3>
- \endraw
-
- This property holds whether the border is disabled.
-
- This property's default is false.
-
- Access functions:
-
- \list
- \li \b { bool isFlat () const}
- \li \b { void setFlat ( bool )}
- \endlist
-
- \endquotation
-
- \code
- / *!
- \property QWidget::width
- \brief The width of the widget excluding any window frame.
-
- See the \l {Window Geometry} documentation for an
- overview of window geometry.
-
- \sa geometry, height, size
- * /
- \endcode
-
- QDoc includes this in \c {qwidget.html} like this:
-
- \quotation
- \raw HTML
- <h3>width : const int</h3>
- \endraw
-
- This property holds the width of the widget excluding
- any window frame.
-
- See the \l {Window Geometry} documentation for an
- overview of window geometry.
-
- Access functions:
-
- \list
- \li \b { int width () const}
- \endlist
-
- See also \l{QWidget::geometry} {geometry},
- \l{QWidget::height} {height}, and \l{QWidget::size} {size}.
- \endquotation
-
- \target qmlattachedproperty-command
- \section1 \\qmlattachedproperty
-
- The \\qmlattachedproperty command is for documenting a QML
- property that will be attached to some QML type. See
- \l{http://qt-project.org/doc/qt-4.7/qdeclarativeintroduction.html#attached-properties}
- {Attached Properties}. The argument is the rest of the line. The
- argument text should be the property type, followed by the QML
- element name where the property is being declared, the \c{::}
- qualifier, and finally the property name. If we have a QML
- attached property named \c isCurrentItem in QML \c ListView,
- and the property has type \c {bool}, the \\qmlattachedproperty for
- it would look like this:
-
- \code
- / *!
- \qmlattachedproperty bool ListView::isCurrentItem
- This attached property is \c true if this delegate is the current
- item; otherwise false.
-
- It is attached to each instance of the delegate.
-
- This property may be used to adjust the appearance of the current
- item, for example:
-
- \snippet doc/src/snippets/declarative/listview/listview.qml isCurrentItem
- * /
- \endcode
-
- QDoc includes this attached property on the QML reference page for the
- \l{http://qt-project.org/doc/qt-4.7/qml-listview.html#isCurrentItem-prop}
- {ListView} element.
-
- \target qmlattachedsignal-command
- \section1 \\qmlattachedsignal
-
- The \\qmlattachedsignal command is for documenting an attachable
- \l{Signal and Handler Event System}{signal}. The \\qmlattachedsignal
- command is used just like the \l{qmlsignal-command} {\\qmlsignal} command.
-
- The argument is the rest of the line. It should be the name of the
- QML type where the signal is declared, the \c{::}
- qualifier, and finally the signal name. For example, a QML
- attached signal named \c add() in the \c GridView
- element is documented like this:
-
- \code
- / *!
- \qmlattachedsignal GridView::add()
- This attached signal is emitted immediately after an item is added to the view.
- * /
- \endcode
-
- QDoc includes this documentation on the QML reference page for the
- \l GridView element.
-
- \target qmlbasictype-command
- \section1 \\qmlbasictype
-
- The \\qmlbasictype command is for documenting a basic type for QML.
- The argument is the type name. The type must be included in the
- QML basic types group using the \l{ingroup-command}{\\ingroup}
- command as shown below. This will cause QDoc to include the
- documentation for the type on the
- \l{http://qt-project.org/doc/qt-4.7/qdeclarativebasictypes.html}
- {QML Basic Types} page. The \l{brief-command} {\\brief} command
- is also required, because it appears on the
- \l{http://qt-project.org/doc/qt-4.7/qdeclarativebasictypes.html}
- {QML Basic Types} page as well.
-
- \code
- / *!
- \qmlbasictype int
- \ingroup qmlbasictypes
-
- \brief An integer is a whole number, for example 0, 10, or -20.
-
- An integer is a whole number, e.g. 0, 10, or -20. The possible
- \c int values range from around -2000000000 to around
- 2000000000, although most elements will only accept a reduced
- range (which they mention in their documentation).
-
- Example:
- \qml
- Item { width: 100; height: 200 }
- \endqml
-
- \sa {QML Basic Types}
- * /
- \endcode
-
- QDoc outputs this as \l{http://qt-project.org/doc/qt-4.7/qml-int.html}
- {qml-int.html}.
-
- \target qmlclass-command
- \section1 \\qmlclass
-
- This command is deprecated. Use \l{qmltype-command} {\\qmltype}
- instead.
-
- The \\qmlclass command is for documenting a QML type that is
- instantiated by a C++ class. The command has two arguments. The
- first argument is the name of the QML type. The second argument
- is the name of the C++ class that instantiates the QML type.
-
- \code
- / *!
- \qmlclass Transform QGraphicsTransform
- \ingroup qml-transform-elements
- \since 4.7
- \brief Provides a way of building advanced transformations on Items.
-
- The Transform element is a base type which cannot be
- instantiated directly. The following concrete Transform types
- are available:
-
- \list
- \li \l Rotation
- \li \l Scale
- \li \l Translate
- \endlist
-
- The Transform elements let you create and control advanced
- transformations that can be configured independently using
- specialized properties.
-
- You can assign any number of Transform elements to an \l
- Item. Each Transform is applied in order, one at a time.
-
- * /
- \endcode
-
- This example generates the
- \l {http://qt-project.org/doc/qt-4.7/qml-transform.html} {QML Transform}
- page. The \\qmlclass comment should include the \l
- {since-command} {\\since} command, because all QML types are
- new. It should also include the \l{brief-command} {\\brief}
- command. If a type is a member of a group of QML
- types, it should also include one or more \l{ingroup-command}
- {\\ingroup} commands.
-
- \target qmlmethod-command
- \section1 \\qmlmethod
-
- The \\qmlmethod command is for documenting a QML method. The
- argument is the complete method signature, including return
- type and parameter names and types.
-
- \code
- / *!
- \qmlmethod void TextInput::select(int start, int end)
-
- Causes the text from \a start to \a end to be selected.
-
- If either start or end is out of range, the selection is not changed.
-
- After having called this, selectionStart will become the lesser, and
- selectionEnd the greater (regardless of the order passed to this method).
-
- \sa selectionStart, selectionEnd
- * /
- \endcode
-
- QDoc includes this documentation on the element reference page for the
- \l{http://qt-project.org/doc/qt-4.7/qml-textinput.html#select-method}
- {TextInput} element.
-
- \target qmltype-command
- \section1 \\qmltype
-
- The \\qmltype command is for documenting a QML type. The command
- has one argument, which is the name of the QML type.
-
- If the QML type is instantiated by a C++ class, that class must be
- specified using the \l{instantiates-command} {\\instantiates}
- context command.
-
- \code
- / *!
- \qmltype Transform
- \instantiates QGraphicsTransform
- \ingroup qml-transform-elements
- \since 4.7
- \brief The Transform elements provide a way to build
- advanced transformations on Items.
-
- The Transform element is a base type which cannot be
- instantiated directly. The concrete Transform types are:
-
- \list
- \li \l Rotation
- \li \l Scale
- \li \l Translate
- \endlist
-
- The Transform elements let you create and control advanced
- transformations that can be configured independently using
- specialized properties.
-
- You can assign any number of Transform elements to an \l
- Item. Each Transform is applied in order, one at a time.
-
- * /
- \endcode
-
- The example generates the \l
- {http://qt-project.org/doc/qt-4.7/qml-transform.html} {QML Transform}
- page. The \e{\\qmltype} comment includes \l{instantiates-command}
- {\\instantiates} to specify that a Transform is instantiated by
- the C++ class QGraphicsTransform. A \\qmltype comment should
- always include a \l {since-command} {\\since} command, because all
- QML types are new. It should also include a \l{brief-command}
- {\\brief} description. If a QML type is a member of a QML type group,
- the \\qmltype comment should include one or more \l{ingroup-command}
- {\\ingroup} commands.
-
-
- \target qmlproperty-command
- \section1 \\qmlproperty
-
- The \\qmlproperty command is for documenting a QML property. The
- argument is the rest of the line. The argument text should be the
- property type, followed by the QML type name, the \c{::}
- qualifier, and finally the property name. If we have a QML
- property named \c x in QML type \c Translate, and the property
- has type \c {real}, the \\qmlproperty for it would look like this:
-
- \code
- / *!
- \qmlproperty real Translate::x
-
- The translation along the X axis.
- * /
- \endcode
-
- QDoc includes this QML property on the QML reference page for the
- \l {http://qt-project.org/doc/qt-4.7/qml-translate.html} {Translate}
- element.
-
- If the QML property is of enumeration type, or it holds a bit-wise
- combination of flags, the \l{value-command}{\\value} command can
- be used to document the acceptable values.
-
- \target qmlsignal-command
- \section1 \\qmlsignal
-
- The \\qmlsignal command is for documenting a QML signal.
- The argument is the rest of the line. The arguments should be: the QML type
- where the signal is declared, the \c{::} qualifier, and finally the signal
- name. If we have a QML signal named \c clicked(), the documentation for it
- would look like this:
-
- \code
- / *!
- \qmlsignal UIComponents::Button::clicked()
- This signal is emitted when the user clicks the button. A click is defined
- as a press followed by a release. The corresponding handler is
- \c onClicked.
- * /
- \endcode
-
- QDoc includes this documentation on the QML reference page for the
- \l{http://qt-project.org/doc/qt-4.7/qml-mousearea.html#onEntered-signal}
- {MouseArea} element.
-
- \target qmlmodule-command
- \section1 \\qmlmodule
-
- Insert the \c{\\qmlmodule} command to create a \c QML module page. A QML
- module is a collection of QML types or any related material. This
- command is similar to the \l{group-command}.
-
- A QML class may belong to a module by inserting the
- \l{inqmlmodule-command}{\\inqmlmodule} command as a topic command.
- Every member of a group must be linked to using the module name and two
- colons (\c{::}).
-
- \code
- \beginqdoc
- A link to the TabWidget of the UI Component is \l {UIComponent::TabWidget}.
- \endqdoc
- \endcode
-
- QDoc will generate a page for the module with a listing of the members
- of the module.
-
- \code
- \qmlmodule ClickableComponents
-
- This is a list of the Clickable Components set. A Clickable component
- responds to a \c clicked() event.
- \endcode
-
- The \l{componentset}{UIComponents} example demonstrates proper usage of
- QDoc commands to document QML types and QML modules.
-
- \target inqmlmodule-command
- \section1 \\inqmlmodule
-
- A QML class may belong to a \l{qmlmodule-command}{QML module} by inserting
- the \l{inqmlmodule-command}{\\inqmlmodule} command as a topic command, with
- the module name (without a version number) as the only argument. Every
- member of a group must be linked to using the module name and two colons
- (\c{::}).
-
- \code
- \qmltype ClickableButton
- \inqmlmodule ClickableComponents
-
- A clickable button that responds to the \c click() event.
- \endcode
-
- To link to the \c ClickableButton, use the
- \c{\l ClickableComponents::ClickableButton} format.
-
- The \l{componentset}{UIComponents} example demonstrates proper usage of
- QDoc commands to document QML types and QML modules.
-
- The \l {noautolist-command} {\\noautolist} command can be used here
- to omit the automatically generated list of types at the end.
-
- \target instantiates-command
- \section1 \\instantiates
-
- The \\instantiates command is used in the \l{qmltype-command} {QML
- type} comment of an elemental QML type to specify the name of the
- C++ class that instantiates the QML type.
-
- If the QML type is not instantiated by a C++ class, this command
- is not used.
-
- \code
- / *!
- \qmltype Transform
- \instantiates QGraphicsTransform
- \ingroup qml-transform-elements
- \since 4.7
- \brief Provides elements provide a way to build
- advanced transformations on Items.
-
- The Transform element is a base type which cannot be
- instantiated directly.
- * /
- \endcode
-
- The example generates the \l
- {http://qt-project.org/doc/qt-4.7/qml-transform.html} {QML Transform}
- page. The \e{\\qmltype} comment includes \l{instantiates-command}
- {\\instantiates} to specify that a Transform is instantiated by
- the C++ class QGraphicsTransform. A \\qmltype comment should
-
- \target typedef-command
- \section1 \\typedef
-
- The \\typedef command is for documenting a C++ typedef. The
- argument is the name of the typedef. The documentation for
- the typedef will be included in the reference documentation
- for the class, namespace, or header file in which the typedef
- is declared. To relate the \\typedef to a class, namespace, or
- header file, the \\typedef comment must contain a
- \l {relates-command} {\\relates} command.
-
- \code
- / *!
- \typedef QObjectList
- \relates QObject
-
- Synonym for QList<QObject>.
- * /
- \endcode
-
- QDoc includes this in \c {qobject.html} as:
-
- \quotation
- \raw HTML
- <h3>typedef QObjectList</h3>
- \endraw
-
- Synonym for QList<QObject>.
- \endquotation
-
- Another, although more rare, example:
-
- \code
- / *!
- \typedef QMsgHandler
- \relates QtGlobal
-
- This is a typedef for a pointer to a function with the
- following signature:
-
- \code
- void myMsgHandler(QtMsgType, const char *);
- \ endcode
-
- \sa QtMsgType, qInstallMsgHandler()
- * /
- \endcode
-
- QDoc includes this in \c {qtglobal.html} as:
-
- \quotation
- \raw HTML
- <h3>typedef QtMsgHandler</h3>
- \endraw
-
- This is a typedef for a pointer to a function with the
- following signature:
-
- \raw HTML
- <tt>
- <pre> void myMsgHandler(QtMsgType, const char *);</pre>
- </tt>
- \endraw
-
- See also QtMsgType and qInstallMsgHandler().
- \endquotation
-
- Other typedefs are located on the reference page for the class
- that defines them.
-
- \code
- / *!
- \typedef QLinkedList::Iterator
-
- Qt-style synonym for QList::iterator.
- * /
- \endcode
-
- QDoc includes this one on the reference page for class QLinkedList as:
-
- \quotation
- \raw HTML
- <h3>typedef QLinkedList::Iterator</h3>
- \endraw
-
- Qt-style synonym for QList::iterator.
- \endquotation
-
- \target variable-command
- \section1 \\variable
-
- The \\variable command is for documenting a class member variable
- or a constant. The argument is the variable or constant name. The
- \\variable command comment includes a \l {brief-command} {\\brief}
- command. QDoc generates the documentation based on the text from
- \\brief command.
-
- The documentation will be located in the in the associated class,
- header file, or namespace documentation.
-
- In case of a member variable:
-
- \code
- / *!
- \variable QStyleOption::palette
- \brief The palette that should be used when painting
- the control
- * /
- \endcode
-
- QDoc includes this in qstyleoption.html as:
-
- \quotation
- \raw HTML
- <h3>
- <a href="http://doc.qt.io/qt-5/qpalette.html">
- QPalette
- </a>
- QStyleOption::palette
- </h3>
- \endraw
-
- This variable holds the palette that should be used
- when painting the control.
- \endquotation
-
- You can also document constants with the \\variable command. For
- example, suppose you have the \c Type and \c UserType constants in
- the QTreeWidgetItem class:
-
- \code
- enum { Type = 0, UserType = 1000 };
- \endcode
-
- For these, the \\variable command can be used this way:
-
- \code
- / *!
- \variable QTreeWidgetItem::Type
-
- The default type for tree widget items.
-
- \sa UserType, type()
- * /
- \endcode
- \code
- / *!
- \variable QTreeWidgetItem::UserType
-
- The minimum value for custom types. Values below
- UserType are reserved by Qt.
-
- \sa Type, type()
- * /
- \endcode
-
- QDoc includes these in qtreewidget.html as:
-
- \quotation
- \raw HTML
- <h3>
- const int QTreeWidgetItem::Type
- </h3>
- \endraw
-
- The default type for tree widget items.
-
- See also \l {QTreeWidgetItem::UserType} {UserType} and \l
- {QTreeWidgetItem::type()} {type()}.
-
- \raw HTML
- <h3>
- const int QTreeWidgetItem::UserType
- </h3>
- \endraw
-
- The minimum value for custom types. Values below
- UserType are reserved by Qt.
-
- See also \l {QTreeWidgetItem::Type} {Type} and
- \l{QTreeWidgetItem::type()} {type()}.
-
- \endquotation
-*/
diff --git a/src/tools/qdoc/doc/qdoc-manual.qdoc b/src/tools/qdoc/doc/qdoc-manual.qdoc
deleted file mode 100644
index a0e35c2e9c..0000000000
--- a/src/tools/qdoc/doc/qdoc-manual.qdoc
+++ /dev/null
@@ -1,78 +0,0 @@
-/****************************************************************************
-**
-** Copyright (C) 2015 The Qt Company Ltd.
-** Contact: http://www.qt.io/licensing/
-**
-** This file is part of the documentation of the Qt Toolkit.
-**
-** $QT_BEGIN_LICENSE:FDL$
-** Commercial License Usage
-** Licensees holding valid commercial Qt licenses may use this file in
-** accordance with the commercial license agreement provided with the
-** Software or, alternatively, in accordance with the terms contained in
-** a written agreement between you and The Qt Company. For licensing terms
-** and conditions see http://www.qt.io/terms-conditions. For further
-** information use the contact form at http://www.qt.io/contact-us.
-**
-** GNU Free Documentation License Usage
-** Alternatively, this file may be used under the terms of the GNU Free
-** Documentation License version 1.3 as published by the Free Software
-** Foundation and appearing in the file included in the packaging of
-** this file. Please review the following information to ensure
-** the GNU Free Documentation License version 1.3 requirements
-** will be met: http://www.gnu.org/copyleft/fdl.html.
-** $QT_END_LICENSE$
-**
-****************************************************************************/
-
-/*!
- \page qdoc-index.html
- \nextpage Introduction to QDoc
-
- \title QDoc Manual
-
- \list
- \li \l {Introduction to QDoc}
- \li \l {Getting Started with QDoc}
- \li \l {Command Index}
- \li \l {Topic Commands}
- \li \l {Context Commands}
- \list
- \li \l {Document Navigation}
- \li \l {Status}
- \li \l {Thread Support}
- \li \l {Relating Things}
- \li \l {Grouping Things}
- \li \l {Naming Things}
- \endlist
- \li \l{Markup Commands}
- \list
- \li \l {Text Markup}
- \li \l {Document Structure}
- \li \l {Including Code Inline}
- \li \l {Including External Code}
- \li \l {Creating Links}
- \li \l {Including Images}
- \li \l {Tables and Lists}
- \li \l {Special Content}
- \li \l {Miscellaneous}
- \endlist
- \li \l{Creating DITA Maps}
- \li \l {The QDoc Configuration File}
- \list
- \li \l {Generic Configuration Variables}
- \li \l {Creating Help Project Files}
- \li \l {C++ Specific Configuration Variables}
- \li \l {HTML Specific Configuration Variables}
- \li \l {Supporting Derived Projects}
- \li \l {Example Manifest Files}
- \li \l {qtgui.qdocconf}
- \li \l {minimum.qdocconf}
- \li \l {Generating DITA XML Output}
- \endlist
- \li \l {QA Pages}
- \endlist
-
-*/
-
-
diff --git a/src/tools/qdoc/doc/qdoc-minimum-qdocconf.qdoc b/src/tools/qdoc/doc/qdoc-minimum-qdocconf.qdoc
deleted file mode 100644
index 1fcd23a0f8..0000000000
--- a/src/tools/qdoc/doc/qdoc-minimum-qdocconf.qdoc
+++ /dev/null
@@ -1,89 +0,0 @@
-/****************************************************************************
-**
-** Copyright (C) 2015 The Qt Company Ltd.
-** Contact: http://www.qt.io/licensing/
-**
-** This file is part of the documentation of the Qt Toolkit.
-**
-** $QT_BEGIN_LICENSE:FDL$
-** Commercial License Usage
-** Licensees holding valid commercial Qt licenses may use this file in
-** accordance with the commercial license agreement provided with the
-** Software or, alternatively, in accordance with the terms contained in
-** a written agreement between you and The Qt Company. For licensing terms
-** and conditions see http://www.qt.io/terms-conditions. For further
-** information use the contact form at http://www.qt.io/contact-us.
-**
-** GNU Free Documentation License Usage
-** Alternatively, this file may be used under the terms of the GNU Free
-** Documentation License version 1.3 as published by the Free Software
-** Foundation and appearing in the file included in the packaging of
-** this file. Please review the following information to ensure
-** the GNU Free Documentation License version 1.3 requirements
-** will be met: http://www.gnu.org/copyleft/fdl.html.
-** $QT_END_LICENSE$
-**
-****************************************************************************/
-/*!
-\page qdoc-minimum-qdocconf.html
-\keyword minimal-qdocconf
-\title A Minimal qdocconf File
-
-\brief Describes a minimal .qdocconf file
-
-Below you will find the full contents of qtgui.qdocconf. The subsequent section
-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.
-
-\badcode
- include(compat.qdocconf)
- outputdir = html
- headerdirs = .
- sourcedirs = .
- exampledirs = .
- imagedirs = ./images
-\endcode
-
-\b Notes:
-
-\badcode
- include(compat.qdocconf)
-\endcode
-
-For compatibility with older versions of Qt, it is recommended
-to include compat.qdocconf.
-
-\code
- outputdir = html
-\endcode
-
-QDoc will put the documentation generated in the html directory.
-
-\badcode
- headerdirs = .
-\endcode
-
-The header file associated with the \e .cpp source files can be found in the
-current directory.
-
-\badcode
- sourcedirs = .
-\endcode
-
-The current directory is the directory containing the source files: the \e .cpp
-and \e .qdoc files used in the documentation.
-
-\badcode
- exampledirs = .
-\endcode
-
-The source code of the example files can be found in the current directory.
-
-\badcode
- imagedirs = ./images
-\endcode
-
-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
deleted file mode 100644
index d90584ff42..0000000000
--- a/src/tools/qdoc/doc/qtgui-qdocconf.qdoc
+++ /dev/null
@@ -1,299 +0,0 @@
-/****************************************************************************
-**
-** Copyright (C) 2015 The Qt Company Ltd.
-** Contact: http://www.qt.io/licensing/
-**
-** This file is part of the documentation of the Qt Toolkit.
-**
-** $QT_BEGIN_LICENSE:FDL$
-** Commercial License Usage
-** Licensees holding valid commercial Qt licenses may use this file in
-** accordance with the commercial license agreement provided with the
-** Software or, alternatively, in accordance with the terms contained in
-** a written agreement between you and The Qt Company. For licensing terms
-** and conditions see http://www.qt.io/terms-conditions. For further
-** information use the contact form at http://www.qt.io/contact-us.
-**
-** GNU Free Documentation License Usage
-** Alternatively, this file may be used under the terms of the GNU Free
-** Documentation License version 1.3 as published by the Free Software
-** Foundation and appearing in the file included in the packaging of
-** this file. Please review the following information to ensure
-** the GNU Free Documentation License version 1.3 requirements
-** will be met: http://www.gnu.org/copyleft/fdl.html.
-** $QT_END_LICENSE$
-**
-****************************************************************************/
-
-/*!
-
-\page qtgui-qdocconf.html
-\title qtgui.qdocconf with Comments
-
-\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 \c qtgui.qdocconf. The subsequent section will discuss
-every statement in the qdocconf file.
-
-\badcode
- include($QT_INSTALL_DOCS/global/qt-module-defaults.qdocconf)
-
- project = QtGui
- description = Qt GUI Reference Documentation
- url = http://doc.qt.io/qt-5
- version = $QT_VERSION
-
- examplesinstallpath = gui
-
- qhp.projects = QtGui
-
- qhp.QtGui.file = qtgui.qhp
- qhp.QtGui.namespace = org.qt-project.qtgui.$QT_VERSION_TAG
- qhp.QtGui.virtualFolder = qtgui
- qhp.QtGui.indexTitle = Qt GUI
- qhp.QtGui.indexRoot =
-
- qhp.QtGui.filterAttributes = qtgui $QT_VERSION qtrefdoc
- qhp.QtGui.customFilters.Qt.name = Qtgui $QT_VERSION
- qhp.QtGui.customFilters.Qt.filterAttributes = qtgui $QT_VERSION
-
- qhp.QtGui.subprojects = classes
- qhp.QtGui.subprojects.classes.title = C++ Classes
- qhp.QtGui.subprojects.classes.indexTitle = Qt GUI C++ Classes
- qhp.QtGui.subprojects.classes.selectors = class fake:headerfile
- qhp.QtGui.subprojects.classes.sortPages = true
-
- tagfile = ../../../doc/qtgui/qtgui.tags
-
- depends += \
- qtcore \
- qtnetwork \
- qtopengl \
- qtsvg \
- qtqml \
- qtquick \
- qtwidgets \
- qtdoc
-
- headerdirs += ..
-
- sourcedirs += .. \
- ../../../examples/gui/doc/src
-
- excludedirs = ../../../examples/gui/doc/src/tmp
-
- exampledirs += ../../../examples/gui \
- snippets
-
- imagedirs += images \
- ../../../examples/gui/doc/images \
- ../../../doc/src/images \
-\endcode
-
-\title Qtgui.qdocconf with notes
-
-\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.
-\badcode
- qmake -query
-\endcode
-
-\b {See also}: \l {include}.
-
-\badcode
- project = QtGui
-\endcode
-
-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.
-
-\b {See also}: \l {project}.
-
-\badcode
- description = Qt GUI Reference Documentation
-\endcode
-
-A short description of the project concerned.
-
-\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 external links
-to content listed in the index.
-
-\note QDoc omits this value when the -installdir argument
-is specified when running QDoc.
-
-\keyword examplesinstallpath
-
-\badcode
- examplesinstallpath = gui
-\endcode
-
-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
- \c exampledirs.
-
-\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
-\e qhelpgenerator program can convert the QHP file into a QCH file (\e .qch),
-which can be opened in Qt Assistant or Qt Creator.
-
-\badcode
- qhp.QtGui.namespace = org.qt-project.qtgui.$QT_VERSION_TAG
-\endcode
-
-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.
-
-\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.
-
-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 '/'.
-
-\badcode
- qhp.QtGui.indexTitle = Qt GUI
-\endcode
-
-This is the title of the page that has the contents.
-
-\badcode
- qhp.QtGui.indexRoot =
-\endcode
-
-Specifies the title of the root (namespace) page to generate the documentation for.
-Typically defined as an empty string.
-
-\badcode
- qhp.QtGui.filterAttributes = qtgui $QT_VERSION qtrefdoc
- qhp.QtGui.customFilters.Qt.name = QtGui $QT_VERSION
- qhp.QtGui.customFilters.Qt.filterAttributes = qtgui $QT_VERSION
-\endcode
-
-The documentation set (one per QDoc project) can have any number of filter
-attributes assigned to it. A filter attribute is an ordinary string which
-can be freely chosen. Additionally, custom filters that reference above
-attributes can be defined. Qt Assistant will display the name of the custom
-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.
-
-\badcode
- qhp.QtGui.subprojects = classes
- qhp.QtGui.subprojects.classes.title = C++ Classes
- qhp.QtGui.subprojects.classes.indexTitle = Qt GUI C++ Classes
-\endcode
-The subprojects specify the sections that are displayed in the table of contents
-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".
-
-\badcode
- qhp.QtGui.subprojects.classes.selectors = class fake:headerfile
-\endcode
-
-Lists all C++ classes and header files.
-
-See \l {Creating Help Project Files} for more information.
-
-\badcode
- tagfile = ../../../doc/qtgui/qtgui.tags
-\endcode
-
-This specifies the Doxygen tag file that needs to be written when the html is generated
-by QDoc.
-
-\badcode
-depends += \
- qtcore \
- qtnetwork \
- qtopengl \
- qtsvg \
- qtqml \
- qtquick \
- qtwidgets \
- qtdoc
-\endcode
-
-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.
-
-\badcode
- headerdirs += ..
-\endcode
-
-Add the parent directory to the list of directories containing the header files
-associated with the \e .cpp source files.
-
-\badcode
- sourcedirs += .. \
- ../../../examples/gui/doc/src
-\endcode
-
-Add the specified directories to the list of directories containing the \e .cpp and
-\e .qdoc files used in the documentation.
-
-\badcode
- excludedirs = ../../../examples/gui/doc/src/tmp
-\endcode
-
-The \c excludedirs variable is for listing directories that should not be processed
-by qdoc, even if the same directories are included by the \c sourcedirs or \c headerdirs
-variables.
-
-When executed, QDoc will ignore the directories listed.
-\b {See also}: \l {excludefiles}.
-
-\badcode
- exampledirs += ../../../examples/gui \
- snippets
-\endcode
-\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.
-
-If QDoc encounters both \c exampledirs and \c examples, it will look first in the
-\c examples directory. QDoc will accept the first matching file it finds. QDoc will
-search in the directories specified, not in their subdirectories.
-
-\badcode
- imagedirs += images \
- ../../../examples/gui/doc/images \
- ../../../doc/src/images \
-\endcode
-
-Add the directories specified above to the list of directories where the images
-can be found.
-*/