diff options
author | Oswald Buddenhagen <oswald.buddenhagen@theqtcompany.com> | 2015-10-21 15:51:54 +0200 |
---|---|---|
committer | Oswald Buddenhagen <oswald.buddenhagen@theqtcompany.com> | 2015-10-23 10:47:25 +0000 |
commit | e15ca59111fe05f5ecc0f7fb48c34b5b22115a12 (patch) | |
tree | 1f66c3191f4745dea9bf126b8c22a4d8c5a90c58 /src/qdoc/doc | |
parent | 4e2d1893a89ce3dcfaacea091acae1f673c14a9e (diff) |
move qdoc back to qttools
we can do that now, as the bootstrap lib is now a properly exported
module, and qmldevtools is now bootstrapped as well.
this removes the abomination of a copy of the qml parser in qtbase.
unfortunately qtbase/2422251ee5025a067b14b989153764ab36e43f10 is
reverted, as qtdeclarative is still missing the respective change.
this introduces no regression in discoverability or usability, as a full
doc build already needed qttools - for qhelpgenerator.
Change-Id: Ic9c4c9732ddf5998637b9e42e27939ba50b31479
Reviewed-by: Jędrzej Nowacki <jedrzej.nowacki@theqtcompany.com>
Reviewed-by: Martin Smith <martin.smith@digia.com>
Reviewed-by: Lars Knoll <lars.knoll@theqtcompany.com>
Reviewed-by: Topi Reiniö <topi.reinio@digia.com>
Diffstat (limited to 'src/qdoc/doc')
42 files changed, 12196 insertions, 0 deletions
diff --git a/src/qdoc/doc/config/qdoc.qdocconf b/src/qdoc/doc/config/qdoc.qdocconf new file mode 100644 index 000000000..9d841e9b6 --- /dev/null +++ b/src/qdoc/doc/config/qdoc.qdocconf @@ -0,0 +1,72 @@ +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/qdoc/doc/corefeatures.qdoc b/src/qdoc/doc/corefeatures.qdoc new file mode 100644 index 000000000..bbee7410f --- /dev/null +++ b/src/qdoc/doc/corefeatures.qdoc @@ -0,0 +1,35 @@ +/**************************************************************************** +** +** 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/qdoc/doc/examples/componentset/ProgressBar.qml b/src/qdoc/doc/examples/componentset/ProgressBar.qml new file mode 100644 index 000000000..c4e8c103e --- /dev/null +++ b/src/qdoc/doc/examples/componentset/ProgressBar.qml @@ -0,0 +1,135 @@ +/**************************************************************************** +** +** 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/qdoc/doc/examples/componentset/Switch.qml b/src/qdoc/doc/examples/componentset/Switch.qml new file mode 100644 index 000000000..7b7e7af31 --- /dev/null +++ b/src/qdoc/doc/examples/componentset/Switch.qml @@ -0,0 +1,142 @@ +/**************************************************************************** +** +** 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/qdoc/doc/examples/componentset/TabWidget.qml b/src/qdoc/doc/examples/componentset/TabWidget.qml new file mode 100644 index 000000000..008c5e14e --- /dev/null +++ b/src/qdoc/doc/examples/componentset/TabWidget.qml @@ -0,0 +1,183 @@ +/**************************************************************************** +** +** 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/qdoc/doc/examples/componentset/componentset.pro b/src/qdoc/doc/examples/componentset/componentset.pro new file mode 100644 index 000000000..5b44737c2 --- /dev/null +++ b/src/qdoc/doc/examples/componentset/componentset.pro @@ -0,0 +1,5 @@ +SOURCES = componentset.pro \ + ProgressBar.qml \ + Switch.qml \ + TabWidget.qml \ + uicomponents.qdoc diff --git a/src/qdoc/doc/examples/componentset/uicomponents.qdoc.sample b/src/qdoc/doc/examples/componentset/uicomponents.qdoc.sample new file mode 100644 index 000000000..7a14f88f4 --- /dev/null +++ b/src/qdoc/doc/examples/componentset/uicomponents.qdoc.sample @@ -0,0 +1,38 @@ +/**************************************************************************** +** +** 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/qdoc/doc/examples/cpp.qdoc.sample b/src/qdoc/doc/examples/cpp.qdoc.sample new file mode 100644 index 000000000..38a131783 --- /dev/null +++ b/src/qdoc/doc/examples/cpp.qdoc.sample @@ -0,0 +1,126 @@ +/**************************************************************************** +** +** 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/qdoc/doc/examples/examples.qdoc b/src/qdoc/doc/examples/examples.qdoc new file mode 100644 index 000000000..28810e30d --- /dev/null +++ b/src/qdoc/doc/examples/examples.qdoc @@ -0,0 +1,97 @@ +/**************************************************************************** +** +** 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/qdoc/doc/examples/layoutmanagement.qdocinc b/src/qdoc/doc/examples/layoutmanagement.qdocinc new file mode 100644 index 000000000..780b03c8f --- /dev/null +++ b/src/qdoc/doc/examples/layoutmanagement.qdocinc @@ -0,0 +1,13 @@ +\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/qdoc/doc/examples/main.cpp b/src/qdoc/doc/examples/main.cpp new file mode 100644 index 000000000..849405e0a --- /dev/null +++ b/src/qdoc/doc/examples/main.cpp @@ -0,0 +1,46 @@ +/**************************************************************************** +** +** 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/qdoc/doc/examples/mainwindow.cpp b/src/qdoc/doc/examples/mainwindow.cpp new file mode 100644 index 000000000..68b878c07 --- /dev/null +++ b/src/qdoc/doc/examples/mainwindow.cpp @@ -0,0 +1,243 @@ +/**************************************************************************** +** +** 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/qdoc/doc/examples/minimum.qdocconf b/src/qdoc/doc/examples/minimum.qdocconf new file mode 100644 index 000000000..e360685f1 --- /dev/null +++ b/src/qdoc/doc/examples/minimum.qdocconf @@ -0,0 +1,38 @@ +# 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/qdoc/doc/examples/objectmodel.qdocinc b/src/qdoc/doc/examples/objectmodel.qdocinc new file mode 100644 index 000000000..02b5991c4 --- /dev/null +++ b/src/qdoc/doc/examples/objectmodel.qdocinc @@ -0,0 +1,11 @@ +\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/qdoc/doc/examples/qml.qdoc.sample b/src/qdoc/doc/examples/qml.qdoc.sample new file mode 100644 index 000000000..cacd91224 --- /dev/null +++ b/src/qdoc/doc/examples/qml.qdoc.sample @@ -0,0 +1,116 @@ +/**************************************************************************** +** +** 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/qdoc/doc/examples/samples.qdocinc b/src/qdoc/doc/examples/samples.qdocinc new file mode 100644 index 000000000..d5679fdcd --- /dev/null +++ b/src/qdoc/doc/examples/samples.qdocinc @@ -0,0 +1,109 @@ +/**************************************************************************** +** +** 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/qdoc/doc/examples/signalandslots.qdocinc b/src/qdoc/doc/examples/signalandslots.qdocinc new file mode 100644 index 000000000..e14ede144 --- /dev/null +++ b/src/qdoc/doc/examples/signalandslots.qdocinc @@ -0,0 +1,9 @@ +\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/qdoc/doc/files/basicqt.qdoc.sample b/src/qdoc/doc/files/basicqt.qdoc.sample new file mode 100644 index 000000000..ce8df096f --- /dev/null +++ b/src/qdoc/doc/files/basicqt.qdoc.sample @@ -0,0 +1,67 @@ + /*! + \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/qdoc/doc/files/compat.qdocconf b/src/qdoc/doc/files/compat.qdocconf new file mode 100644 index 000000000..3e7ea6c89 --- /dev/null +++ b/src/qdoc/doc/files/compat.qdocconf @@ -0,0 +1,12 @@ +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/qdoc/doc/files/qtgui.qdocconf b/src/qdoc/doc/files/qtgui.qdocconf new file mode 100644 index 000000000..0b2d28108 --- /dev/null +++ b/src/qdoc/doc/files/qtgui.qdocconf @@ -0,0 +1,49 @@ +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/qdoc/doc/images/happy.gif b/src/qdoc/doc/images/happy.gif Binary files differnew file mode 100644 index 000000000..a4597f6fa --- /dev/null +++ b/src/qdoc/doc/images/happy.gif diff --git a/src/qdoc/doc/images/happyguy.jpg b/src/qdoc/doc/images/happyguy.jpg Binary files differnew file mode 100644 index 000000000..e8604793c --- /dev/null +++ b/src/qdoc/doc/images/happyguy.jpg diff --git a/src/qdoc/doc/images/link-to-qquickitem.png b/src/qdoc/doc/images/link-to-qquickitem.png Binary files differnew file mode 100644 index 000000000..00e03c371 --- /dev/null +++ b/src/qdoc/doc/images/link-to-qquickitem.png diff --git a/src/qdoc/doc/images/links-to-broken-links.png b/src/qdoc/doc/images/links-to-broken-links.png Binary files differnew file mode 100644 index 000000000..775143bd4 --- /dev/null +++ b/src/qdoc/doc/images/links-to-broken-links.png diff --git a/src/qdoc/doc/images/links-to-links.png b/src/qdoc/doc/images/links-to-links.png Binary files differnew file mode 100644 index 000000000..9d2cc2fae --- /dev/null +++ b/src/qdoc/doc/images/links-to-links.png diff --git a/src/qdoc/doc/images/qa-table.png b/src/qdoc/doc/images/qa-table.png Binary files differnew file mode 100644 index 000000000..5818739fa --- /dev/null +++ b/src/qdoc/doc/images/qa-table.png diff --git a/src/qdoc/doc/images/qt-logo.png b/src/qdoc/doc/images/qt-logo.png Binary files differnew file mode 100644 index 000000000..6b72d5fb7 --- /dev/null +++ b/src/qdoc/doc/images/qt-logo.png diff --git a/src/qdoc/doc/images/training.jpg b/src/qdoc/doc/images/training.jpg Binary files differnew file mode 100644 index 000000000..c2ce5c3b2 --- /dev/null +++ b/src/qdoc/doc/images/training.jpg diff --git a/src/qdoc/doc/qa-pages.qdoc b/src/qdoc/doc/qa-pages.qdoc new file mode 100644 index 000000000..a96673901 --- /dev/null +++ b/src/qdoc/doc/qa-pages.qdoc @@ -0,0 +1,109 @@ +/**************************************************************************** +** +** 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/qdoc/doc/qdoc-guide/qdoc-guide.qdoc b/src/qdoc/doc/qdoc-guide/qdoc-guide.qdoc new file mode 100644 index 000000000..af1fa1ba1 --- /dev/null +++ b/src/qdoc/doc/qdoc-guide/qdoc-guide.qdoc @@ -0,0 +1,632 @@ +/**************************************************************************** +** +** 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 = "Π" + \endcode + The snippet code will replace any instances of \c{\\pi} with \c Π in the + HTML file, which will appear as the Greek \pi symbol when viewed in + browsers. + + \section2 QML Additions + + QDoc is able to parse QML files for QDoc comments. QDoc will parse files + with the QML extension, \c{.qml}, if the extension type is included in the + \l{Input and Output Directories}{fileextensions} variable. + + Also, the generated HTML files can have a prefix and a suffix following the + QML module name, specified in the QDoc configuration file. + \badcode + outputprefixes = QML + outputprefixes.QML = uicomponents- + outputsuffixes = QML + outputsuffixes.QML = -tp + \endcode + + \b {See also}: \l {outputprefixes-variable}{outputprefixes}, + \l {outputsuffixes-variable}{outputsuffixes}. + +*/ + +/*! + \page qdoc-guide-writing.html + \title Writing Documentation + \previouspage Creating QDoc Configuration Files + \nextpage Categories of Documentation + + \section1 QDoc Comments + + Documentation is contained within qdoc \e comments, delimited by + \beginqdoc and \endqdoc comments. Note that these are valid comments + in C++, QML, and JavaScript. + + 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/qdoc/doc/qdoc-guide/qtwritingstyle-cpp.qdoc b/src/qdoc/doc/qdoc-guide/qtwritingstyle-cpp.qdoc new file mode 100644 index 000000000..8cbf74cd6 --- /dev/null +++ b/src/qdoc/doc/qdoc-guide/qtwritingstyle-cpp.qdoc @@ -0,0 +1,187 @@ +/**************************************************************************** +** +** 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/qdoc/doc/qdoc-guide/qtwritingstyle-qml.qdoc b/src/qdoc/doc/qdoc-guide/qtwritingstyle-qml.qdoc new file mode 100644 index 000000000..6955a042c --- /dev/null +++ b/src/qdoc/doc/qdoc-guide/qtwritingstyle-qml.qdoc @@ -0,0 +1,164 @@ +/**************************************************************************** +** +** 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/qdoc/doc/qdoc-manual-DITA.qdoc b/src/qdoc/doc/qdoc-manual-DITA.qdoc new file mode 100644 index 000000000..72882c8eb --- /dev/null +++ b/src/qdoc/doc/qdoc-manual-DITA.qdoc @@ -0,0 +1,164 @@ +/**************************************************************************** +** +** 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/qdoc/doc/qdoc-manual-cmdindex.qdoc b/src/qdoc/doc/qdoc-manual-cmdindex.qdoc new file mode 100644 index 000000000..d3f188c26 --- /dev/null +++ b/src/qdoc/doc/qdoc-manual-cmdindex.qdoc @@ -0,0 +1,156 @@ +/**************************************************************************** +** +** 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/qdoc/doc/qdoc-manual-contextcmds.qdoc b/src/qdoc/doc/qdoc-manual-contextcmds.qdoc new file mode 100644 index 000000000..d707c77cf --- /dev/null +++ b/src/qdoc/doc/qdoc-manual-contextcmds.qdoc @@ -0,0 +1,1058 @@ +/**************************************************************************** +** +** 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/qdoc/doc/qdoc-manual-intro.qdoc b/src/qdoc/doc/qdoc-manual-intro.qdoc new file mode 100644 index 000000000..84f941684 --- /dev/null +++ b/src/qdoc/doc/qdoc-manual-intro.qdoc @@ -0,0 +1,325 @@ +/**************************************************************************** +** +** 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/qdoc/doc/qdoc-manual-markupcmds.qdoc b/src/qdoc/doc/qdoc-manual-markupcmds.qdoc new file mode 100644 index 000000000..49cbfc065 --- /dev/null +++ b/src/qdoc/doc/qdoc-manual-markupcmds.qdoc @@ -0,0 +1,4081 @@ +/**************************************************************************** +** +** 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/qdoc/doc/qdoc-manual-qdocconf.qdoc b/src/qdoc/doc/qdoc-manual-qdocconf.qdoc new file mode 100644 index 000000000..69980c1e1 --- /dev/null +++ b/src/qdoc/doc/qdoc-manual-qdocconf.qdoc @@ -0,0 +1,1714 @@ +/**************************************************************************** +** +** 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 = "á" + macro.Aring.DITAXML = "Å" + macro.aring.DITAXML = "å" + macro.Auml.DITAXML = "Ä" + macro.br.DITAXML = " " + macro.BR.DITAXML = " " + macro.copyright.DITAXML = "©" + macro.eacute.DITAXML = "é" + macro.hr.DITAXML = " " + macro.iacute.DITAXML = "í" + macro.oslash.DITAXML = "ø" + macro.ouml.DITAXML = "ö" + macro.raisedaster.DITAXML = "<sup>*</sup>" + macro.rarrow.DITAXML = "→" + macro.reg.DITAXML = "<sup>®</sup>" + macro.uuml.DITAXML = "ü" + macro.mdash.DITAXML = "—" + 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/qdoc/doc/qdoc-manual-topiccmds.qdoc b/src/qdoc/doc/qdoc-manual-topiccmds.qdoc new file mode 100644 index 000000000..1dfd03163 --- /dev/null +++ b/src/qdoc/doc/qdoc-manual-topiccmds.qdoc @@ -0,0 +1,1594 @@ +/**************************************************************************** +** +** 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><QtAlgorithms> - + 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 <Qt></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/qdoc/doc/qdoc-manual.qdoc b/src/qdoc/doc/qdoc-manual.qdoc new file mode 100644 index 000000000..a0e35c2e9 --- /dev/null +++ b/src/qdoc/doc/qdoc-manual.qdoc @@ -0,0 +1,78 @@ +/**************************************************************************** +** +** 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/qdoc/doc/qdoc-minimum-qdocconf.qdoc b/src/qdoc/doc/qdoc-minimum-qdocconf.qdoc new file mode 100644 index 000000000..1fcd23a0f --- /dev/null +++ b/src/qdoc/doc/qdoc-minimum-qdocconf.qdoc @@ -0,0 +1,89 @@ +/**************************************************************************** +** +** 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/qdoc/doc/qtgui-qdocconf.qdoc b/src/qdoc/doc/qtgui-qdocconf.qdoc new file mode 100644 index 000000000..d90584ff4 --- /dev/null +++ b/src/qdoc/doc/qtgui-qdocconf.qdoc @@ -0,0 +1,299 @@ +/**************************************************************************** +** +** 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. +*/ |