diff options
Diffstat (limited to 'src/tools/qdoc/doc')
42 files changed, 0 insertions, 12196 deletions
diff --git a/src/tools/qdoc/doc/config/qdoc.qdocconf b/src/tools/qdoc/doc/config/qdoc.qdocconf deleted file mode 100644 index 9d841e9b64..0000000000 --- a/src/tools/qdoc/doc/config/qdoc.qdocconf +++ /dev/null @@ -1,72 +0,0 @@ -include($QT_INSTALL_DOCS/global/qt-module-defaults.qdocconf) - -project = QDoc -description = QDoc Manual -version = $QT_VERSION - -sourcedirs = .. - -exampledirs = .. \ - ../examples - -imagedirs = ../images \ - ../../../../widgets/doc/images -# ../../../doc/src/templates/images - -tagfile = ../html/qdoc.tags - -examples.fileextensions = "*.cpp *.h *.js *.xq *.svg *.xml *.ui *.qhp *.qhcp *.qml *.css *.qdoc *.qdocinc *.sample" - -qhp.projects = QDoc - -qhp.QDoc.file = qdoc.qhp -qhp.QDoc.namespace = org.qt-project.qdoc.$QT_VERSION_TAG -qhp.QDoc.virtualFolder = qdoc -qhp.QDoc.indexTitle = QDoc Manual -qhp.QDoc.indexRoot = - -qhp.QDoc.filterAttributes = qdoc qtrefdoc -qhp.QDoc.customFilters.QDoc.name = QDoc -qhp.QDoc.customFilters.QDoc.filterAttributes = qdoc -qhp.QDoc.subprojects = overviews -qhp.QDoc.subprojects.overviews.title = Overviews -qhp.QDoc.subprojects.overviews.indexTitle = QDoc Manual -qhp.QDoc.subprojects.overviews.selectors = fake:page,group,module - -depends += \ - activeqt \ - qtassistant \ - qtbluetooth \ - qtconcurrent \ - qtcontacts \ - qtcore \ - qtdbus \ - qtdesigner \ - qtdoc \ - qthelp \ - qtimageformats \ - qtgui \ - qtlocation \ - qtlinguist \ - qtmultimedia \ - qtnetwork \ - qtopengl \ - qtorganizer \ - qtprintsupport \ - qtqml \ - qtquick \ - qtscript \ - qtscripttools \ - qtsensors \ - qtsql \ - qtsvg \ - qttestlib \ - qtuitools \ - qtversit \ - qtwidgets \ - qtwebkit \ - qtwebkitexamples \ - qtxml \ - qtxmlpatterns - -navigation.landingpage = "QDoc Manual" diff --git a/src/tools/qdoc/doc/corefeatures.qdoc b/src/tools/qdoc/doc/corefeatures.qdoc deleted file mode 100644 index bbee7410fe..0000000000 --- a/src/tools/qdoc/doc/corefeatures.qdoc +++ /dev/null @@ -1,35 +0,0 @@ -/**************************************************************************** -** -** Copyright (C) 2015 The Qt Company Ltd. -** Contact: http://www.qt.io/licensing/ -** -** This file is part of the documentation of the Qt Toolkit. -** -** $QT_BEGIN_LICENSE:FDL$ -** Commercial License Usage -** Licensees holding valid commercial Qt licenses may use this file in -** accordance with the commercial license agreement provided with the -** Software or, alternatively, in accordance with the terms contained in -** a written agreement between you and The Qt Company. For licensing terms -** and conditions see http://www.qt.io/terms-conditions. For further -** information use the contact form at http://www.qt.io/contact-us. -** -** GNU Free Documentation License Usage -** Alternatively, this file may be used under the terms of the GNU Free -** Documentation License version 1.3 as published by the Free Software -** Foundation and appearing in the file included in the packaging of -** this file. Please review the following information to ensure -** the GNU Free Documentation License version 1.3 requirements -** will be met: http://www.gnu.org/copyleft/fdl.html. -** $QT_END_LICENSE$ -** -****************************************************************************/ - -/*! - \page corefeatures.html - \title Core Features - - \input examples/signalandslots.qdocinc - \input examples/objectmodel.qdocinc - \input examples/layoutmanagement.qdocinc -*/ diff --git a/src/tools/qdoc/doc/examples/componentset/ProgressBar.qml b/src/tools/qdoc/doc/examples/componentset/ProgressBar.qml deleted file mode 100644 index c4e8c103e9..0000000000 --- a/src/tools/qdoc/doc/examples/componentset/ProgressBar.qml +++ /dev/null @@ -1,135 +0,0 @@ -/**************************************************************************** -** -** Copyright (C) 2015 The Qt Company Ltd. -** Contact: http://www.qt.io/licensing/ -** -** This file is part of the examples of the Qt Toolkit. -** -** $QT_BEGIN_LICENSE:BSD$ -** You may use this file under the terms of the BSD license as follows: -** -** "Redistribution and use in source and binary forms, with or without -** modification, are permitted provided that the following conditions are -** met: -** * Redistributions of source code must retain the above copyright -** notice, this list of conditions and the following disclaimer. -** * Redistributions in binary form must reproduce the above copyright -** notice, this list of conditions and the following disclaimer in -** the documentation and/or other materials provided with the -** distribution. -** * Neither the name of The Qt Company Ltd nor the names of its -** contributors may be used to endorse or promote products derived -** from this software without specific prior written permission. -** -** -** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS -** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT -** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR -** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT -** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, -** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT -** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, -** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY -** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT -** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE -** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE." -** -** $QT_END_LICENSE$ -** -****************************************************************************/ - -import QtQuick 1.0 - -/*! - \qmltype ProgressBar - \inqmlmodule UIComponents - \brief A component that shows the progress of an event - - A ProgressBar shows the linear progress of an event as its \l value. - The range is specified using the \l {minimum} and the \l{maximum} values. - - The ProgressBar component is part of the \l {UI Components} module. - - This documentation is part of the \l{componentset}{UIComponents} example. -*/ -Item { - id: progressbar - - /*! - The minimum value of the ProgressBar range. - The \l value must not be less than this value. - */ - property int minimum: 0 - - /*! - The maximum value of the ProgressBar range. - The \l value must not be more than this value. - */ - property int maximum: 100 - - /*! - The value of the progress. - */ - property int value: 0 - - /*! - \qmlproperty color ProgressBar::color - The color of the ProgressBar's gradient. Must bind to a color type. - - \omit - The "\qmlproperty <type> <property name>" is needed because - property alias need to have their types manually entered. - - QDoc will not publish the documentation within omit and endomit. - \endomit - - \sa secondColor - */ - property alias color: gradient1.color - - /*! - \qmlproperty color ProgressBar::secondColor - The second color of the ProgressBar's gradient. - Must bind to a color type. - - \omit - The "\qmlproperty <type> <property name>" is needed because - property alias need to have their types manually entered. - - QDoc will not publish the documentation within omit and endomit. - \endomit - - \sa color - */ - property alias secondColor: gradient2.color - - width: 250; height: 23 - clip: true - - Rectangle { - id: highlight - - /*! - An internal documentation comment. The widthDest property is not - a public API and therefore will not be exposed. - */ - property int widthDest: ((progressbar.width * (value - minimum)) / (maximum - minimum) - 6) - - width: highlight.widthDest - Behavior on width { SmoothedAnimation { velocity: 1200 } } - - anchors { left: parent.left; top: parent.top; bottom: parent.bottom; margins: 3 } - radius: 1 - gradient: Gradient { - GradientStop { id: gradient1; position: 0.0 } - GradientStop { id: gradient2; position: 1.0 } - } - - } - Text { - anchors { right: highlight.right; rightMargin: 6; verticalCenter: parent.verticalCenter } - color: "white" - font.bold: true - text: Math.floor((value - minimum) / (maximum - minimum) * 100) + '%' - } -} diff --git a/src/tools/qdoc/doc/examples/componentset/Switch.qml b/src/tools/qdoc/doc/examples/componentset/Switch.qml deleted file mode 100644 index 7b7e7af31f..0000000000 --- a/src/tools/qdoc/doc/examples/componentset/Switch.qml +++ /dev/null @@ -1,142 +0,0 @@ -/**************************************************************************** -** -** Copyright (C) 2015 The Qt Company Ltd. -** Contact: http://www.qt.io/licensing/ -** -** This file is part of the examples of the Qt Toolkit. -** -** $QT_BEGIN_LICENSE:BSD$ -** You may use this file under the terms of the BSD license as follows: -** -** "Redistribution and use in source and binary forms, with or without -** modification, are permitted provided that the following conditions are -** met: -** * Redistributions of source code must retain the above copyright -** notice, this list of conditions and the following disclaimer. -** * Redistributions in binary form must reproduce the above copyright -** notice, this list of conditions and the following disclaimer in -** the documentation and/or other materials provided with the -** distribution. -** * Neither the name of The Qt Company Ltd nor the names of its -** contributors may be used to endorse or promote products derived -** from this software without specific prior written permission. -** -** -** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS -** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT -** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR -** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT -** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, -** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT -** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, -** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY -** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT -** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE -** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE." -** -** $QT_END_LICENSE$ -** -****************************************************************************/ - -import QtQuick 1.0 - -/*! - \qmltype ToggleSwitch - \inqmlmodule UIComponents - \brief A component that can be turned on or off - - A toggle switch has two states: an \c on and an \c off state. The \c off - state is when the \l on property is set to \c false. - - The ToggleSwitch component is part of the \l {UI Components} module. - - This documentation is part of the \l{componentset}{UIComponents} example. - -*/ -Item { - id: toggleswitch - width: background.width; height: background.height - - /*! - Indicates the state of the switch. If \c false, then the switch is in - the \c off state. - - \omit - The \qmlproperty <type> <propertyname> is not necessary as QDoc - will associate this property to the ToggleSwitch - - QDoc will not publish the documentation within omit and endomit. - \endomit - */ - property bool on: false - - - /*! - A method to toggle the switch. If the switch is \c on, the toggling it - will turn it \c off. Toggling a switch in the \c off position will - turn it \c on. - */ - function toggle() { - if (toggleswitch.state == "on") - toggleswitch.state = "off"; - else - toggleswitch.state = "on"; - } - - - /*! - \internal - - An internal function to synchronize the switch's internals. This - function is not for public access. The \internal command will - prevent QDoc from publishing this comment in the public API. - */ - function releaseSwitch() { - if (knob.x == 1) { - if (toggleswitch.state == "off") return; - } - if (knob.x == 78) { - if (toggleswitch.state == "on") return; - } - toggle(); - } - - Rectangle { - id: background - width: 130; height: 48 - radius: 48 - color: "lightsteelblue" - MouseArea { anchors.fill: parent; onClicked: toggle() } - } - - Rectangle { - id: knob - width: 48; height: 48 - radius: width - color: "lightblue" - - MouseArea { - anchors.fill: parent - drag.target: knob; drag.axis: Drag.XAxis; drag.minimumX: 1; drag.maximumX: 78 - onClicked: toggle() - onReleased: releaseSwitch() - } - } - - states: [ - State { - name: "on" - PropertyChanges { target: knob; x: 78 } - PropertyChanges { target: toggleswitch; on: true } - }, - State { - name: "off" - PropertyChanges { target: knob; x: 1 } - PropertyChanges { target: toggleswitch; on: false } - } - ] - - transitions: Transition { - NumberAnimation { properties: "x"; easing.type: Easing.InOutQuad; duration: 200 } - } -} diff --git a/src/tools/qdoc/doc/examples/componentset/TabWidget.qml b/src/tools/qdoc/doc/examples/componentset/TabWidget.qml deleted file mode 100644 index 008c5e14e7..0000000000 --- a/src/tools/qdoc/doc/examples/componentset/TabWidget.qml +++ /dev/null @@ -1,183 +0,0 @@ -/**************************************************************************** -** -** Copyright (C) 2015 The Qt Company Ltd. -** Contact: http://www.qt.io/licensing/ -** -** This file is part of the examples of the Qt Toolkit. -** -** $QT_BEGIN_LICENSE:BSD$ -** You may use this file under the terms of the BSD license as follows: -** -** "Redistribution and use in source and binary forms, with or without -** modification, are permitted provided that the following conditions are -** met: -** * Redistributions of source code must retain the above copyright -** notice, this list of conditions and the following disclaimer. -** * Redistributions in binary form must reproduce the above copyright -** notice, this list of conditions and the following disclaimer in -** the documentation and/or other materials provided with the -** distribution. -** * Neither the name of The Qt Company Ltd nor the names of its -** contributors may be used to endorse or promote products derived -** from this software without specific prior written permission. -** -** -** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS -** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT -** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR -** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT -** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, -** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT -** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, -** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY -** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT -** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE -** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE." -** -** $QT_END_LICENSE$ -** -****************************************************************************/ - -import QtQuick 1.0 - -/*! - \qmltype TabWidget - \inqmlmodule UIComponents - \brief A widget that places its children as tabs - - A TabWidget places its children as tabs in a view. Selecting - a tab involves selecting the tab at the top. - - The TabWidget component is part of the \l {UI Components} module. - - This documentation is part of the \l{componentset}{UIComponents} example. - - \section1 Adding Tabs - - To add a tab, declare the tab as a child of the TabWidget. - - \code - TabWidget { - id: tabwidget - - Rectangle { - id: tab1 - color: "red" - //... omitted - } - Rectangle { - id: tab2 - color: "blue" - //... omitted - } - - } - \endcode - -*/ -Item { - id: tabWidget - - /*! - \internal - - Setting the default property to stack.children means any child items - of the TabWidget are actually added to the 'stack' item's children. - - See the \l{"Property Binding in QML"} - documentation for details on default properties. - - This is an implementation detail, not meant for public knowledge. Putting - the \internal command at the beginning will cause QDoc to not publish this - documentation in the public API page. - - Normally, a property alias needs to have a - "\qmlproperty <type> <propertyname>" to assign the alias a type. - - */ - default property alias content: stack.children - - - /*! - The currently active tab in the TabWidget. - */ - property int current: 0 - - /*! - A sample \c{read-only} property. - A contrived property to demonstrate QDoc's ability to detect - read-only properties. - - The signature is: - \code - readonly property int sampleReadOnlyProperty: 0 - \endcode - - Note that the property must be initialized to a value. - - */ - readonly property int sampleReadOnlyProperty: 0 - - /*! - \internal - - This handler is an implementation - detail. The \c{\internal} command will prevent QDoc from publishing this - documentation on the public API. - */ - onCurrentChanged: setOpacities() - Component.onCompleted: setOpacities() - - /*! - \internal - - An internal function to set the opacity. - The \internal command will prevent QDoc from publishing this - documentation on the public API. - */ - function setOpacities() { - for (var i = 0; i < stack.children.length; ++i) { - stack.children[i].opacity = (i == current ? 1 : 0) - } - } - - Row { - id: header - - Repeater { - model: stack.children.length - delegate: Rectangle { - width: tabWidget.width / stack.children.length; height: 36 - - Rectangle { - width: parent.width; height: 1 - anchors { bottom: parent.bottom; bottomMargin: 1 } - color: "#acb2c2" - } - BorderImage { - anchors { fill: parent; leftMargin: 2; topMargin: 5; rightMargin: 1 } - border { left: 7; right: 7 } - source: "tab.png" - visible: tabWidget.current == index - } - Text { - horizontalAlignment: Qt.AlignHCenter; verticalAlignment: Qt.AlignVCenter - anchors.fill: parent - text: stack.children[index].title - elide: Text.ElideRight - font.bold: tabWidget.current == index - } - MouseArea { - anchors.fill: parent - onClicked: tabWidget.current = index - } - } - } - } - - Item { - id: stack - width: tabWidget.width - anchors.top: header.bottom; anchors.bottom: tabWidget.bottom - } -} diff --git a/src/tools/qdoc/doc/examples/componentset/componentset.pro b/src/tools/qdoc/doc/examples/componentset/componentset.pro deleted file mode 100644 index 5b44737c2d..0000000000 --- a/src/tools/qdoc/doc/examples/componentset/componentset.pro +++ /dev/null @@ -1,5 +0,0 @@ -SOURCES = componentset.pro \ - ProgressBar.qml \ - Switch.qml \ - TabWidget.qml \ - uicomponents.qdoc diff --git a/src/tools/qdoc/doc/examples/componentset/uicomponents.qdoc.sample b/src/tools/qdoc/doc/examples/componentset/uicomponents.qdoc.sample deleted file mode 100644 index 7a14f88f45..0000000000 --- a/src/tools/qdoc/doc/examples/componentset/uicomponents.qdoc.sample +++ /dev/null @@ -1,38 +0,0 @@ -/**************************************************************************** -** -** Copyright (C) 2015 The Qt Company Ltd. -** Contact: http://www.qt.io/licensing/ -** -** This file is part of the documentation of the Qt Toolkit. -** -** $QT_BEGIN_LICENSE:FDL$ -** Commercial License Usage -** Licensees holding valid commercial Qt licenses may use this file in -** accordance with the commercial license agreement provided with the -** Software or, alternatively, in accordance with the terms contained in -** a written agreement between you and The Qt Company. For licensing terms -** and conditions see http://www.qt.io/terms-conditions. For further -** information use the contact form at http://www.qt.io/contact-us. -** -** GNU Free Documentation License Usage -** Alternatively, this file may be used under the terms of the GNU Free -** Documentation License version 1.3 as published by the Free Software -** Foundation and appearing in the file included in the packaging of -** this file. Please review the following information to ensure -** the GNU Free Documentation License version 1.3 requirements -** will be met: http://www.gnu.org/copyleft/fdl.html. -** $QT_END_LICENSE$ -** -****************************************************************************/ - -/*! - \qmlmodule UIComponents 1.0 - \title UI Components - \brief Basic set of UI components - - This is a listing of a list of UI components implemented by QML types. These - files are available for general import and they are based off the \l{Qt - Quick Code Samples}. - - This module is part of the \l{componentset}{UIComponents} example. -*/ diff --git a/src/tools/qdoc/doc/examples/cpp.qdoc.sample b/src/tools/qdoc/doc/examples/cpp.qdoc.sample deleted file mode 100644 index 38a131783b..0000000000 --- a/src/tools/qdoc/doc/examples/cpp.qdoc.sample +++ /dev/null @@ -1,126 +0,0 @@ -/**************************************************************************** -** -** Copyright (C) 2015 The Qt Company Ltd. -** Contact: http://www.qt.io/licensing/ -** -** This file is part of the documentation of the Qt Toolkit. -** -** $QT_BEGIN_LICENSE:FDL$ -** Commercial License Usage -** Licensees holding valid commercial Qt licenses may use this file in -** accordance with the commercial license agreement provided with the -** Software or, alternatively, in accordance with the terms contained in -** a written agreement between you and The Qt Company. For licensing terms -** and conditions see http://www.qt.io/terms-conditions. For further -** information use the contact form at http://www.qt.io/contact-us. -** -** GNU Free Documentation License Usage -** Alternatively, this file may be used under the terms of the GNU Free -** Documentation License version 1.3 as published by the Free Software -** Foundation and appearing in the file included in the packaging of -** this file. Please review the following information to ensure -** the GNU Free Documentation License version 1.3 requirements -** will be met: http://www.gnu.org/copyleft/fdl.html. -** $QT_END_LICENSE$ -** -****************************************************************************/ - -//![class] -/*! - \class QCache - \brief The QCache class is a template class that provides a cache. - - \ingroup tools - \ingroup shared - - \reentrant - - QCache\<Key, T\> defines a cache that stores objects of type T - associated with keys of type Key. For example, here's the - definition of a cache that stores objects of type Employee - associated with an integer key: - - \snippet code/doc_src_qcache.cpp 0 - - Here's how to insert an object in the cache: - - \snippet code/doc_src_qcache.cpp 1 - - ... detailed description ommitted - - \sa QPixmapCache, QHash, QMap -*/ -//![class] - -//![function] -/*! - \fn QString &QString::remove(int position, int n) - - Removes \a n characters from the string, starting at the given \a - position index, and returns a reference to the string. - - If the specified \a position index is within the string, but \a - position + \a n is beyond the end of the string, the string is - truncated at the specified \a position. - - \snippet qstring/main.cpp 37 - - \sa insert(), replace() -*/ -QString &QString::remove(int pos, int len) -//! [function] - -//! [return] -/*! - Returns \c true if a QScroller object was already created for \a target; \c false otherwise. - - \sa scroller() -*/ -bool QScroller::hasScroller(QObject *target) -//! [return] - -//! [property] -/*! - \property QVariantAnimation::duration - \brief the duration of the animation - - This property describes the duration in milliseconds of the - animation. The default duration is 250 milliseconds. - - \sa QAbstractAnimation::duration() - */ -int QVariantAnimation::duration() const -//! [property] - -//! [signals] -/*! - \fn QAbstractTransition::triggered() - - This signal is emitted when the transition has been triggered (after - onTransition() has been called). -*/ -//! [signals] - -//! [enums] -/*! - \enum QSql::TableType - - This enum type describes types of SQL tables. - - \value Tables All the tables visible to the user. - \value SystemTables Internal tables used by the database. - \value Views All the views visible to the user. - \value AllTables All of the above. -*/ -//! [enums] - -//! [overloaded notifier] -/*! -\property QSpinBox::value -\brief the value of the spin box - -setValue() will emit valueChanged() if the new value is different -from the old one. The \l{QSpinBox::}{value} property has a second notifier -signal which includes the spin box's prefix and suffix. -*/ -//! [overloaded notifier] diff --git a/src/tools/qdoc/doc/examples/examples.qdoc b/src/tools/qdoc/doc/examples/examples.qdoc deleted file mode 100644 index 28810e30da..0000000000 --- a/src/tools/qdoc/doc/examples/examples.qdoc +++ /dev/null @@ -1,97 +0,0 @@ -/**************************************************************************** -** -** Copyright (C) 2015 The Qt Company Ltd. -** Contact: http://www.qt.io/licensing/ -** -** This file is part of the documentation of the Qt Toolkit. -** -** $QT_BEGIN_LICENSE:FDL$ -** Commercial License Usage -** Licensees holding valid commercial Qt licenses may use this file in -** accordance with the commercial license agreement provided with the -** Software or, alternatively, in accordance with the terms contained in -** a written agreement between you and The Qt Company. For licensing terms -** and conditions see http://www.qt.io/terms-conditions. For further -** information use the contact form at http://www.qt.io/contact-us. -** -** GNU Free Documentation License Usage -** Alternatively, this file may be used under the terms of the GNU Free -** Documentation License version 1.3 as published by the Free Software -** Foundation and appearing in the file included in the packaging of -** this file. Please review the following information to ensure -** the GNU Free Documentation License version 1.3 requirements -** will be met: http://www.gnu.org/copyleft/fdl.html. -** $QT_END_LICENSE$ -** -****************************************************************************/ - -/*! - \example componentset - \title QML Documentation Example - - This example demonstrates one of the ways to document QML types. - - In particular, there are sample types that are documented with QDoc - commands comments. There are documentation comments for the QML types - and their public interfaces. The types are grouped into a module, the - \l{UI Components} module. - - The \l{componentset/uicomponents.qdoc.sample}{uicomponents.qdoc} file generates - the overview page for the \l{UI Components} module page. - - The generated documentation is available in the \l{UI Components} module. - - \section1 QML Class - - The QML types use the \l{qmltype-command}{\\qmltype} to document the - type. In addition, they have the \l{inmodule-command}{\\inmodule} - command in order for QDoc to associate them to the \c UIComponents module. - - QDoc uses the \l{brief-command}{\\brief} command to place a basic - description when listing the types. - - \section1 Properties, Signals, Handlers, and Methods - - The types have their properties, signals, handlers, and methods - defined in their respective QML files. QDoc associates the properties and - methods to the types, therefore, you only need to place the - documentation above the property, method, or signal. - - To document the type of a \e {property alias}, you must use the - \l{qmlproperty-command}{\\qmlproperty} command to specify the data type. - - \code - \qmlproperty int anAliasedProperty - An aliased property of type int. - \endcode - - \section2 Internal Documentation - - You may declare that a documentation is for internal use by placing the - \l{internal-command}{\\internal} command after the beginning QDoc comment - \begincomment. QDoc will prevent the internal documentation from appearing - in the public API. - - If you wish to omit certain parts of the documentation, you may use the - \l{omit-command}{\\omit} and \l{omit-command}{\\endomit} command. - - \section1 QML Types with C++ Implementation - - This example only demonstrates the documentation for types in QML - files, but the regular \l{qml-documentation}{QML commands} may be placed - inside C++ classes to define the public API of the QML type. - -*/ - - -/*! - \qmlmodule UIComponents 1.0 - \title UI Components - \brief Basic set of UI components - - This is a listing of a list of UI components implemented by QML types. These - files are available for general import and they are based on the - \l{Qt Quick Examples and Tutorials}{Qt Quick Code Samples}. - - This module is part of the \l{componentset}{UIComponents} example. -*/ diff --git a/src/tools/qdoc/doc/examples/layoutmanagement.qdocinc b/src/tools/qdoc/doc/examples/layoutmanagement.qdocinc deleted file mode 100644 index 780b03c8ff..0000000000 --- a/src/tools/qdoc/doc/examples/layoutmanagement.qdocinc +++ /dev/null @@ -1,13 +0,0 @@ -\section1 Layout Classes - -The Qt layout system provides a simple and powerful way of specifying -the layout of child widgets. - -By specifying the logical layout once, you get the following benefits: - -\list - \li Positioning of child widgets. - \li Sensible default sizes for windows. - \li Sensible minimum sizes for windows. - \li ... -\endlist diff --git a/src/tools/qdoc/doc/examples/main.cpp b/src/tools/qdoc/doc/examples/main.cpp deleted file mode 100644 index 849405e0ae..0000000000 --- a/src/tools/qdoc/doc/examples/main.cpp +++ /dev/null @@ -1,46 +0,0 @@ -/**************************************************************************** -** -** Copyright (C) 2015 The Qt Company Ltd. -** Contact: http://www.qt.io/licensing/ -** -** This file is part of the tools applications of the Qt Toolkit. -** -** $QT_BEGIN_LICENSE:LGPL21$ -** Commercial License Usage -** Licensees holding valid commercial Qt licenses may use this file in -** accordance with the commercial license agreement provided with the -** Software or, alternatively, in accordance with the terms contained in -** a written agreement between you and The Qt Company. For licensing terms -** and conditions see http://www.qt.io/terms-conditions. For further -** information use the contact form at http://www.qt.io/contact-us. -** -** GNU Lesser General Public License Usage -** Alternatively, this file may be used under the terms of the GNU Lesser -** General Public License version 2.1 or version 3 as published by the Free -** Software Foundation and appearing in the file LICENSE.LGPLv21 and -** LICENSE.LGPLv3 included in the packaging of this file. Please review the -** following information to ensure the GNU Lesser General Public License -** requirements will be met: https://www.gnu.org/licenses/lgpl.html and -** http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html. -** -** As a special exception, The Qt Company gives you certain additional -** rights. These rights are described in The Qt Company LGPL Exception -** version 1.1, included in the file LGPL_EXCEPTION.txt in this package. -** -** $QT_END_LICENSE$ -** -****************************************************************************/ - -#include <QApplication> -#include <QPushButton> - -int main(int argc, char *argv[]) -{ - QApplication app(argc, argv); - - QPushButton hello("Hello world!"); - hello.resize(100, 30); - - hello.show(); - return app.exec(); -} diff --git a/src/tools/qdoc/doc/examples/mainwindow.cpp b/src/tools/qdoc/doc/examples/mainwindow.cpp deleted file mode 100644 index 68b878c07e..0000000000 --- a/src/tools/qdoc/doc/examples/mainwindow.cpp +++ /dev/null @@ -1,243 +0,0 @@ -/**************************************************************************** -** -** Copyright (C) 2015 The Qt Company Ltd. -** Contact: http://www.qt.io/licensing/ -** -** This file is part of the tools applications of the Qt Toolkit. -** -** $QT_BEGIN_LICENSE:LGPL21$ -** Commercial License Usage -** Licensees holding valid commercial Qt licenses may use this file in -** accordance with the commercial license agreement provided with the -** Software or, alternatively, in accordance with the terms contained in -** a written agreement between you and The Qt Company. For licensing terms -** and conditions see http://www.qt.io/terms-conditions. For further -** information use the contact form at http://www.qt.io/contact-us. -** -** GNU Lesser General Public License Usage -** Alternatively, this file may be used under the terms of the GNU Lesser -** General Public License version 2.1 or version 3 as published by the Free -** Software Foundation and appearing in the file LICENSE.LGPLv21 and -** LICENSE.LGPLv3 included in the packaging of this file. Please review the -** following information to ensure the GNU Lesser General Public License -** requirements will be met: https://www.gnu.org/licenses/lgpl.html and -** http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html. -** -** As a special exception, The Qt Company gives you certain additional -** rights. These rights are described in The Qt Company LGPL Exception -** version 1.1, included in the file LGPL_EXCEPTION.txt in this package. -** -** $QT_END_LICENSE$ -** -****************************************************************************/ - -#include <QtWidgets> - -#include "mainwindow.h" -#include "scribblearea.h" - -//! [0] -MainWindow::MainWindow() -{ - scribbleArea = new ScribbleArea; - setCentralWidget(scribbleArea); - - createActions(); - createMenus(); - - setWindowTitle(tr("Scribble")); - resize(500, 500); -} -//! [0] - -//! [1] -void MainWindow::closeEvent(QCloseEvent *event) -//! [1] //! [2] -{ - if (maybeSave()) { - event->accept(); - } else { - event->ignore(); - } -} -//! [2] - -//! [3] -void MainWindow::open() -//! [3] //! [4] -{ - if (maybeSave()) { - QString fileName = QFileDialog::getOpenFileName(this, - tr("Open File"), QDir::currentPath()); - if (!fileName.isEmpty()) - scribbleArea->openImage(fileName); - } -} -//! [4] - -//! [5] -void MainWindow::save() -//! [5] //! [6] -{ - QAction *action = qobject_cast<QAction *>(sender()); - QByteArray fileFormat = action->data().toByteArray(); - saveFile(fileFormat); -} -//! [6] - -//! [7] -void MainWindow::penColor() -//! [7] //! [8] -{ - QColor newColor = QColorDialog::getColor(scribbleArea->penColor()); - if (newColor.isValid()) - scribbleArea->setPenColor(newColor); -} -//! [8] - -//! [9] -void MainWindow::penWidth() -//! [9] //! [10] -{ - bool ok; - int newWidth = QInputDialog::getInteger(this, tr("Scribble"), - tr("Select pen width:"), - scribbleArea->penWidth(), - 1, 50, 1, &ok); - if (ok) - scribbleArea->setPenWidth(newWidth); -} -//! [10] - -//! [11] -void MainWindow::about() -//! [11] //! [12] -{ - QMessageBox::about(this, tr("About Scribble"), - tr("<p>The <b>Scribble</b> example shows how to use QMainWindow as the " - "base widget for an application, and how to reimplement some of " - "QWidget's event handlers to receive the events generated for " - "the application's widgets:</p><p> We reimplement the mouse event " - "handlers to facilitate drawing, the paint event handler to " - "update the application and the resize event handler to optimize " - "the application's appearance. In addition we reimplement the " - "close event handler to intercept the close events before " - "terminating the application.</p><p> The example also demonstrates " - "how to use QPainter to draw an image in real time, as well as " - "to repaint widgets.</p>")); -} -//! [12] - -//! [13] -void MainWindow::createActions() -//! [13] //! [14] -{ - openAct = new QAction(tr("&Open..."), this); - openAct->setShortcuts(QKeySequence::Open); - connect(openAct, SIGNAL(triggered()), this, SLOT(open())); - - foreach (const QByteArray &format, QImageWriter::supportedImageFormats()) { - QString text = tr("%1...").arg(QString(format).toUpper()); - - QAction *action = new QAction(text, this); - action->setData(format); - connect(action, SIGNAL(triggered()), this, SLOT(save())); - saveAsActs.append(action); - } - - printAct = new QAction(tr("&Print..."), this); - connect(printAct, SIGNAL(triggered()), scribbleArea, SLOT(print())); - - exitAct = new QAction(tr("E&xit"), this); - exitAct->setShortcuts(QKeySequence::Quit); - connect(exitAct, SIGNAL(triggered()), this, SLOT(close())); - - penColorAct = new QAction(tr("&Pen Color..."), this); - connect(penColorAct, SIGNAL(triggered()), this, SLOT(penColor())); - - penWidthAct = new QAction(tr("Pen &Width..."), this); - connect(penWidthAct, SIGNAL(triggered()), this, SLOT(penWidth())); - - clearScreenAct = new QAction(tr("&Clear Screen"), this); - clearScreenAct->setShortcut(tr("Ctrl+L")); - connect(clearScreenAct, SIGNAL(triggered()), - scribbleArea, SLOT(clearImage())); - - aboutAct = new QAction(tr("&About"), this); - connect(aboutAct, SIGNAL(triggered()), this, SLOT(about())); - - aboutQtAct = new QAction(tr("About &Qt"), this); - connect(aboutQtAct, SIGNAL(triggered()), qApp, SLOT(aboutQt())); -} -//! [14] - -//! [15] -void MainWindow::createMenus() -//! [15] //! [16] -{ - saveAsMenu = new QMenu(tr("&Save As"), this); - foreach (QAction *action, saveAsActs) - saveAsMenu->addAction(action); - - fileMenu = new QMenu(tr("&File"), this); - fileMenu->addAction(openAct); - fileMenu->addMenu(saveAsMenu); - fileMenu->addAction(printAct); - fileMenu->addSeparator(); - fileMenu->addAction(exitAct); - - optionMenu = new QMenu(tr("&Options"), this); - optionMenu->addAction(penColorAct); - optionMenu->addAction(penWidthAct); - optionMenu->addSeparator(); - optionMenu->addAction(clearScreenAct); - - helpMenu = new QMenu(tr("&Help"), this); - helpMenu->addAction(aboutAct); - helpMenu->addAction(aboutQtAct); - - menuBar()->addMenu(fileMenu); - menuBar()->addMenu(optionMenu); - menuBar()->addMenu(helpMenu); -} -//! [16] - -//! [17] -bool MainWindow::maybeSave() -//! [17] //! [18] -{ - if (scribbleArea->isModified()) { - QMessageBox::StandardButton ret; - ret = QMessageBox::warning(this, tr("Scribble"), - tr("The image has been modified.\n" - "Do you want to save your changes?"), - QMessageBox::Save | QMessageBox::Discard - | QMessageBox::Cancel); - if (ret == QMessageBox::Save) { - return saveFile("png"); - } else if (ret == QMessageBox::Cancel) { - return false; - } - } - return true; -} -//! [18] - -//! [19] -bool MainWindow::saveFile(const QByteArray &fileFormat) -//! [19] //! [20] -{ - QString initialPath = QDir::currentPath() + "/untitled." + fileFormat; - - QString fileName = QFileDialog::getSaveFileName(this, tr("Save As"), - initialPath, - tr("%1 Files (*.%2);;All Files (*)") - .arg(QString(fileFormat.toUpper())) - .arg(QString(fileFormat))); - if (fileName.isEmpty()) { - return false; - } else { - return scribbleArea->saveImage(fileName, fileFormat); - } -} -//! [20] diff --git a/src/tools/qdoc/doc/examples/minimum.qdocconf b/src/tools/qdoc/doc/examples/minimum.qdocconf deleted file mode 100644 index e360685f1d..0000000000 --- a/src/tools/qdoc/doc/examples/minimum.qdocconf +++ /dev/null @@ -1,38 +0,0 @@ -# QDoc is a tool that constantly evolves to suit our needs, -# and there are some compatibility issues between old and new -# practices. For that reason, any QDoc configuration file needs to -# include compat.qdocconf. - -#include(compat.qdocconf) - - -# The outputdir variable specifies the directory -# where QDoc will put the generated documentation. - -outputdir = html - - -# The headerdirs variable specifies the directories -# containing the header files associated -# with the .cpp source files used in the documentation. - -headerdirs = . - - -# The sourcedirs variable specifies the -# directories containing the .cpp or .qdoc -# files used in the documentation. - -#sourcedirs = . - - -# The exampledirs variable specifies the directories containing -# the source code of the example files. - -exampledirs = . - - -# The imagedirs variable specifies the -# directories containing the images used in the documentation. - -imagedirs = ./images diff --git a/src/tools/qdoc/doc/examples/objectmodel.qdocinc b/src/tools/qdoc/doc/examples/objectmodel.qdocinc deleted file mode 100644 index 02b5991c4d..0000000000 --- a/src/tools/qdoc/doc/examples/objectmodel.qdocinc +++ /dev/null @@ -1,11 +0,0 @@ -\section1 Qt Object Model - -The standard C++ object model provides very efficient runtime support -for the object paradigm. But its static nature is inflexibile in -certain problem domains. Graphical user interface programming is a -domain that requires both runtime efficiency and a high level of -flexibility. Qt provides this, by combining the speed of C++ with the -flexibility of the Qt Object Model. - -... - diff --git a/src/tools/qdoc/doc/examples/qml.qdoc.sample b/src/tools/qdoc/doc/examples/qml.qdoc.sample deleted file mode 100644 index cacd912242..0000000000 --- a/src/tools/qdoc/doc/examples/qml.qdoc.sample +++ /dev/null @@ -1,116 +0,0 @@ -/**************************************************************************** -** -** Copyright (C) 2015 The Qt Company Ltd. -** Contact: http://www.qt.io/licensing/ -** -** This file is part of the documentation of the Qt Toolkit. -** -** $QT_BEGIN_LICENSE:FDL$ -** Commercial License Usage -** Licensees holding valid commercial Qt licenses may use this file in -** accordance with the commercial license agreement provided with the -** Software or, alternatively, in accordance with the terms contained in -** a written agreement between you and The Qt Company. For licensing terms -** and conditions see http://www.qt.io/terms-conditions. For further -** information use the contact form at http://www.qt.io/contact-us. -** -** GNU Free Documentation License Usage -** Alternatively, this file may be used under the terms of the GNU Free -** Documentation License version 1.3 as published by the Free Software -** Foundation and appearing in the file included in the packaging of -** this file. Please review the following information to ensure -** the GNU Free Documentation License version 1.3 requirements -** will be met: http://www.gnu.org/copyleft/fdl.html. -** $QT_END_LICENSE$ -** -****************************************************************************/ - -//![qmltype] - \qmltype TextEdit - \instantiates QQuickTextEdit - \inqmlmodule QtQuick - \ingroup qtquick-visual - \ingroup qtquick-input - \inherits Item - \brief Displays multiple lines of editable formatted text - - The TextEdit item displays a block of editable, formatted text. - - It can display both plain and rich text. For example: - - \qml - TextEdit { - width: 240 - text: "<b>Hello</b> <i>World!</i>" - font.family: "Helvetica" - font.pointSize: 20 - color: "blue" - focus: true - } - \endqml - - \image declarative-textedit.gif - - ... omitted detailed description - - \sa Text, TextInput, {examples/quick/text/textselection}{Text Selection example} -//![qmltype] - -//![function] -/* - \qmlmethod QtQuick2::ListModel::remove(int index, int count = 1) - - Deletes the content at \a index from the model. - - \sa clear() -*/ -void QQuickListModel::remove(QQmlV8Function *args) -//! [function] - -//! [return] -/* - Returns \c true if a QScroller object was already created for \a target; \c false otherwise. - - \sa scroller() -*/ -bool QScroller::hasScroller(QObject *target) -//! [return] - -//! [property] -/* - \property QVariantAnimation::duration - \brief the duration of the animation - - This property describes the duration in milliseconds of the - animation. The default duration is 250 milliseconds. - - \sa QAbstractAnimation::duration() - */ -int QVariantAnimation::duration() const -//! [property] - -//! [signals] -/* - This signal is emitted when the user clicks the button. A click is defined - as a press followed by a release. The corresponding handler is - \c onClicked. -*/ -signal clicked() -//! [signals] - -//! [enums] -/*! -\qmlproperty enumeration QtQuick2::Text::font.weight - -Sets the font's weight. - -The weight can be one of: -\list -\li Font.Light -\li Font.Normal - the default -\li Font.DemiBold -\li Font.Bold -\li Font.Black -\endlist -*/ -//! [enums] diff --git a/src/tools/qdoc/doc/examples/samples.qdocinc b/src/tools/qdoc/doc/examples/samples.qdocinc deleted file mode 100644 index d5679fdcd8..0000000000 --- a/src/tools/qdoc/doc/examples/samples.qdocinc +++ /dev/null @@ -1,109 +0,0 @@ -/**************************************************************************** -** -** Copyright (C) 2015 The Qt Company Ltd. -** Contact: http://www.qt.io/licensing/ -** -** This file is part of the documentation of the Qt Toolkit. -** -** $QT_BEGIN_LICENSE:FDL$ -** Commercial License Usage -** Licensees holding valid commercial Qt licenses may use this file in -** accordance with the commercial license agreement provided with the -** Software or, alternatively, in accordance with the terms contained in -** a written agreement between you and The Qt Company. For licensing terms -** and conditions see http://www.qt.io/terms-conditions. For further -** information use the contact form at http://www.qt.io/contact-us. -** -** GNU Free Documentation License Usage -** Alternatively, this file may be used under the terms of the GNU Free -** Documentation License version 1.3 as published by the Free Software -** Foundation and appearing in the file included in the packaging of -** this file. Please review the following information to ensure -** the GNU Free Documentation License version 1.3 requirements -** will be met: http://www.gnu.org/copyleft/fdl.html. -** $QT_END_LICENSE$ -** -****************************************************************************/ - -//! [qvector3d-class] -/*! - \class QVector3D - \brief The QVector3D class represents a vector or vertex in 3D space. - \since 4.6 - \ingroup painting-3D - - Vectors are one of the main building blocks of 3D representation and - drawing. They consist of three coordinates, traditionally called - x, y, and z. - - The QVector3D class can also be used to represent vertices in 3D space. - We therefore do not need to provide a separate vertex class. - - \b{Note:} By design values in the QVector3D instance are stored as \c float. - This means that on platforms where the \c qreal arguments to QVector3D - functions are represented by \c double values, it is possible to - lose precision. - - \sa QVector2D, QVector4D, QQuaternion -*/ -//! [qvector3d-class] - -//! [qvector3d-function] -/*! - \fn QVector3D::QVector3D(const QPoint& point) - - Constructs a vector with x and y coordinates from a 2D \a point, and a - z coordinate of 0. -*/ -//! [qvector3d-function] - -//! [sample-page] -/*! - \page generic-guide.html - \title Generic QDoc Guide - \nextpage Creating QDoc Configuration Files - There are three essential materials for generating documentation with qdoc: - - \list - \li \c qdoc binary - \li \c qdocconf configuration files - \li \c Documentation in \c C++, \c QML, and \c .qdoc files - \endlist -*/ -//! [sample-page] - -//! [sample-faq] -/*! - \page altruism-faq.html faq - \title Altruism Frequently Asked Questions - - \brief All the questions about altruism, answered. - - ... -*/ -//! [sample-faq] - -//! [sample-example] -/*! - \title UI Components: Tab Widget Example - \example declarative/ui-components/tabwidget - - This example shows how to create a tab widget. It also demonstrates how - \l {Property aliases}{property aliases} and - \l {Introduction to the QML Language#Default Properties}{default properties} can be used to collect and - assemble the child items declared within an \l Item. - - \image qml-tabwidget-example.png -*/ -//! [sample-example] - -//! [sample-overview] -/*! - \page overview-qt-technology.html overview - \title Overview of a Qt Technology - - \brief provides a technology never seen before. - -*/ -//! [sample-overview] - diff --git a/src/tools/qdoc/doc/examples/signalandslots.qdocinc b/src/tools/qdoc/doc/examples/signalandslots.qdocinc deleted file mode 100644 index e14ede1441..0000000000 --- a/src/tools/qdoc/doc/examples/signalandslots.qdocinc +++ /dev/null @@ -1,9 +0,0 @@ -\section1 Signals and Slots - -Signals and slots are used for communication between objects. The signals and -slots mechanism is a central feature of Qt and probably the part that differs -most from the features provided by other frameworks. - -\section2 Introduction - -In GUI programming, when we ... diff --git a/src/tools/qdoc/doc/files/basicqt.qdoc.sample b/src/tools/qdoc/doc/files/basicqt.qdoc.sample deleted file mode 100644 index ce8df096fa..0000000000 --- a/src/tools/qdoc/doc/files/basicqt.qdoc.sample +++ /dev/null @@ -1,67 +0,0 @@ - /*! - \page basicqt.html - \contentspage {Basic Qt} {Contents} - \nextpage Getting Started - - \indexpage Index - \startpage Basic Qt - - \title Basic Qt - - The Qt toolkit is a C++ class library and a set of tools for - building multiplatform GUI programs using a "write once, - compile anywhere approach". - - Table of contents: - - \list - \li \l {Getting Started} - \li \l {Creating Dialogs} - \li \l {Creating Main Windows} - \endlist - */ - - /*! - \page gettingstarted.html - \previouspage Basic Qt - \contentspage {Basic Qt} {Contents} - \nextpage Creating Dialogs - - \indexpage Index - \startpage Basic Qt - - \title Getting Started - - This chapter shows how to combine basic C++ with the - functionality provided by Qt to create a few small graphical - interface (GUI) applications. -*/ - -/ *! - \page creatingdialogs.html - \previouspage Getting Started - \contentspage {Basic Qt} {Contents} - - \indexpage Index - \startpage Basic Qt - - \title Creating Dialogs - - This chapter will teach you how to create dialog boxes using Qt. -*/ - -/*! - \page index.html - - \indexpage Index - \startpage Basic Qt - - \title Index - - \list - \li \l {Basic Qt} - \li \l {Creating Dialogs} - \li \l {Getting Started} - \endlist -*/ - diff --git a/src/tools/qdoc/doc/files/compat.qdocconf b/src/tools/qdoc/doc/files/compat.qdocconf deleted file mode 100644 index 3e7ea6c891..0000000000 --- a/src/tools/qdoc/doc/files/compat.qdocconf +++ /dev/null @@ -1,12 +0,0 @@ -alias.include = input - -macro.0 = "\\\\0" -macro.b = "\\\\b" -macro.n = "\\\\n" -macro.r = "\\\\r" -macro.img = "\\image" -macro.endquote = "\\endquotation" -macro.relatesto = "\\relates" - -spurious = "Missing comma in .*" \ - "Missing pattern .*" diff --git a/src/tools/qdoc/doc/files/qtgui.qdocconf b/src/tools/qdoc/doc/files/qtgui.qdocconf deleted file mode 100644 index 0b2d281081..0000000000 --- a/src/tools/qdoc/doc/files/qtgui.qdocconf +++ /dev/null @@ -1,49 +0,0 @@ -include($QT_INSTALL_DOCS/global/qt-module-defaults.qdocconf) - -project = QtGui -description = Qt GUI Reference Documentation -version = $QT_VERSION - -examplesinstallpath = qtbase/gui - -qhp.projects = QtGui - -qhp.QtGui.file = qtgui.qhp -qhp.QtGui.namespace = org.qt-project.qtgui.$QT_VERSION_TAG -qhp.QtGui.virtualFolder = qtgui -qhp.QtGui.indexTitle = Qt GUI -qhp.QtGui.indexRoot = - -qhp.QtGui.filterAttributes = qtgui $QT_VERSION qtrefdoc -qhp.QtGui.customFilters.Qt.name = Qtgui $QT_VERSION -qhp.QtGui.customFilters.Qt.filterAttributes = qtgui $QT_VERSION - -qhp.QtGui.subprojects = classes -qhp.QtGui.subprojects.classes.title = C++ Classes -qhp.QtGui.subprojects.classes.indexTitle = Qt GUI C++ Classes -qhp.QtGui.subprojects.classes.selectors = class fake:headerfile -qhp.QtGui.subprojects.classes.sortPages = true - -tagfile = ../../../doc/qtgui/qtgui.tags - -depends += \ - qtcore \ - qtnetwork \ - qtopengl \ - qtsvg \ - qtqml \ - qtquick \ - qtwidgets \ - qtdoc - -headerdirs += .. - -sourcedirs += .. \ - ../../../examples/gui/doc/src - -exampledirs += ../../../examples/gui \ - snippets - -imagedirs += images \ - ../../../examples/gui/doc/images \ - ../../../doc/src/images \ diff --git a/src/tools/qdoc/doc/images/happy.gif b/src/tools/qdoc/doc/images/happy.gif Binary files differdeleted file mode 100644 index a4597f6fa8..0000000000 --- a/src/tools/qdoc/doc/images/happy.gif +++ /dev/null diff --git a/src/tools/qdoc/doc/images/happyguy.jpg b/src/tools/qdoc/doc/images/happyguy.jpg Binary files differdeleted file mode 100644 index e8604793c2..0000000000 --- a/src/tools/qdoc/doc/images/happyguy.jpg +++ /dev/null diff --git a/src/tools/qdoc/doc/images/link-to-qquickitem.png b/src/tools/qdoc/doc/images/link-to-qquickitem.png Binary files differdeleted file mode 100644 index 00e03c3717..0000000000 --- a/src/tools/qdoc/doc/images/link-to-qquickitem.png +++ /dev/null diff --git a/src/tools/qdoc/doc/images/links-to-broken-links.png b/src/tools/qdoc/doc/images/links-to-broken-links.png Binary files differdeleted file mode 100644 index 775143bd4a..0000000000 --- a/src/tools/qdoc/doc/images/links-to-broken-links.png +++ /dev/null diff --git a/src/tools/qdoc/doc/images/links-to-links.png b/src/tools/qdoc/doc/images/links-to-links.png Binary files differdeleted file mode 100644 index 9d2cc2fae5..0000000000 --- a/src/tools/qdoc/doc/images/links-to-links.png +++ /dev/null diff --git a/src/tools/qdoc/doc/images/qa-table.png b/src/tools/qdoc/doc/images/qa-table.png Binary files differdeleted file mode 100644 index 5818739fac..0000000000 --- a/src/tools/qdoc/doc/images/qa-table.png +++ /dev/null diff --git a/src/tools/qdoc/doc/images/qt-logo.png b/src/tools/qdoc/doc/images/qt-logo.png Binary files differdeleted file mode 100644 index 6b72d5fb72..0000000000 --- a/src/tools/qdoc/doc/images/qt-logo.png +++ /dev/null diff --git a/src/tools/qdoc/doc/images/training.jpg b/src/tools/qdoc/doc/images/training.jpg Binary files differdeleted file mode 100644 index c2ce5c3b21..0000000000 --- a/src/tools/qdoc/doc/images/training.jpg +++ /dev/null diff --git a/src/tools/qdoc/doc/qa-pages.qdoc b/src/tools/qdoc/doc/qa-pages.qdoc deleted file mode 100644 index a96673901a..0000000000 --- a/src/tools/qdoc/doc/qa-pages.qdoc +++ /dev/null @@ -1,109 +0,0 @@ -/**************************************************************************** -** -** Copyright (C) 2015 The Qt Company Ltd. -** Contact: http://www.qt.io/licensing/ -** -** This file is part of the documentation of the Qt Toolkit. -** -** $QT_BEGIN_LICENSE:FDL$ -** Commercial License Usage -** Licensees holding valid commercial Qt licenses may use this file in -** accordance with the commercial license agreement provided with the -** Software or, alternatively, in accordance with the terms contained in -** a written agreement between you and The Qt Company. For licensing terms -** and conditions see http://www.qt.io/terms-conditions. For further -** information use the contact form at http://www.qt.io/contact-us. -** -** GNU Free Documentation License Usage -** Alternatively, this file may be used under the terms of the GNU Free -** Documentation License version 1.3 as published by the Free Software -** Foundation and appearing in the file included in the packaging of -** this file. Please review the following information to ensure -** the GNU Free Documentation License version 1.3 requirements -** will be met: http://www.gnu.org/copyleft/fdl.html. -** $QT_END_LICENSE$ -** -****************************************************************************/ - -/*! - \page 28-qdoc-qa-pages.html - \previouspage Generating DITA XML Output - \contentspage QDoc Manual - \nextpage QDoc Manual - - \title QA Pages - - qdoc can generate some extra HTML pages that can be useful for - debugging qdoc documentation. These \e QA pages make it easier for - those who write documentation to find links that either go to the - wrong targets or don't go anywhere at all. - - \section2 Generating the QA Pages - - Add \c {-write-qa-pages} to the command line to tell qdoc to - generate the QA pages. If this option is not provided, the QA - pages will not be generated, and previolusly generated QA pages - will be deleted. - - \section2 Finding the Module's Main QA Page - - The main QA page for a module is not linked into the module's - generated documentation, but it is located in the same output - directory. To find the top-level QA page for module \e {xxx}, set - your browser to the qdoc output directory for module \e {xxx}. - Several files whose names begin with \e {aaa} appear at the top of - the list. These are the QA pages for module \e{xxx}. The file - names begin with \e {aaa} to ensure that they are easy to find at - the top of the directory. - - For module \e{xxx}, find the file \e{aaa-xxx-qa-page.html}. This - is the top-level QA page for module \e{xxx}. Load that file into - the browser. The top-level QA page shows a table that contains - links to several QA sub-pages. - - For example, the main QA page for QtCore is \c{aaa-qtcore-qa-page.html}. - This was the table for QtCore at one point: - - \image qa-table.png - - Each table entry shows the number of links from QtCore to some - other module, except for the last entry, which shows the number of - broken links in QtCore. Click the \b qtquick entry to load the QA - subpage showing the links from QtCore to QtQuick. - - \section2 Links To Links Page - - Clicking the \b qtquick table entry on the main QA page for QtCore - loads the QA subpage showing a table containing all the links from - QtCore to QtQuick. The table contains all the links constructed - with the \l {l-command} {\\l command}, as well as the autolinks. - - \image links-to-links.png - - At the time this table was generated, there were six links from - QtCore to QtQuick. The first column of each table entry contains - a link to some link in QtCore. The link text as it appears in - QtCore is shown. The second and third columns contain the source - file name and line number for where qdoc saw the link in a qdoc - comment. - - \note The line number will normally refer to the first line of the - comment where qdoc saw the link. - - Clicking on a link in the table takes you to that link in the - documentation. There the link will be marked with three red - asterisks. For example, clicking on the link in the fifth table - entry takes you here: - - \image link-to-qquickitem.png - - The link is marked with three red asterisks. Now you can click on - the actual link to check that it goes to the correct place. In - this case, the link should go to the reference page for the - QQuickItem class. You can check each link in the table this - way. If you find a link that goes to the wrong place, use the - source file name and line number to find the link, and fix the - problem using the square bracket notation for the \l {l-command} - {\\l command}. - - */ diff --git a/src/tools/qdoc/doc/qdoc-guide/qdoc-guide.qdoc b/src/tools/qdoc/doc/qdoc-guide/qdoc-guide.qdoc deleted file mode 100644 index af1fa1ba14..0000000000 --- a/src/tools/qdoc/doc/qdoc-guide/qdoc-guide.qdoc +++ /dev/null @@ -1,632 +0,0 @@ -/**************************************************************************** -** -** Copyright (C) 2015 The Qt Company Ltd. -** Contact: http://www.qt.io/licensing/ -** -** This file is part of the documentation of the Qt Toolkit. -** -** $QT_BEGIN_LICENSE:FDL$ -** Commercial License Usage -** Licensees holding valid commercial Qt licenses may use this file in -** accordance with the commercial license agreement provided with the -** Software or, alternatively, in accordance with the terms contained in -** a written agreement between you and The Qt Company. For licensing terms -** and conditions see http://www.qt.io/terms-conditions. For further -** information use the contact form at http://www.qt.io/contact-us. -** -** GNU Free Documentation License Usage -** Alternatively, this file may be used under the terms of the GNU Free -** Documentation License version 1.3 as published by the Free Software -** Foundation and appearing in the file included in the packaging of -** this file. Please review the following information to ensure -** the GNU Free Documentation License version 1.3 requirements -** will be met: http://www.gnu.org/copyleft/fdl.html. -** $QT_END_LICENSE$ -** -****************************************************************************/ -/*! - \page qdoc-guide.html - \title Getting Started with QDoc - \nextpage Creating QDoc Configuration Files - - Qt uses QDoc to generate its documentation set into HTML and DITA XML - formats. QDoc uses a set of configuration files to generate documentation - from QDoc comments. The comments have types called - \l{writing-topic-commands}{topics} that determine whether a comment is a - class documentation or a property documentation. A comment may also have - \l{writing-markup}{mark up} to enhance the layout and formatting of the - final output. - - There are three essential materials for generating documentation with qdoc: - \list - \li \c QDoc binary - \li \c qdocconf configuration files - \li \c Documentation in \c C++, \c QML, and \c .qdoc files - \endlist - - This section intends to cover the basic necessities for creating a - documentation set. Additionally, the guide presents special considerations - and options to documenting non-C++ API documentation as well as QML - documentation. Finally, the guide will provide a sample project - documentation and an example of a QML type documentation. - - For specific QDoc information, consult the - \l{QDoc Manual}. - \section1 Chapters - - \list 1 - \li \l{Creating QDoc Configuration Files} - \li \l{Writing Documentation} - \li \l{Categories of Documentation} - \list - \li \l{C++ Documentation Style} - \li \l{QML Documentation Style} - \endlist - \li \l{QML Documentation Example} - \endlist - -*/ - -/*! - \page qdoc-guide-conf.html - \title Creating QDoc Configuration Files - \previouspage Getting Started with QDoc - \nextpage Writing Documentation - To generate documentation, QDoc uses configuration files, with the - \c qdocconf extension, to store configuration settings. - - The \l{The QDoc Configuration File} article covers the various configuration - variables in greater detail. - - \section1 QDoc Configuration Files - QDoc's configuration settings can reside in a single \e qdocconf file, but - can also be in other qdocconf files. The \c {include(<filepath>)} command - allows configuration files to include other configuration files. - - QDoc has two outputs, HTML documentation and documentation in DITA XML - format. The main distinction between the two outputs is that HTML - documentation needs to have its HTML styling information in the - configuration files. DITA XML documentation does not, and a separate process - can style the documentation in DITA at a later time. DITA XML is therefore - more flexible in allowing different styles to apply to the same information. - - To run qdoc, the project configuration file is supplied as an argument. - \code - qdoc project.qdocconf - \endcode - - The project configuration contains information that qdoc uses to create the - documentation. - - \section2 Project Information - - QDoc uses the \c project information to generate the documentation. - \code - project = QDoc Project - description = Sample QDoc project - \endcode - - \target qdoc-input-output-dir - \section2 Input and Output Directories - - Specifying the path to the source directories allow QDoc to find sources and - generate documentation. - - \badcode - sourcedirs = <path to source code> - exampledirs = <path to examples directory> - imagedirs = <path to image directory> - - sources.fileextensions = "*.cpp *.qdoc *.mm *.qml" - headers.fileextensions = "*.h *.ch *.h++ *.hh *.hpp *.hxx" - examples.fileextensions = "*.cpp *.h *.js *.xq *.svg *.xml *.ui *.qhp *.qhcp *.qml" - examples.imageextensions = "*.png *.jpeg *.jpg *.gif *.mng" - \endcode - - QDoc will process headers and sources from the ones specified in the - \c fileextensions variable. - - Likewise, QDoc needs the path to the output directory. The \c outputformats - variable determines the type of documentation. These variables should be - in separate configuration files to modularize the documentation build. - \badcode - outputdir = $SAMPLE_PROJECT/doc/html - outputformats = HTML - \endcode - - QDoc can resolve the paths relative to the qdocconf file as well as - environment variables. - - \note During each QDoc run, the output directory is deleted. - \section2 Extra Files - - QDoc will output generated documentation into the directory specified in - the \l{Input and Output Directories}{output} directory. It is also possible - to specify extra files that QDoc should export. - - \badcode - HTML.extraimages = extraImage.png \ - extraImage2.png - \endcode - - The \c extraImage.png and the \c extraImage2.png files will be copied to the - HTML output directory. - - \section2 Qt Help Framework Configuration - - QDoc will also export a \e {Qt Help Project} file, in a \c qhp file. - The qhp file is then used by the \c qhelpgenerator to package the - documentation into a \c qch file. Qt Creator and Qt Assistant reads the qch - file to display the documentation. - - The \l {Creating Help Project Files} article covers the configuration - options. - - \section2 HTML Configuration - - QDoc has an HTML generator that will export a set of documentation into - HTML files using various configuration settings. QDoc will place the - generated documentation into the directory specified by the \c outputdir - variable. - - \badcode - outputformats = HTML - outputdir = <path to output directory> - \endcode - - QDoc needs to know where the styles and templates for generating HTML - are located. Typically, the templates directory contains a \c scripts, - \c images, and a \c style directory, containing scripts and CSS files. - - \badcode - HTML.templatedir = <path to templates> - \endcode - - The main configuration variables are: - \badcode - HTML.postheader - HTML.postpostheader - HTML.postheader - HTML.footer - - HTML.headerstyles - HTML.stylesheets = style.css \ - style1.css - - HTML.scripts = script.js - \endcode - - The \c{HTML.headerstyles} variable inserts the style information into the - HTML file and the \c{HTML.stylesheets} specifies which files QDoc should - copy into the output directory. As well, QDoc will embed the string - in the \c postheader, \c footer, and related variables into each HTML file. - - The \l {HTML Specific Configuration Variables} article outlines the usage - of each variable. - - \section2 DITA XML Configuration - - DITA XML output is enabled using the \c outputformats variable. Unlike HTML - documentation, QDoc does not need HTML style templates for generating - documentation in DITA XML format. - - \badcode - outputformats = DITAXML - outputdir - \endcode - - \section2 Qt Index Reference - Documentation projects can link to Qt APIs and other articles by specifying - the path to the \c qt.index file. When qdoc generates the Qt Reference - Documentation, it will also generate an index file, containing the URLs to - the articles. Other projects can use the links in the index file so that - they can link to other articles and API documentation within Qt. - - \badcode - indexes = $QT_INSTALL_DOCS/html/qt.index $OTHER_PROJECT/html/qt.index - \endcode - It is possible to specify multiple index files from several projects. - - \section1 Macros and Other Configurations - - Macros for substituting HTML characters exist and are helpful for generating - specific HTML-valid characters. - - \badcode - macro.pi.HTML = "Π" - \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/tools/qdoc/doc/qdoc-guide/qtwritingstyle-cpp.qdoc b/src/tools/qdoc/doc/qdoc-guide/qtwritingstyle-cpp.qdoc deleted file mode 100644 index 8cbf74cd67..0000000000 --- a/src/tools/qdoc/doc/qdoc-guide/qtwritingstyle-cpp.qdoc +++ /dev/null @@ -1,187 +0,0 @@ -/**************************************************************************** -** -** Copyright (C) 2015 The Qt Company Ltd. -** Contact: http://www.qt.io/licensing/ -** -** This file is part of the documentation of the Qt Toolkit. -** -** $QT_BEGIN_LICENSE:FDL$ -** Commercial License Usage -** Licensees holding valid commercial Qt licenses may use this file in -** accordance with the commercial license agreement provided with the -** Software or, alternatively, in accordance with the terms contained in -** a written agreement between you and The Qt Company. For licensing terms -** and conditions see http://www.qt.io/terms-conditions. For further -** information use the contact form at http://www.qt.io/contact-us. -** -** GNU Free Documentation License Usage -** Alternatively, this file may be used under the terms of the GNU Free -** Documentation License version 1.3 as published by the Free Software -** Foundation and appearing in the file included in the packaging of -** this file. Please review the following information to ensure -** the GNU Free Documentation License version 1.3 requirements -** will be met: http://www.gnu.org/copyleft/fdl.html. -** $QT_END_LICENSE$ -** -****************************************************************************/ - -/*! -\page qtwritingstyle-cpp.html -\title C++ Documentation Style -\brief Style guidelines for C++ documentation - -To generate the documentation, QDoc goes through the source code and generates -documentation for C++ types such as classes. QDoc then associates member -functions, properties, and other types to the appropriate class. - -Note that the documentation must be in the implementation files such as \c .cpp. - -\section1 Class Documentation - -Class documentation is generated using the \l{class-command}{\\class} command and -the name of the class as the first argument. - -\snippet examples/cpp.qdoc.sample class - -\l{Context commands} add information about the class, such as its module or -which version the class was added. - -Some common context commands are: -\list -\li \l{brief-command}{\\brief} - the class' brief description \b (mandatory) -\li \l{since-command}{\\since} - the version to which the class was added \b (mandatory) -\li \l{internal-command}{\\internal} - marks the class as internal. Internal -classes do not appear in the public API documentation. -\endlist - - -\section2 The Brief and Detailed Description - -The \e{brief description} is marked with the \l{brief-command}{\\brief} command -and it is for summarizing the purpose or functionality of the class. For C++ -classes, QDoc will take the class and create annotated information for the -class. The annotated information appears in lists and tables which display the -class. - -The C++ brief should start with: -\code -"The <C++ class name> class" -\endcode - -The \e{detailed description} section starts after the brief description. It -provides more information about the class. The detailed description may contain -images, snippet code, or links to other relevant documents. There -must be an empty line which separates the brief and detailed description. - -\section1 Member Functions - -Typically, function documentation immediately precedes the implementation of the -function in the \c .cpp file. For function documentation that is not immediately -above the implementation, the \l{fn-command}{\\fn} is needed. - -\snippet examples/cpp.qdoc.sample function - -The function documentation starts with a verb, indicating the operation the -function performs. This also applies to constructors and destructors. - -Some common verbs for function documentation: -\list -\li "Constructs..." - for constructors -\li "Destroys..." - for destructors -\li "Returns..." - for accessor functions -\endlist - -The function documentation must document: -\list -\li the return type -\li the parameters -\li the actions of the functions -\endlist - -The \l{a-command}{\\a} command marks the parameter in the documentation. -The return type documentation should link to the type documentation or be -marked with the \l{c-command}{\\c} command in the case of boolean values. - -\snippet examples/cpp.qdoc.sample return - -\section1 Properties - -The property documentation resides immediately above the read function's -implementation. The \l{writing-topic-commands}{topic command} for properties is -\l{property-command}{\\property}. - -\snippet examples/cpp.qdoc.sample property - -Property documentation usually starts with "This property...", but these are -alternate expressions: -\list -\li "This property holds..." -\li "This property describes..." -\li "This property represents..." -\li "Returns \c true when... and \c false when..." - for properties that -are read. -\li "Sets the..." - for properties that configure a type. -\endlist - -Property documentation must include: -\list -\li description and behavior of the property -\li accepted values for the property -\li the default value of the property -\endlist -Similar to \l{Member Functions}{functions}, the default type may be linked -or marked with the \c{\c} command. - -An example of a value range style is: -\quotation -The values range from 0.0 (no blur) to maximumRadius (maximum blur). By default, the property is set to 0.0 (no blur). -\endquotation - -\section1 Signals, Notifiers, and Slots -The \l{writing-topic-commands}{topic command} for signals, notifiers, and slots -is \l{fn-command}{\\fn}. Signal documentation state when they are triggered -or emitted. - -\snippet examples/cpp.qdoc.sample signals - -Signal documentation typically begin with "This signal is triggered when...". -Here are alternate styles: -\list -\li "This signal is triggered when..." -\li "Triggered when..." -\li "Emitted when..." -\endlist - -For slots or notifiers, the condition when they are executed or triggered by -a signal should be documented. -\list -\li "Executed when..." -\li "This slot is executed when..." -\endlist - -For properties that have overloaded signals, QDoc groups the overloaded -notifiers together. To refer to a specific version of a notifier or signal, -simply refer to the property and mention that there are different versions of -the notifier. - -\snippet examples/cpp.qdoc.sample overloaded notifier - -\section1 Enums, Namespaces, and Other Types - -Enums, namespaces, and macros have a \l{writing-topic-commands}{topic command} for their documentation: -\list -\li \l{enum-command}{\\enum} -\li \l{typedef-command}{\\typedef} -\li \l{macro-command}{\\macro} -\endlist - -The language style for these types mention that they are an enum or a macro and -continues with the type description. - -For enumerations, the \l{value-command}{\\value} command is for listing the -values. QDoc creates a table of values for the enum. - -\snippet examples/cpp.qdoc.sample enums - -*/ - diff --git a/src/tools/qdoc/doc/qdoc-guide/qtwritingstyle-qml.qdoc b/src/tools/qdoc/doc/qdoc-guide/qtwritingstyle-qml.qdoc deleted file mode 100644 index 6955a042c2..0000000000 --- a/src/tools/qdoc/doc/qdoc-guide/qtwritingstyle-qml.qdoc +++ /dev/null @@ -1,164 +0,0 @@ -/**************************************************************************** -** -** Copyright (C) 2015 The Qt Company Ltd. -** Contact: http://www.qt.io/licensing/ -** -** This file is part of the documentation of the Qt Toolkit. -** -** $QT_BEGIN_LICENSE:FDL$ -** Commercial License Usage -** Licensees holding valid commercial Qt licenses may use this file in -** accordance with the commercial license agreement provided with the -** Software or, alternatively, in accordance with the terms contained in -** a written agreement between you and The Qt Company. For licensing terms -** and conditions see http://www.qt.io/terms-conditions. For further -** information use the contact form at http://www.qt.io/contact-us. -** -** GNU Free Documentation License Usage -** Alternatively, this file may be used under the terms of the GNU Free -** Documentation License version 1.3 as published by the Free Software -** Foundation and appearing in the file included in the packaging of -** this file. Please review the following information to ensure -** the GNU Free Documentation License version 1.3 requirements -** will be met: http://www.gnu.org/copyleft/fdl.html. -** $QT_END_LICENSE$ -** -****************************************************************************/ - -/*! -\page qtwritingstyle-qml.html -\title QML Documentation Style -\brief Style guidelines for QML documentation - -QDoc can process QML types defined as C++ classes and QML types defined in -\c .qml files. For C++ classes documented as QML types, the QDoc comments are -in the \c .cpp file while QML types defined in QML are in the \c .qml -file. The C++ classes must also be documented -documented with the QML \l{topic-commands}{topic commands}: - -\list -\li \l{qmlattachedproperty-command}{\\qmlattachedproperty} -\li \l{qmlattachedsignal-command}{\\qmlattachedsignal} -\li \l{qmlbasictype-command}{\\qmlbasictype} -\li \l{qmltype-command}{\\qmltype} -\li \l{qmlmethod-command}{\\qmlmethod} -\li \l{qmlproperty-command}{\\qmlproperty} -\li \l{qmlsignal-command}{\\qmlsignal} -\li \l{qmlmodule-command}{\\qmlmodule} -\li \l{inqmlmodule-command}{\\inqmlmodule} -\li \l{instantiates-command}{\\instantiates} -\endlist - -For QML types defined in \c .qml files, QDoc will parse the QML and determine -the properties, signals, and the type within the QML definition. The QDoc -block then needs to be immediately above the declaration. For QML types -implemented in C++, QDoc will output warnings if the C++ class documentation -does not exist. The class documentation may be marked as -\l{internal-command}{internal} if it is not a public API. - -\section1 QML Types - -The \l{qmltype-command}{\\qmltype} command is for QML type documentation. - -\snippet examples/qml.qdoc.sample qmltype - -The \l{instantiates-command}{\\instantiates} accepts the C++ class which -implements the QML type as the argument. For types implemented in QML, this -is not needed. - -The \e{brief description} provides a summary for the QML type. The brief does -not need to be a complete sentence and may start with a verb. QDoc will append -the brief description onto the QML type in tables and generated lists. - -\code -\qmltype ColorAnimation -\brief Animates changes in color values -\endcode - -Here are some alternate verbs for the brief statement: -\list -\li "Provides..." -\li "Specifies..." -\li "Describes..." -\endlist - -The \e{detailed description} follows the brief and may contain images, snippet, -and link to other documentation. - -\section1 Properties - -The property description focuses on what the property \e does and may use the -following style: - -Property documentation usually starts with "This property..." but for certain -properties, these are the common expressions: -\list -\li "This property holds..." -\li "This property describes..." -\li "This property represents..." -\li "Returns \c true when... and \c false when..." - for properties that -are marked \c{read-only}. -\li "Sets the..." - for properties that configure a type. -\endlist - -\section1 Signals and Handlers Documentation - -QML signals are documented either in the QML file or in the C++ implementation -with the \l{qmlsignal-command}{\\qmlsignal} command. Signal documentation -must include the condition for emitting the signal, mention the corresponding -signal handler, and document whether the signal accepts a parameter. - -\snippet examples/qml.qdoc.sample signals - -These are the possible documentation styles for signals: -\list -\li "This signal is triggered when..." -\li "Triggered when..." -\li "Emitted when..." -\endlist - -\section1 Methods and JavaScript Functions - -Typically, function documentation immediately precedes the implementation of the -function in the \c .cpp file. The \l{topic-commands}{topic command} for -functions is \l{fn-command}{\\fn}. For functions in QML or JavaScript, the -documentation must reside immediately above the function declaration. - -The function documentation starts with a verb, indicating the operation the -function performs. - -\snippet examples/qml.qdoc.sample function - -Some common verbs for function documentation: -\list -\li "Copies..." - for constructors -\li "Destroys..." - for destructors -\li "Returns..." - for accessor functions -\endlist - -The function documentation must document: -\list -\li the return type -\li the parameters -\li the actions of the functions -\endlist - -The \l{a-command}{\\a} command marks the parameter in the documentation. -The return type documentation should link to the type documentation or be -marked with the \l{c-command}{\\c} command in the case of boolean values. - -\section1 Enumerations - -QML enumerations are documented as QML properties with the -\l{qmlproperty-command}{\\qmlproperty} command. The type of the property -is \c enumeration. - -\snippet examples/qml.qdoc.sample enums - -The QDoc comment lists the values of the enumeration. If the enumeration is -implemented in C++, the documentation may link to the corresponding C++ -enumeration. However, the QDoc comment should advise that the enumeration -is a C++ enumeration. - -*/ - diff --git a/src/tools/qdoc/doc/qdoc-manual-DITA.qdoc b/src/tools/qdoc/doc/qdoc-manual-DITA.qdoc deleted file mode 100644 index 72882c8eb1..0000000000 --- a/src/tools/qdoc/doc/qdoc-manual-DITA.qdoc +++ /dev/null @@ -1,164 +0,0 @@ -/**************************************************************************** -** -** Copyright (C) 2015 The Qt Company Ltd. -** Contact: http://www.qt.io/licensing/ -** -** This file is part of the documentation of the Qt Toolkit. -** -** $QT_BEGIN_LICENSE:FDL$ -** Commercial License Usage -** Licensees holding valid commercial Qt licenses may use this file in -** accordance with the commercial license agreement provided with the -** Software or, alternatively, in accordance with the terms contained in -** a written agreement between you and The Qt Company. For licensing terms -** and conditions see http://www.qt.io/terms-conditions. For further -** information use the contact form at http://www.qt.io/contact-us. -** -** GNU Free Documentation License Usage -** Alternatively, this file may be used under the terms of the GNU Free -** Documentation License version 1.3 as published by the Free Software -** Foundation and appearing in the file included in the packaging of -** this file. Please review the following information to ensure -** the GNU Free Documentation License version 1.3 requirements -** will be met: http://www.gnu.org/copyleft/fdl.html. -** $QT_END_LICENSE$ -** -****************************************************************************/ - -/*! - \page 21-0-qdoc-creating-dita-maps.html - \previouspage Miscellaneous - \contentspage QDoc Manual - \nextpage The QDoc Configuration File - - \title Creating DITA Maps - - You can create DITA map files using three new qdoc commands, the \l{ditamap-command} - {ditamap} command, the \l{topicref-command} {topicref} command, and the \l{mapref-command} - {mapref} command. How these DITA maps will be used automatically or manually by the - documentation build process is still under consideration. This section will be updated - as the decisions are made. - - \section1 What is a DITA Map? - - A complete description of DITA can be found at the - \l{http://www.oasis-open.org/committees/tc_home.php?wg_abbrev=dita} - {OASIS Darwin Information Typing Architecture} site. - - An explanation of the DITA map is found at that site - \l{http://docs.oasis-open.org/dita/v1.2/os/spec/langref/map.html}{here}. - - \target ditamap-command - \section1 \\ditamap - - The \\ditamap command is for creating a DITA map using qdoc commands. - The \\ditamap command is a kind of \\page command that produces a - \e{.ditamap} instead of a \e{.html} or \e{.xml} file. The file that - is created actually contains XML text, but the \e{.ditamap} suffix is - used to identify the file as containing a DITA MAP. - - The argument is the name of the file to be created. In the following - example, the file \e{creator.ditamap} is output: - \code - \ditamap creator.ditamap - \endcode - - \target topicref-command - \section1 \\topicref \\endtopicref - - The \\topicref \\endtopicref commands are for creating a topicref - in the ditamap. The \\endtopicref command is required because - \\topicref commands can be nested. - - \\topicref has two arguments. The first argument becomes the value - of the \e navtitle attribute. Normally, you use the title of the - topic being referenced. This title is often what will appear in a - table of contents constructed from the ditamap. - - The second argument is the name of the page being referenced. The - second argument is actually optional, for example if you are using - a topicref as a container for other topicrefs and maprefs. It is - also optional if you want qdoc to find the page name for you by - looking up the title in its internal data structure. It is recommended - that you provide the second parameter if you know the page name. - - \code - \topicref {QML Module QtQuick 2} {qtquick-2.xml} - \mapref {Creator Manual} {creator-manual.ditamap} \endmapref - \topicref {QML Mouse Events} {qtquick2-mouseevents.xml} \endtopicref - \topicref {Property Binding} {qtquick2-propertybinding.xml} \endtopicref - \endtopicref - \endcode - - \target mapref-command - \section1 \\mapref - - The \\mapref command is for creating a mapref in the ditamap. A - mapref refers to another ditamap, which you want to include in - your ditamap. Like the \\topicref command, the \\mapref command - has two arguments, but for the \\mapref command, both arguments - are required. The arguments are essentially the same as described - for \\topicref, but for \\mapref, the second command must be the - name of another ditamap, i.e. it must have the \e{.ditamap} - suffix. You must provide the file name. qdoc can't look up the - file name for you. - - \code - \mapref {Creator Manual} {creator-manual.ditamap} \endmapref - \endcode - - \section1 An Example Ditamap Page - - The following example uses the three qdoc ditamap commands described above. - - \code - \ditamap creator.ditamap - \title The DITA Map for Creator - - \topicref {QML Module QtQuick 1} - \topicref {QML Mouse Events} \endtopicref - \topicref {Property Binding} \endtopicref - \endtopicref - - \topicref {QML Module QtQuick 2} {qtquick-2.xml} - \mapref {Creator Manual} {creator-manual.ditamap} \endmapref - \topicref {QML Mouse Events} {qtquick2-mouseevents.xml} \endtopicref - \topicref {Property Binding} {qtquick2-propertybinding.xml} \endtopicref - \endtopicref - - \topicref {QML Module QtQuick.Particles 2} {qtquick-particles-2.xml} - \topicref {Age} {qml-qtquick-particles2-age.xml} \endtopicref - \endtopicref - \endcode - - \section1 The Resulting Ditamap File - - This is the \e{.ditamap} file you get when you input the qdoc - ditamap page shown above. Note that you can write ditamap files - directly in XML just as easily as you can write them using the - qdoc commands. The choice is yours. - - \code - <?xml version="1.0" encoding="UTF-8"?> - <!DOCTYPE map PUBLIC "-//OASIS//DTD DITA Map//EN" "map.dtd"> - <map> - <topicmeta> - <shortdesc>The DITA Map for Creator</shortdesc> - </topicmeta> - <topicref navtitle="QML Module QtQuick 1" href="qtquick-1.xml"> - <topicref navtitle="QML Mouse Events" href="qtquick2-mouseevents.xml"/> - <topicref navtitle="Property Binding" href="qtquick2-propertybinding.xml"/> - </topicref> - <topicref navtitle="QML Module QtQuick 2" href="qtquick-2.xml"> - <mapref navtitle="Creator Manual" href="creator-manual.ditamap"/> - <topicref navtitle="QML Mouse Events" href="qtquick2-mouseevents.xml"/> - <topicref navtitle="Property Binding" href="qtquick2-propertybinding.xml"/> - </topicref> - <topicref navtitle="QML Module QtQuick.Particles 2" href="qtquick-particles-2.xml"> - <topicref navtitle="Age" href="qml-qtquick-particles2-age.xml"/> - </topicref> - </map> - \endcode - -*/ - diff --git a/src/tools/qdoc/doc/qdoc-manual-cmdindex.qdoc b/src/tools/qdoc/doc/qdoc-manual-cmdindex.qdoc deleted file mode 100644 index d3f188c265..0000000000 --- a/src/tools/qdoc/doc/qdoc-manual-cmdindex.qdoc +++ /dev/null @@ -1,156 +0,0 @@ -/**************************************************************************** -** -** Copyright (C) 2015 The Qt Company Ltd. -** Contact: http://www.qt.io/licensing/ -** -** This file is part of the documentation of the Qt Toolkit. -** -** $QT_BEGIN_LICENSE:FDL$ -** Commercial License Usage -** Licensees holding valid commercial Qt licenses may use this file in -** accordance with the commercial license agreement provided with the -** Software or, alternatively, in accordance with the terms contained in -** a written agreement between you and The Qt Company. For licensing terms -** and conditions see http://www.qt.io/terms-conditions. For further -** information use the contact form at http://www.qt.io/contact-us. -** -** GNU Free Documentation License Usage -** Alternatively, this file may be used under the terms of the GNU Free -** Documentation License version 1.3 as published by the Free Software -** Foundation and appearing in the file included in the packaging of -** this file. Please review the following information to ensure -** the GNU Free Documentation License version 1.3 requirements -** will be met: http://www.gnu.org/copyleft/fdl.html. -** $QT_END_LICENSE$ -** -****************************************************************************/ - -/*! - \page 27-qdoc-commands-alphabetical.html - \previouspage Introduction to QDoc - \contentspage QDoc Manual - \nextpage Topic Commands - - \title Command Index - - This is a complete, alphabetized list of the QDoc commands. - - \list - - \li \l {a-command} {\\a} - \li \l {abstract-command} {\\abstract} - \li \l {annotatedlist-command} {\\annotatedlist} - \li \l {b-command} {\\b} - \li \l {b-command} {\\bold} \span {class="newStuff"} {(deprecated, use \\b)} - \li \l {brief-command} {\\brief} - \li \l {c-command} {\\c} - \li \l {caption-command} {\\caption} - \li \l {chapter-command} {\\chapter} - \li \l {class-command} {\\class} - \li \l {code-command} {\\code} - \li \l {codeline-command} {\\codeline}, - \li \l {compat-command} {\\compat} - \li \l {contentspage-command} {\\contentspage} - \li \l {default-command} {\\default} - \li \l {div-command} {\\div} - \li \l {dots-command} {\\dots} - \li \l {e-command} {\\e} - \li \l {else-command} {\\else} - \li \l {endif-command} {\\endif} - \li \l {enum-command} {\\enum} - \li \l {example-command} {\\example} - \li \l {externalpage-command} {\\externalpage} - \li \l {fn-command} {\\fn} - \li \l {footnote-command} {\\footnote} - \li \l {generatelist-command} {\\generatelist} - \li \l {group-command} {\\group} - \li \l {header-command} {\\header} - \li \l {headerfile-command} {\\headerfile} - \li \l {e-command} {\\i} \span {class="newStuff"} {(deprecated, use \\e)} - \li \l {if-command} {\\if} - \li \l {image-command} {\\image} - \li \l {include-command} {\\include} - \li \l {indexpage-command} {\\indexpage} - \li \l {ingroup-command} {\\ingroup} - \li \l {inherits-command}{\\inherits} - \li \l {inlineimage-command} {\\inlineimage} - \li \l {inmodule-command} {\\inmodule} - \li \l {inqmlmodule-command} {\\inqmlmodule} - \li \l {instantiates-command} {\\instantiates} - \li \l {internal-command} {\\internal} - \li \l {keyword-command} {\\keyword} - \li \l {l-command} {\\l} - \li \l {legalese-command} {\\legalese} - \li \l {li-command} {\\li} - \li \l {list-command} {\\list} - \li \l {macro-command} {\\macro} - \li \l {meta-command} {\\meta} - \li \l {module-command} {\\module} - \li \l {namespace-command} {\\namespace} - \li \l {nextpage-command} {\\nextpage} - \li \l {newcode-command} {\\newcode} - \li \l {noautolist-command} {\\noautolist} - \li \l {nonreentrant-command} {\\nonreentrant} - \li \l {note-command} {\\note} - \li \l {li-command} {\\o} \span {class="newStuff"} {(deprecated, use \\li)} - - \li \l {obsolete-command} {\\obsolete} - \li \l {oldcode-command} {\\oldcode} - \li \l {omit-command} {\\omit} - \li \l {omitvalue-command} {\\omitvalue} - \li \l {overload-command} {\\overload} - \li \l {page-command} {\\page} - \li \l {part-command} {\\part} - \li \l {preliminary-command} {\\preliminary} - \li \l {previouspage-command} {\\previouspage} - \li \l {printline-command} {\\printline} - \li \l {printto-command} {\\printto} - \li \l {printuntil-command} {\\printuntil} - \li \l {property-command} {\\property} - \li \l {qmlabstract-command} {\\qmlabstract} - \li \l {qmlattachedproperty-command} {\\qmlattachedproperty} - \li \l {qmlattachedsignal-command} {\\qmlattachedsignal} - \li \l {qmlbasictype-command} {\\qmlbasictype} - \li \l {qmlclass-command} {\\qmlclass} \span {class="newStuff"} {(deprecated, use \\qmltype)} - \li \l {qmltype-command} {\\qmltype} - \li \l {qmlmethod-command} {\\qmlmethod} - \li \l {qmlproperty-command} {\\qmlproperty} - \li \l {qmlsignal-command} {\\qmlsignal} - \li \l {qmlmodule-command} {\\qmlmodule} - \li \l {quotation-command} {\\quotation} - \li \l {quotefile-command} {\\quotefile} - \li \l {quotefromfile-command} {\\quotefromfile} - \li \l {raw-command} {\\raw} - \li \l {reentrant-command} {\\reentrant} - \li \l {reimp-command} {\\reimp} - \li \l {relates-command} {\\relates} - \li \l {row-command} {\\row} - \li \l {sa-command} {\\sa} - \li \l {sectionOne-command} {\\section1} - \li \l {sectionTwo-command} {\\section2} - \li \l {sectionThree-command} {\\section3} - \li \l {sectionFour-command} {\\section4} - \li \l {since-command} {\\since} - \li \l {skipline-command} {\\skipline} - \li \l {skipto-command} {\\skipto} - \li \l {skipuntil-command} {\\skipuntil} - \li \l {snippet-command} {\\snippet}, - \li \l {span-command} {\\span} - \li \l {startpage-command} {\\startpage} - \li \l {sub-command} {\\sub} - \li \l {subtitle-command} {\\subtitle} - \li \l {sup-command} {\\sup} - \li \l {table-command} {\\table} - \li \l {tableofcontents-command} {\\tableofcontents} - \li \l {target-command} {\\target} - \li \l {threadsafe-command} {\\threadsafe} - \li \l {title-command} {\\title} - \li \l {tt-command} {\\tt} - \li \l {typedef-command} {\\typedef} - \li \l {uicontrol-command} {\\uicontrol} - \li \l {underline-command} {\\underline} - \li \l {variable-command} {\\variable} - \li \l {value-command} {\\value} - \li \l {warning-command} {\\warning} - \endlist -*/ diff --git a/src/tools/qdoc/doc/qdoc-manual-contextcmds.qdoc b/src/tools/qdoc/doc/qdoc-manual-contextcmds.qdoc deleted file mode 100644 index d707c77cfb..0000000000 --- a/src/tools/qdoc/doc/qdoc-manual-contextcmds.qdoc +++ /dev/null @@ -1,1058 +0,0 @@ -/**************************************************************************** -** -** Copyright (C) 2015 The Qt Company Ltd. -** Contact: http://www.qt.io/licensing/ -** -** This file is part of the documentation of the Qt Toolkit. -** -** $QT_BEGIN_LICENSE:FDL$ -** Commercial License Usage -** Licensees holding valid commercial Qt licenses may use this file in -** accordance with the commercial license agreement provided with the -** Software or, alternatively, in accordance with the terms contained in -** a written agreement between you and The Qt Company. For licensing terms -** and conditions see http://www.qt.io/terms-conditions. For further -** information use the contact form at http://www.qt.io/contact-us. -** -** GNU Free Documentation License Usage -** Alternatively, this file may be used under the terms of the GNU Free -** Documentation License version 1.3 as published by the Free Software -** Foundation and appearing in the file included in the packaging of -** this file. Please review the following information to ensure -** the GNU Free Documentation License version 1.3 requirements -** will be met: http://www.gnu.org/copyleft/fdl.html. -** $QT_END_LICENSE$ -** -****************************************************************************/ - -/*! - \page 14-qdoc-commands-contextcommands.html - \previouspage Topic Commands - \contentspage QDoc Manual - \nextpage Document Navigation - - \title Context Commands - - The context commands provide information about the element being - documented that QDoc can't deduce on its own. For example: - \list - \li Is this class thread-safe? - \li Is this function reentrant? - \li Of which module is this class a member ? - \endlist - - Context commands can appear anywhere in a QDoc comment, - but they are normally placed near the top of the comment, just - below the \l {Topic Commands} {topic} command. - - \list - \li \l {abstract-command} {\\abstract} - \li \l {compat-command}{\\compat}, - \li \l {contentspage-command}{\\contentspage}, - \li \l {indexpage-command}{\\indexpage}, - \li \l {ingroup-command}{\\ingroup}, - \li \l {inherits-command}{\\inherits}, - \li \l {inmodule-command}{\\inmodule}, - \li \l {internal-command}{\\internal}, - \li \l {nextpage-command}{\\nextpage}, - \li \l {nonreentrant-command}{\\nonreentrant}, - \li \l {obsolete-command}{\\obsolete}, - \li \l {overload-command}{\\overload}, - \li \l {preliminary-command}{\\preliminary}, - \li \l {previouspage-command}{\\previouspage}, - \li \l {qmlabstract-command} {\\qmlabstract} - \li \l {reentrant-command}{\\reentrant}, - \li \l {reimp-command}{\\reimp}, - \li \l {relates-command}{\\relates}, - \li \l {since-command}{\\since}, - \li \l {startpage-command}{\\startpage}, - \li \l {subtitle-command}{\\subtitle} - \li \l {threadsafe-command}{\\threadsafe}, - \li \l {title-command}{\\title} - \endlist - -*/ - -/*! - \page 15-qdoc-commands-navigation.html - \previouspage Context Commands - \contentspage QDoc Manual - \nextpage Status - - \title Document Navigation - - The navigation commands are for linking the pages of a document in - a meaningful sequence. Below is a sequence of QDoc comments that - shows a typical use of the navigation commands. - - \section1 Example - \quotefile files/basicqt.qdoc.sample - - QDoc renders the "Getting Started" page in \c{creatingdialogs.html}: - - \quotation - \raw HTML - <table border="0" cellpadding="0" cellspacing="5" width="100%"> - - <tr> - <p> - [Previous: <a href="15-qdoc-commands-navigation.html#deadlink"> - Basic Qt</a>] - [<a href="15-qdoc-commands-navigation.html#deadlink">Contents</a>] - [Next: <a href="15-qdoc-commands-navigation.html#deadlink"> - Creating Dialogs</a>] - </p> - - <h1 align="center">Getting Started<br /></h1> - - <p> - This chapter shows how to combine basic C++ with the - functionality provided by Qt to create a few small graphical - interface (GUI) applications. - </p> - - <p> - [Previous: <a href="15-qdoc-commands-navigation.html#deadlink"> - Basic Qt</a>] - [<a href="15-qdoc-commands-navigation.html#deadlink">Contents</a>] - [Next: <a href="15-qdoc-commands-navigation.html#deadlink"> - Creating Dialogs</a>] - </p> - - </table> - \endraw - \endquotation - - The \l {indexpage-command} {\\indexpage} and \l - {startpage-command} {\\startpage} commands create links to the - page's index page and start page. These links can be used by - browsers and search engines. - - The index page is typically an alphabetical list of the document's - titles and topics, while the start page is the page considered by - the author to be the starting point of a multipage document. - - The links are included in the generated HTML source code, but have - no visual effect on the documentation: - - \code - <head> - ... - <link rel="index" href="index.html" /> - <link rel="start" href="basicqt.html" /> - ... - </head> - \endcode - - \section1 Commands - - \target previouspage-command - \section2 \\previouspage - - The \\previouspage command links the current page to the previous - page in a sequence.a The command has two arguments, each enclosed - by curly braces: the first is the link target (the title of - the previous page), the second is the link text. If the page's - title is equivalent to the link text, the second argument can be - omitted. - - The command must stand alone on its own line. - - \target nextpage-command - \section2 \\nextpage - - The \\nextpage command links the current page to the next page in - a sequence. The command follows the same syntax and argument - convention as the \l {previouspage-command} {\\previouspage} - command. - - \target startpage-command - \section2 \\startpage - - The \\startpage command specifies the first page of a sequence of - pages. The command must stand alone on its own line, and its - unique argument is the title of the first document. - - QDoc will generate a link to the start page and include it in the - generated HTML file, but this has no visual effect on the - documentation. The generated link type tells browsers and search - engines which document is considered by the author to be the - starting point of the collection. - - \target contentspage-command - \section2 \\contentspage - - The \\contentspage command links the current page to a table of - contents page. The command follows the same syntax and argument - convention as the \l {previouspage-command} {\\previouspage} - command. - - \target indexpage-command - \section2 \\indexpage - - The \\indexpage command specifies an index page for the current - document. The command must stand alone on its own line, and its - unique argument is the title of the index document. - - QDoc will generate a link to the index page and include it in the - generated HTML file, but this has no visual effect on the - documentation. The generated link type tells browsers and search - engines which document is considered by the author to be the - index page of the collection. -*/ - -/*! - \page 16-qdoc-commands-status.html - \previouspage Document Navigation - \contentspage QDoc Manual - \nextpage Thread Support - - \title Status - - These commands are for indicating that a documented element has - some special status. The element could be marked as about to be - made obsolete, or that it is provided for compatibility with an - earlier version, or is simply not to be included in the public - interface. The \l {since-command}{\\since} command is for - specifying the version number in which a function or class first - appeared. The \l {qmlabstract-command} {\\qmlabstract} command is - for marking a QML type as an abstract base class. - - \target abstract-command - \target qmlabstract-command - \section1 \\abstract and \\qmlabstract - - \\abstract is a synonym for the \\qmlabstract command. Add this - command to the \l {qmltype-command} {\\qmltype} comment for a QML - type when that type is meant to be used \e {only} as an abstract - base type. When a QML type is abstract, it means that the QML type - that can't be instantiated. Instead, the properties in its public - API are included in the public properties list on the reference - page for each QML type that inherits the abstract QML type. The - properties are documented as if they are properties of the - inheriting QML type. - - Normally, when a QML type is marked with \e{\\qmlabstract}, it is - also marked with \e{\\internal} so that its reference page is not - generated. It the abstract QML type is not marked internal, it - will have a reference page in the documentation. - - \target compat-command - \section1 \\compat - - The \\compat command is for indicating that a class or function is - part of the support library provided to keep old source code - working. - - The command must stand on its own line. - - Usually an equivalent function or class is provided as an - alternative. - - If the command is used in the documentation of a class, the - command expands to a warning that the referenced class is part of - the support library. The warning is located at the top of the - documentation page. - - \code - \beginqdoc - \class MyQt3SupportClass - \compat - \endqdoc - \endcode - - QDoc renders this at the top of the MyQt3SupportClass class - reference page. - - \quotation - \b {This class is part of the Qt 3 support - library.} It is provided to keep old source code - working. We strongly advise against using it in new - code. See the \l - {http://doc.qt.io/qt-4.8/porting4.html} {Porting - Guide} for more information. - \endquotation - - If the command is used when documenting a function, QDoc will - create and link to a separate page documenting Qt 3 support - members when generating the reference documentation for the - associated class. - - \code - \beginqdoc - \fn MyClass::MyQt3SupportMemberFunction - \compat - - Use MyNewFunction() instead. - \endqdoc - \endcode - - QDoc renders this in \c{myclass-qt3.html} as: - - \quotation - \raw HTML - <h1>Qt 3 Support Members for MyClass</h1> - \endraw - - \b {The following class members are part of the Qt 3 - support layer.} They are provided to help you port old code to - Qt 4. We advise against using them in new code. - - ... - - \list - \li void MyQt3SupportMemberFunction() - \li ... - \endlist - - \raw HTML - <hr /> - <h2>Member Function Documentation</h2> - <h3>void MyQt3SupportMemberFunction ()</h3> - <p>Use MyNewFunction() instead.</p> - \endraw - ... - \endquotation - - \target default-command - \section1 \\default - - The \\default command is for marking a QML property as the - \l {default-properties} - {default property}. The word \span {class="newStuff"} {default} is shown in red in - the documentation of the property. - - \code - / *! - \qmlproperty list<Change> State::changes - This property holds the changes to apply for this state. - \default - - By default these changes are applied against the default state. If the state - extends another state, then the changes are applied against the state being - extended. - * / - \endcode - - See how QDoc renders this property on the reference page for the - \l {State::changes}{State} type. - - \target obsolete-command - \section1 \\obsolete - - The \\obsolete command is for indicating that a function is being - deprecated, and it should no longer be used in new code. There is - no guarantee for how long it will remain in the library. - - The command must stand on its own line. - - When generating the reference documentation for a class, QDoc will - create and link to a separate page documenting its obsolete - functions. Usually an equivalent function is provided as an - alternative. - - \code - / *! - \fn MyClass::MyObsoleteFunction - \obsolete - - Use MyNewFunction() instead. - * / - \endcode - - QDoc renders this in \c{myclass-obsolete.html} as: - - \quotation - \raw HTML - <h1>Obsolete Members for MyClass</h1> - \endraw - - \b {The following class members are obsolete.} They are - provided to keep old source code working. We strongly advise - against using them in new code. - - ... - - \list - \li void MyObsoleteFunction() \c (obsolete) - \li ... - \endlist - - \raw HTML - <hr /> - <h2>Member Function Documentation</h2> - <h3>void MyObsoleteFunction ()</h3> - <p>Use MyNewFunction() instead.</p> - \endraw - ... - \endquotation - - \target internal-command - \section1 \\internal - - The \\internal command indicates that the referenced - function is not part of the public interface. - - The command must stand on its own line. - - QDoc ignores the documentation as well as the documented item, - when generating the associated class reference documentation. - - \code - / *! - \internal - - Tries to find the decimal separator. If it can't find - it and the thousand delimiter is != '.' it will try to - find a '.'; - * / - int QDoubleSpinBoxPrivate::findDelimiter - (const QString &str, int index) const - { - int dotindex = str.indexOf(delimiter, index); - if (dotindex == -1 && thousand != dot && delimiter != dot) - dotindex = str.indexOf(dot, index); - return dotindex; - } - \endcode - - This function will not be included in the documentation. - - \target preliminary-command - \section1 \\preliminary - - The \\preliminary command is for indicating that a referenced - function is still under development. - - The command must stand on its own line. - - The \\preliminary command expands to a notification in the - function documentation, and marks the function as preliminary when - it appears in lists. - - \code - / *! - \preliminary - - Returns information about the joining type attributes of the - character (needed for certain languages such as Arabic or - Syriac). - - * / - QChar::JoiningType QChar::joiningType() const - { - return QChar::joiningType(ucs); - } - \endcode - - QDoc renders this as: - - \quotation - \raw HTML - <h3> - <a href="http://doc.qt.io/qt-5/qchar.html#JoiningType-enum">JoiningType</a> - QChar::joiningType() const</h3> - \endraw - - \b {This function is under development and - subject to change.} - - Returns information about the joining type attributes of the - character (needed for certain languages such as Arabic or - Syriac). - \endquotation - - And the function's entry in QChar's list of public functions will be - rendered as: - - \quotation - \list - \li ... - \li JoiningType \l {QChar::joiningType()} {joiningType}() const \c (preliminary) - \li ... - \endlist - \endquotation - - \target since-command - \section1 \\since - - The \\since command tells in which minor release - the associated functionality was added. - - \code - / *! - \since 4.1 - - Returns an icon for \a standardIcon. - - ... - - \sa standardPixmap() - * / - QIcon QStyle::standardIcon(StandardPixmap standardIcon, const QStyleOption *option, const QWidget *widget) const - { - } - \endcode - - QDoc renders this as: - - \quotation - \raw HTML - <h3>QIcon QStyle::standardIcon(StandardPixmap standardIcon, const QStyleOption *option, const QWidget *widget) const</h3> - \endraw - - This function was introduced in Qt version 4.1 - - Returns an icon for \a standardIcon. - - ... - - See also \l {QStyle::standardPixmap()} {standardPixmap()}. - \endquotation - - QDoc generates the "Qt" reference from the \l - {25-qdoc-configuration-derivedprojects.html#project} {\c project} - configuration variable. For that reason this reference will change - according to the current documentation project. - - See also \l {project} - {\c project}. -*/ - - -/*! - \page 17-qdoc-commands-thread.html - \previouspage Status - \contentspage QDoc Manual - \nextpage Relating Things - - \title Thread Support - - The thread support commands are for specifying the level of - support for multithreaded programming in a class or function. - There are three levels of support: \c threadsafe, \c reentrant and - \c nonreentrant. - - The default is \c nonreentrant which means that the associated - class or function cannot be called by multiple threads. \c - Reentrant and \c threadsafe are levels primarily used for classes. - - \c Reentrant means that all the functions in the referenced class - can be called simultaneously by multiple threads, provided that - each invocation of the functions reference unique data. While \c - threadsafe means that all the functions in the referenced class - can be called simultaneously by multiple threads even when each - invocation references shared data. - - When a class is marked \l {reentrant-command} {\\reentrant} or \l - {threadsafe-command} {\\threadsafe}, functions in that class can - be marked \c nonreentrant using the \l {nonreentrant-command} - {\\nonreentrant} command. - - \section1 Example - - \target reentrant-example - \code - \beginqdoc - \class QLocale - \brief The QLocale class converts between numbers and their - string representations in various languages. - - \reentrant - \ingroup i18n - \ingroup text - - QLocale is initialized with a language/country pair in its - constructor and offers number-to-string and string-to-number - conversion functions similar to those in QString. - - ... - - \nonreentrant - - Sets the global default locale to \a locale. These values are - used when a QLocale object is constructed with no - arguments. If this function is not called, the system's locale - is used. - - \warning In a multithreaded application, the default locale - should be set at application startup, before any non-GUI - threads are created. - - \sa system(), c() - \endqdoc - void QLocale::setDefault(const QLocale &locale) - { - default_d = locale.d; - } - \endcode - - QDoc renders this as: - - \quotation - \raw HTML - <h1><center>QLocale Class Reference</center></h1> - \endraw - - The QLocale class converts between numbers and their string - representations in various languages. More... - - \code - #include <QLocale> - \endcode - - \b {Note:} All the functions in this class are \l - {17-qdoc-commands-thread.html#reentrant} {reentrant}, except \l - {QLocale::setDefault()} {setDefault()}. - - ... - - \raw HTML - <hr /> - <h2>Member Type Documentation</h2> - \endraw - - ... - - \raw HTML - <h3>void QLocale::setDefault ( const QLocale & locale ) </h3> - \endraw - - Sets the global default locale to locale. These values are - used when a QLocale object is constructed with no - arguments. If this function is not called, the system's locale - is used. - - \warning In a multithreaded application, the default locale - should be set at application startup, before any non-GUI - threads are created. - - \warning This function is not reentrant. - - See also \l {QLocale::system()} {system()} and \l - {QLocale::c()} {c()}. - - ... - \endquotation - - As shown above, QDoc generates a notification when a class is - declared reentrant, and lists the exceptions (the declared - nonreentrant functions). A link to the general documentation on \l - {17-qdoc-commands-thread.html#reentrant} {reentrancy and thread-safety} is - included. In addition a warning, "\b Warning: This function is - not reentrant.", is generated in the nonreentrant functions' - documentation. - - QDoc will generate the same notification and warnings when a class - is declared threadsafe. - - For more information see the general documentation on \l - {17-qdoc-commands-thread.html#reentrant} {reentrancy and thread-safety}. - - \section1 Commands - - \target threadsafe-command - \section2 \\threadsafe - - The \\threadsafe command includes a line in the documentation to - indicate that the associated class or function is \e threadsafe - and can be called simultaneously by multiple threads, even when - separate invocations reference shared data. - - The command must stand on its own line. - - The documentation generated from this command will be similar to - the what is generated for the \l {reentrant-command} {\\reentrant} - command. See the example above in the \l {reentrant-example} - {introduction}. - - See also \l{reentrant-command} {\\reentrant} and - \l{nonreentrant-command} {\\nonreentrant}. - - \target reentrant-command - \section2 \\reentrant - - The \\reentrant command indicates that the associated class or - function can be called simultaneously by multiple threads, - provided that each invocation references its own data. See the \l - {reentrant-example} {example} above. - - The command must stand on its own line. - - See also \l{nonreentrant-command} {\\nonreentrant} and - \l{threadsafe-command} {\\threadsafe}. - - \target nonreentrant-command - \section2 \\nonreentrant - - The \\nonreentrant command indicates that the associated class or - function cannot be called by multiple threads. Nonreentrant is the - default case. - - The command must stand on its own line. - - When a class is marked \l {reentrant-command} {\\reentrant} or \l - {threadsafe-command} {\\threadsafe}, functions in that class can - be marked \c nonreentrant using this command in the \l{fn-command} - {\\fn} comment of the functions to be excluded. - - See also \l{reentrant-command} {\\reentrant} and - \l{threadsafe-command} {\\threadsafe}. -*/ - -/*! - \page 18-qdoc-commands-relating.html - \previouspage Thread Support - \contentspage QDoc Manual - \nextpage Grouping Things - - \title Relating Things - - The relating commands are for specifying how one documented - element relates to another documented element. Some examples: - \list - \li This function is an overload of another function. - \li This function is a reimplementation of another function. - \li This typedef is \e related to some class or header file. - \endlist - - There is also a command for documenting that a QML type inherits - some other QML type. - - \section1 Commands - - \target inherits-command - \section2 \\inherits - - The \\inherits command is for documenting that one QML type - inherits some other QML type. It must be included in the - inheriting element's \l{qmltype-command}{\\qmltype} comment. - The argument is the name of the inherited QML type. - - \code - / *! - \qmltype PauseAnimation - \instantiates QDeclarativePauseAnimation - \ingroup qml-animation-transition - \since 4.7 - \inherits Animation - \brief The PauseAnimation element provides a pause for an animation. - - When used in a SequentialAnimation, PauseAnimation is a step - when nothing happens, for a specified duration. - - A 500ms animation sequence, with a 100ms pause between two animations: - - SequentialAnimation { - NumberAnimation { ... duration: 200 } - PauseAnimation { duration: 100 } - NumberAnimation { ... duration: 200 } - } - - \sa {QML Animation and Transitions}, {declarative/animation/basics}{Animation basics example} - * / - \endcode - - QDoc includes this line on the reference page for the - \l{http://qt-project.org/doc/qt-4.7/qml-pauseanimation.html} {PauseAnimation} - element: - - \quotation - Inherits \l{http://qt-project.org/doc/qt-4.7/qml-animation.html} {Animation} - \endquotation - - \target overload-command - \section2 \\overload - - The \\overload command is for indicating that a function is a - secondary overload of its name. - - The command must stand on its own line. - - For a function name that is overloaded (except constructors), QDoc - expects one primary version of the function, and all the others - marked with the \b {\\overload command}. The primary version - should be fully documented. Each overload can have whatever extra - documentation you want to add for just that overloaded version. - - From Qt 4.5, you can include the function name plus '()' as a - parameter to the \b{\\overload} command, which will include a - standard \e{This function overloads...} line of text with a link - to the documentation for the primary version of the function. - - \code - / *! - \overload addAction() - - This convenience function creates a new action with an - \a icon and some \a text. The function adds the newly - created action to the menu's list of actions, and - returns it. - - \sa QWidget::addAction() - * / - QAction *QMenu::addAction(const QIcon &icon, const QString &text) - { - QAction *ret = new QAction(icon, text, this); - addAction(ret); - return ret; - } - \endcode - - QDoc renders this as: - - \quotation - \raw HTML - <h3><a href="http://doc.qt.io/qt-5/qaction.html">QAction</a> - * QMenu::addAction ( const QIcon & <i>icon</i>, - const QString & <i>text</i> ) - </h3> - \endraw - - This function overloads \l {QMenu::addAction()} {addAction()} - - This convenience function creates a new action with an - \e icon and some \e text. The function adds the newly - created action to the menu's list of actions, and - returns it. - - See also - \l {QWidget::addAction()} {QWidget::addAction}(). - \endquotation - - If you don't include the function name with the \b{\\overload} - command, then instead of the "This function overloads..." line - with the link to the documentation for the primary version, you - get the old standard line: - - \quotation - This is an overloaded member function, provided for - convenience. - \endquotation. - - \target reimp-command - \section2 \\reimp - - The \\reimp command is for indicating that a function is a - reimplementation of a virtual function. - - The command must stand on its own line. - - QDoc will omit the reimplemented function from the class - reference. - - \code - / *! - \reimp - * / - void QToolButton::nextCheckState() - { - Q_D(QToolButton); - if (!d->defaultAction) - QAbstractButton::nextCheckState(); - else - d->defaultAction->trigger(); - } - \endcode - - This function will not be included in the documentation. Instead, - a link to the base function QAbstractButton::nextCheckState() will - appear in the documentation. - - \target relates-command - \section2 \\relates - - The \\relates command is for including the documentation of a - global element to some class or header file. The argument is a - class name or header file. - - \code - / *! - \relates QChar - - Reads a char from the stream \a in into char \a chr. - - \sa {Format of the QDataStream operators} - * / - QDataStream &operator>>(QDataStream &in, QChar &chr) - { - quint16 u; - in >> u; - chr.unicode() = ushort(u); - return in; - } - \endcode - - The documentation for this function will be included on the reference page - for class QChar. -*/ - -/*! - \page 19-qdoc-commands-grouping.html - \previouspage Relating Things - \contentspage QDoc Manual - \nextpage Naming Things - - \title Grouping Things - - The grouping commands relate classes to defined groups and - modules. The groups are used when generating lists of related - classes in the documentation, while the modules are elements of - Qt's structure. - - \section1 Commands - - \target ingroup-command - \section2 \\ingroup - - The \\ingroup command indicates that the given - overview or documented class belongs to a certain group of - related docmentation. - - A class or overview may belong to many groups. - - The \\ingroup command's argument is a group name, but note - that the command considers the rest of the line as part of - its argument. Make sure that the group name is followed by - a linebreak. - - \code - / *! - \class QDir - \brief The QDir class provides access to directory - structures and their contents. - - \ingroup io - ... - * / - \endcode - - This will include the QDir class in the \c io group, which means, - for example, that QDir will appear on the list created by calling - the \l {group-command} {\\group} command with the \c io argument. - - To list overviews that are related to a certain group, you must - generate the list explicitly using the \l {generatelist-command} - {\\generatelist} command with the \c related argument. - - See also \l {group-command} {\\group}. - - \target inmodule-command - \section2 \\inmodule - - The \\inmodule command relates a class to the module specified by - the command's argument. - - For the basic classes in Qt, a class's module is determined by its - location, namely its directory. However, for extensions like - ActiveQt and Qt Designer, a class must be related to a module - explicitly. - - The command's argument is a module name, but note that the command - considers the rest of the line as part of its argument. Make sure - that the module name is followed by a linebreak. - - \code - /*! - \class QDesignerTaskMenuExtension - \inmodule QtDesigner - * / - \endcode - - This ensures that the QDesignerTaskMenuExtension class is included - in the Qt Designer module, which means, for example, that the - class will appear on the list created by calling the \l - {generatelist-command} {\\generatelist} command with the \c - {{classesbymodule QtDesigner}} argument. - - See also \l {module-command} {\\module} and \l - {generatelist-command} {\\generatelist}. -*/ - -/*! - \page 20-qdoc-commands-namingthings.html - \previouspage Grouping Things - \contentspage QDoc Manual - \nextpage Markup Commands - - \title Naming Things - - In general, a title command considers everything that follows it - until the first line break as its argument. If the title is so - long it must span multiple lines, end each line (except the last - one) with a backslash. - - \section1 Commands - - \target title-command - \section2 \\title - - The \\title command sets the title for a documentation page, or - allows you to override it. - - \code - / *! - \page signalandslots.html - - \title Signals & Slots - - Signals and slots are used for communication between - objects. The signals and slots mechanism is a central - feature of Qt, and probably the part that differs most - from the features provided by other frameworks. - - ... - * / - \endcode - - QDoc renders this as: - - \quotation - \raw HTML - <h1><center>Signal and Slots</center></h1> - \endraw - - Signals and slots are used for communication between - objects. The signals and slots mechanism is a central - feature of Qt and probably the part that differs most - from the features provided by other frameworks. - ... - \endquotation - See also \l {subtitle-command} {\\subtitle}. - - \target subtitle-command - \section2 \\subtitle - - The \\subtitle command sets a subtitle for a documentation page. - - \code - \beginqdoc - \page qtopiacore-overview.html - - \title Qtopia Core - \subtitle Qt for Embedded Linux - - Qt/Embedded, the embedded Linux port of Qt, is a - complete and self-contained C++ GUI and platform - development tool for Linux-based embedded development. - ... - \endqdoc - \endcode - - QDoc renders this as: - - \quotation - \raw HTML - <h1><center>Qtopia Core</center></h1> - <h2><center>Qt for Embedded Linux</center></h2> - \endraw - - Qt/Embedded, the embedded Linux port of Qt, is a - complete and self-contained C++ GUI and platform - development tool for Linux-based embedded development. - ... - \endquotation - - See also \l {title-command} {\\title}. - -*/ diff --git a/src/tools/qdoc/doc/qdoc-manual-intro.qdoc b/src/tools/qdoc/doc/qdoc-manual-intro.qdoc deleted file mode 100644 index 84f9416843..0000000000 --- a/src/tools/qdoc/doc/qdoc-manual-intro.qdoc +++ /dev/null @@ -1,325 +0,0 @@ -/**************************************************************************** -** -** Copyright (C) 2015 The Qt Company Ltd. -** Contact: http://www.qt.io/licensing/ -** -** This file is part of the documentation of the Qt Toolkit. -** -** $QT_BEGIN_LICENSE:FDL$ -** Commercial License Usage -** Licensees holding valid commercial Qt licenses may use this file in -** accordance with the commercial license agreement provided with the -** Software or, alternatively, in accordance with the terms contained in -** a written agreement between you and The Qt Company. For licensing terms -** and conditions see http://www.qt.io/terms-conditions. For further -** information use the contact form at http://www.qt.io/contact-us. -** -** GNU Free Documentation License Usage -** Alternatively, this file may be used under the terms of the GNU Free -** Documentation License version 1.3 as published by the Free Software -** Foundation and appearing in the file included in the packaging of -** this file. Please review the following information to ensure -** the GNU Free Documentation License version 1.3 requirements -** will be met: http://www.gnu.org/copyleft/fdl.html. -** $QT_END_LICENSE$ -** -****************************************************************************/ - -/*! - \page 01-qdoc-manual.html - \contentspage QDoc Manual - \previouspage QDoc Manual - \nextpage Command Index - - \title Introduction to QDoc - - QDoc is a tool used by Qt Developers to generate documentation for - software projects. It works by extracting \e {QDoc comments} from - project source files and then formatting these comments as HTML - pages or DITA XML documents. QDoc finds QDoc comments in \c - {.cpp} files and in \c {.qdoc} files. QDoc does not look for QDoc - comments in \c {.h} files. A QDoc comment always begins with an - exclamation mark (\b{!})). For example: - - \code - / *! - \class QObject - \brief The QObject class is the base class of all Qt objects. - - \ingroup objectmodel - - \reentrant - - QObject is the heart of the Qt \l{Object Model}. The - central feature in this model is a very powerful mechanism - for seamless object communication called \l{signals and - slots}. You can connect a signal to a slot with connect() - and destroy the connection with disconnect(). To avoid - never ending notification loops you can temporarily block - signals with blockSignals(). The protected functions - connectNotify() and disconnectNotify() make it possible to - track connections. - - QObjects organize themselves in \l {Object Trees & - Ownership} {object trees}. When you create a QObject with - another object as parent, the object will automatically - add itself to the parent's \c children() list. The parent - takes ownership of the object. It will automatically - delete its children in its destructor. You can look for an - object by name and optionally type using findChild() or - findChildren(). - - Every object has an objectName() and its class name can be - found via the corresponding metaObject() (see - QMetaObject::className()). You can determine whether the - object's class inherits another class in the QObject - inheritance hierarchy by using the \c inherits() function. - - .... - * / - \endcode - - From the QDoc comment above, QDoc generates the HTML \l {QObject} - {QObject class reference} page. - - This manual explains how to use the QDoc commands in QDoc comments - to embed good documentation in your source files. It also explains - how to make a \l {The QDoc Configuration File} {QDoc configuration - file}, which you will pass to QDoc on the command line. - - \section1 Running QDoc - - The name of the QDoc program is \c {qdoc}. To run qdoc from the - command line, give it the name of a configuration file: - - \quotation - \c {$ ../../bin/qdoc ./config.qdocconf} - \endquotation - - QDoc recognizes the \c {.qdocconf} suffix as a \l{The QDoc - Configuration File} {QDoc configuration file}. The configuration - file is where you tell QDoc where to find the project source - files, header files, and \c {.qdoc} files. It is also where you - tell QDoc what kind of output to generate (HTML, DITA XML,...), - and where to put the generated documentation. The configuration - file also contains other information for QDoc. - - See \l{The QDoc Configuration File} for instructions on how to - set up a QDoc configuration file. - - \section2 Running QDoc in Single Execution Mode - - Beginning with Qt 5.5, a new way to run QDoc is available that - reduces the time it takes to generate the Qt5 documentation by as - much as 90%. The new way to run QDoc is \e{single execution} mode. - Single execution mode is not currently available in the Qt5 build - system, which still uses the \e {standard} mode. Single execution - mode is only available when you run QDoc yourself, which you will - want to do often as you document your module and integrate your - documentation with the other Qt modules. - - To run QDoc in single execution mode, add \c {-single-exec} to the - command line and pass QDoc a master \c qdocconf file that is - simply a list of file paths for qdocconf files of all the Qt5 - modules. For example: - - \code - /Users/me/qt5/qtbase/bin/qdoc -outputdir /Users/me/qt5/qtbase/doc -installdir /Users/me/qt5/qtbase/doc /Users/me/qt5/master.qdocconf -single-exec - \endcode - - The qdocconf file, \c {master.qdocconf}, just lists the qdocconf files for all the Qt5 modules to be processed: - - \badcode - /Users/me/qt5/qtbase/src/corelib/doc/qtcore.qdocconf - /Users/me/qt5/qtbase/src/network/doc/qtnetwork.qdocconf - /Users/me/qt5/qtbase/src/sql/doc/qtsql.qdocconf - /Users/me/qt5/qtbase/src/xml/doc/qtxml.qdocconf - /Users/me/qt5/qtbase/src/testlib/doc/qttestlib.qdocconf - /Users/me/qt5/qtbase/src/concurrent/doc/qtconcurrent.qdocconf - /Users/me/qt5/qtbase/src/gui/doc/qtgui.qdocconf - /Users/me/qt5/qtbase/src/platformheaders/doc/qtplatformheaders.qdocconf - /Users/me/qt5/qtbase/src/widgets/doc/qtwidgets.qdocconf - /Users/me/qt5/qtbase/src/opengl/doc/qtopengl.qdocconf - /Users/me/qt5/qtbase/src/printsupport/doc/qtprintsupport.qdocconf - /Users/me/qt5/qtbase/src/tools/qdoc/doc/config/qdoc.qdocconf - /Users/me/qt5/qtbase/qmake/doc/qmake.qdocconf - /Users/me/qt5/qtsvg/src/svg/doc/qtsvg.qdocconf - /Users/me/qt5/qtxmlpatterns/src/xmlpatterns/doc/qtxmlpatterns.qdocconf - /Users/me/qt5/qtdeclarative/src/qml/doc/qtqml.qdocconf - /Users/me/qt5/qtdeclarative/src/quick/doc/qtquick.qdocconf - /Users/me/qt5/qtquickcontrols/src/controls/doc/qtquickcontrols.qdocconf - /Users/me/qt5/qtquickcontrols/src/layouts/doc/qtquicklayouts.qdocconf - /Users/me/qt5/qtquickcontrols/src/dialogs/doc/qtquickdialogs.qdocconf - /Users/me/qt5/qtmultimedia/src/multimedia/doc/qtmultimedia.qdocconf - /Users/me/qt5/qtmultimedia/src/multimediawidgets/doc/qtmultimediawidgets.qdocconf - /Users/me/qt5/qtactiveqt/src/activeqt/doc/activeqt.qdocconf - /Users/me/qt5/qtsensors/src/sensors/doc/qtsensors.qdocconf - /Users/me/qt5/qtwebkit/Source/qtwebkit.qdocconf - /Users/me/qt5/qttools/src/assistant/help/doc/qthelp.qdocconf - /Users/me/qt5/qttools/src/assistant/assistant/doc/qtassistant.qdocconf - /Users/me/qt5/qttools/src/designer/src/uitools/doc/qtuitools.qdocconf - /Users/me/qt5/qttools/src/designer/src/designer/doc/qtdesigner.qdocconf - /Users/me/qt5/qttools/src/linguist/linguist/doc/qtlinguist.qdocconf - /Users/me/qt5/qtwebkit-examples/doc/qtwebkitexamples.qdocconf - /Users/me/qt5/qtimageformats/src/imageformats/doc/qtimageformats.qdocconf - /Users/me/qt5/qtgraphicaleffects/src/effects/doc/qtgraphicaleffects.qdocconf - /Users/me/qt5/qtscript/src/script/doc/qtscript.qdocconf - /Users/me/qt5/qtscript/src/scripttools/doc/qtscripttools.qdocconf - /Users/me/qt5/qtserialport/src/serialport/doc/qtserialport.qdocconf - /Users/me/qt5/qtdoc/doc/config/qtdoc.qdocconf - \endcode - - \section3 Why Standard Mode Is Slow - - Currently, the Qt5 build system does not use QDoc's \e {single - execution} mode for generating the Qt5 documentation. It runs QDoc - in the \e {standard} mode. The standard mode was came about - because it was the easiest way to get convert the Qt4 QDoc to - handle the modularization of Qt in Qt5. In Qt4, QDoc ran once over - all the Qt4 sources to generate the HTML documentation for Qt. - While generating the Qt documentation, Qt4 QDoc also generated an - \e {index file} for Qt. That index file was meant to be used as - input to subsequent QDoc runs for generating HTML documentation - for other software libraries/products that were based on Qt. The - Qt index file allowed QDoc to link documentation written for those - other libraries/products to the Qt4 documentation. - - When Qt5 came along, Qt was divided into modules. Since then, - many new modules have been added to Qt. As of version 5.5, there - are over 40 separate modules in Qt5, each with its own - documentation that links to (depends on) the documentation of - other Qt modules. - - In \e {standard mode}, QDoc runs twice for each module. The first - QDoc run for a particular Qt module, parses all the module's - source files and then uses the information to generate the - module's index file. It is called the \e{prepare phase} because - it \e prepares the module's index file. The second QDoc run for - the module also parses all the module's source files and then - generates the module's documentation pages. This is called the \e - {generate phase} because it generates the module's documentation. - - The module's documentation will likely contain HTML links to the - documentation of one or more of the other Qt modules. For example, - most Qt5 modules contain links to documentation in QtCore. When a - Qt module contains links into the documentation of other Qt - module's, that module is said to depend on those other Qt modules. - Hence when QDoc runs the \e {generate phase} for that module, it - must also load the index files for those modules so it can create - those thinks. - - Hence, when the Qt build system generates the Qt documentation, it - first runs QDoc once for each module to perform the \e {prepare - phase} to generate all the index files. Then it runs QDoc once for - each module to perform the \e {generate phase}, where it uses the - dependent index files to generate the module's documentation, - including any cross-module links it finds. Each execution of - QDoc, both \e {prepare phase} and \e {generate phase}, parses - all the source files that are included in the module, and in the - \e {generate phase} also parses the index files for the dependent - modules. Nothing is retained or retainable between QDoc runs. - - \section3 Why Single Execution Mode Is Much Faster - - As the name implies, single execution mode uses a single QDoc - process to generate all the Qt5 documentation. The single QDoc - process still performs a \e{prepare phase} for each module and - then a \e{generate phase} for each module, but there are a few - differences. It begins by reading the master qdocconf file. Then - it reads each qdocconf file in the master list and performs the - \e{prepare phase} for each module. During the \e{prepare phase}, - all the source files for the module are parsed to build a syntax - tree for the module. The module's index file is then generated, - although QDoc will not re-read the index files in the \e{generate - phase}. The important difference here is that the module's syntax - tree is retained after the index file is generated, so that after - the \e{prepare phase} has been run for all the modules, QDoc still - has all the syntax trees it built. - - QDoc then processes each module again for the \e{generate phase}. - But now QDoc doesn't need to re-parse each module's source files, - because the module's syntax tree is still in memory. Nor does QDoc - need to re-read the index files for the dependent modules, again - because it still has the syntax trees for those modules in memry. - It remains only to traverse each module's syntax tree to generate - the documentation pages. - - Hence, QDoc parses each source file once and only once and doesn't - need to read index files. This is what makes single execution mode - much faster than the standard mode. It is anticipated that the Qt - build system will eventually run QDoc in single execution mode. - However, changes to the master qdocconf file might be required, so - the method described above for running QDoc in single execution - mode might have to change, watch this space for updates. - - \section1 How QDoc Works - - QDoc begins by reading the configuration file you specified on the - command line. It stores all the variables from the configuration - file for later use. One of the first variables it uses is \c - {outputformats}. This variable tells QDoc which output generators - it will run. The default value is \e {HTML}, so if you don't set - \c {outputformats} in your configuration file, QDoc will generate - HTML output. That's usually what you will want anyway, but you can - also specify \e {DITAXML} to get DITA XML output instead. - - Next, QDoc uses the values of the - \l {headerdirs-variable} - {headerdirs} variable and/or the \l - {22-qdoc-configuration-generalvariables.html#headers-variable} - {headers} variable to find and parse all the header files for your - project. QDoc does \e not scan header files for QDoc comments. It - parses the header files to build a master tree of all the items - that should be documented, in other words, the items that QDoc should find - QDoc comments for. - - After parsing all the header files and building the master tree of - items to be documented, QDoc uses the value of the \l - {22-qdoc-configuration-generalvariables.html#sourcedirs-variable} - {sourcedirs} variable and/or the value of the \l - {22-qdoc-configuration-generalvariables.html#sources-variable} - {sources} variable to find and parse all the \c {.cpp} and \c - {.qdoc} files for your project. These are the files QDoc scans for - \e {QDoc comments}. Remember that a QDoc comment begins with - an exclamation mark: \b {/*!} . - - For each QDoc comment it finds, it searches the master tree for - the item where the documentation belongs. Then it interprets the - qdoc commands in the comment and stores the interpreted commands - and the comment text in the tree node for the item. - - Finally, QDoc traverses the master tree. For each node, if the - node has stored documentation, QDoc calls the output generator - specified by the \c {outputformats} variable to format and write - the documentation in the directory specified in the configuration - file in the \l - {22-qdoc-configuration-generalvariables.html#outputdir-variable} - {outputdir} variable. - - \section1 Command Types - - QDoc interprets three types of commands: - - \list - \li \l {Topic Commands} - \li \l {Context Commands} - \li \l {Markup Commands} - \endlist - - Topic commands identify the element you are documenting, for example - a C++ class, function, type, or an extra page of text - that doesn't map to an underlying C++ element. - - Context commands tell QDoc how the element being documented - relates to other documented elements, for example, next and previous page - links, inclusion in page groups, or library modules. Context - commands can also provide information about the documented element - that QDoc can't get from the source files, for example, whether the - element is thread-safe, whether it is an overloaded or reimplemented function, - or whether it has been deprecated. - - Markup commands tell QDoc how text and image elements in the - document should be rendered, or about the document's outline - structure. -*/ - diff --git a/src/tools/qdoc/doc/qdoc-manual-markupcmds.qdoc b/src/tools/qdoc/doc/qdoc-manual-markupcmds.qdoc deleted file mode 100644 index 49cbfc0654..0000000000 --- a/src/tools/qdoc/doc/qdoc-manual-markupcmds.qdoc +++ /dev/null @@ -1,4081 +0,0 @@ -/**************************************************************************** -** -** Copyright (C) 2015 The Qt Company Ltd. -** Contact: http://www.qt.io/licensing/ -** -** This file is part of the documentation of the Qt Toolkit. -** -** $QT_BEGIN_LICENSE:FDL$ -** Commercial License Usage -** Licensees holding valid commercial Qt licenses may use this file in -** accordance with the commercial license agreement provided with the -** Software or, alternatively, in accordance with the terms contained in -** a written agreement between you and The Qt Company. For licensing terms -** and conditions see http://www.qt.io/terms-conditions. For further -** information use the contact form at http://www.qt.io/contact-us. -** -** GNU Free Documentation License Usage -** Alternatively, this file may be used under the terms of the GNU Free -** Documentation License version 1.3 as published by the Free Software -** Foundation and appearing in the file included in the packaging of -** this file. Please review the following information to ensure -** the GNU Free Documentation License version 1.3 requirements -** will be met: http://www.gnu.org/copyleft/fdl.html. -** $QT_END_LICENSE$ -** -****************************************************************************/ - -/*! - \page 03-qdoc-commands-markup.html - \contentspage QDoc Manual - \previouspage Naming Things - \nextpage Text Markup - - \title Markup Commands - - The markup commands indicate the generated documentation's visual - appearance and logical structure. - - \list - \li \l {a-command} {\\a} - \li \l {annotatedlist-command} {\\annotatedlist} - \li \l {b-command} {\\b} \span {class="newStuff"} - \li \l {b-command} {\\bold} {(deprecated, use \\b)} - \li \l {brief-command} {\\brief} - \li \l {c-command} {\\c} - \li \l {caption-command} {\\caption} - \li \l {chapter-command} {\\chapter} - \li \l {code-command} {\\code} - \li \l {codeline-command} {\\codeline} - \li \l {div-command} {\\div} - \li \l {dots-command} {\\dots} - \li \l {e-command} {\\e} \span {class="newStuff"} - \li \l {else-command} {\\else} - \li \l {endif-command} {\\endif} - \li \l {footnote-command} {\\footnote} - \li \l {generatelist-command} {\\generatelist} - \li \l {header-command} {\\header} - \li \l {e-command} {\\i} \span {class="newStuff"} {(deprecated, use \\e)} - \li \l {if-command} {\\if} - \li \l {image-command} {\\image} - \li \l {include-command} {\\include} - \li \l {include-command} {\\input} - \li \l {inlineimage-command} {\\inlineimage} - \li \l {keyword-command} {\\keyword} - \li \l {l-command} {\\l} - \li \l {legalese-command} {\\legalese} - \li \l {li-command} {\\li} \span {class="newStuff"} - \li \l {list-command} {\\list} - \li \l {meta-command} {\\meta} - \li \l {noautolist-command} {\\noautolist} - \li \l {newcode-command} {\\newcode} - \li \l {li-command} {\\o} \span {class="newStuff"} {(deprecated, use \\li)} - \li \l {note-command} {\\note} - \li \l {oldcode-command} {\\oldcode} - \li \l {omit-command} {\\omit} - \li \l {part-command} {\\part} - \li \l {printline-command} {\\printline} - \li \l {printto-command} {\\printto} - \li \l {printuntil-command} {\\printuntil} - \li \l {quotation-command} {\\quotation} - \li \l {quotefile-command} {\\quotefile} - \li \l {quotefromfile-command} {\\quotefromfile} - \li \l {raw-command} {\\raw} - \li \l {row-command} {\\row} - \li \l {sa-command} {\\sa} - \li \l {sectionOne-command} {\\section1} - \li \l {sectionTwo-command} {\\section2} - \li \l {sectionThree-command} {\\section3} - \li \l {sectionFour-command} {\\section4} - \li \l {skipline-command} {\\skipline} - \li \l {skipto-command} {\\skipto} - \li \l {skipuntil-command} {\\skipuntil} - \li \l {snippet-command} {\\snippet} - \li \l {span-command} {\\span} - \li \l {sub-command} {\\sub} - \li \l {sup-command} {\\sup} - \li \l {table-command} {\\table} - \li \l {tableofcontents-command} {\\tableofcontents} - \li \l {target-command} {\\target} - \li \l {tt-command} {\\tt} - \li \l {uicontrol-command} {\\uicontrol} {(new 25/3/2012)} - \li \l {underline-command} {\\underline} - \li \l {raw-command} {\\unicode} - \li \l {warning-command} {\\warning} - \li \l {backslash-command} {\\\\} - \endlist -*/ - - -/*! - \page 04-qdoc-commands-textmarkup.html - \contentspage QDoc Manual - \previouspage Markup Commands - \nextpage Document Structure - - \title Text Markup - - The text formatting commands indicate how text is to be rendered. - - \target a-command - \section1 \\a (parameter marker) - - The \\a command tells QDoc the next word is a formal parameter name. - - A warning is emitted when a formal parameter is not documented or - is misspelled, so when you document a function you should mention - each formal parameter by name in the function description, - preceded by the \\a command. The parameter name is then rendered - in italics. - - \code - / *! - Constructs a line edit containing the text - \a contents. The \a parent parameter is sent - to the QWidget constructor. - * / - - QLineEdit::QLineEdit(const QString &contents, QWidget *parent) :QWidget(parent) - { - ... - } - - \endcode - - QDoc renders this as: - - \quotation - \b {QLineEdit::QLineEdit ( const QString & - contents, QWidget *parent )} - - Constructs a line edit containing the text \a contents. - The \a parent parameter is sent to the QWidget constructor. - \endquotation - - The formal parameter name may be enclosed between curly brackets, - but that isn't required. - - \target c-command - \section1 \\c (code font) - - The \\c command is used for rendering variable names, user-defined - class names, and C++ keywords (for example, \c int and \c for) in the code - font. - - The command renders its argument using a monospace font. For - example: - - \code - / *! - The \c AnalogClock class provides a clock widget with hour - and minute hands that is automatically updated every - few seconds. - * / - \endcode - - QDoc renders this as: - - \quotation - The \c AnalogClock class provides a clock widget with hour - and minute hands, which are automatically updated every - few seconds. - \endquotation - - If the text to be rendered in the code font contains spaces, enclose the - entire text in curly brackets. - - \code - \c {QLineEdit::QLineEdit(const QString &contents, QWidget *parent) :QWidget(parent)} - \endcode - - QDoc renders this as: - - \quotation - \c {QLineEdit::QLineEdit(const QString &contents, QWidget *parent) :QWidget(parent)} - \endquotation - - The \\c command accepts the special character \c \ within its - argument, which renders it as a normal character. So if you want - to use nested commands, you must use the \l {tt-command} {teletype - (\\tt)} command instead. - - See also \l {tt-command} {\\tt} and \l {code-command} {\\code}. - - \target div-command - \section1 \\div - - The \\div and \\enddiv commands delimit a large or small block of - text (which may include other QDoc commands) to which special - formatting attributes should be applied. - - An argument must be provided in curly braces, as in the qdoc - comment shown below. The argument is not interpreted but is used - as attribute(s) of the tag that is output by qdoc. - - For example, we might want to render an inline image so that it - floats to the right of the current block of text: - - \code - / *! - \div {class="float-right"} - \inlineimage qml-column.png - \enddiv - - * / - \endcode - - If qdoc is generating HTML, it will translate these commands to: - - \code - <div class="float-right"><p><img src="images/qml-column.png" /></p></div> - \endcode - - For HTML, the attribute value \e {float-right} then will refer to - a clause in the style.css file, which in this case could be: - - \code - div.float-right - { - float: right; margin-left: 2em - } - \endcode - - If qdoc is generating DITA XML, it will translate the commands to: - - \code - <sectiondiv outputclass="float-right"> - <p> - <fig> - <image href="images/qml-column.png" placement="inline"/> - </fig> - </p> - </sectiondiv> - \endcode - - Your DITA XML publishing program must then recognize the \e - {outputclass} attribute value. - - \note Note that the \b {\\div} command can be nested. - - Below you can find an example taken from the index.qdoc file used to - generate index.html for Qt 4.7: - - \code - \div {class="indexbox guide"} - \div {class="heading"} - Qt Developer Guide - \enddiv - \div {class="indexboxcont indexboxbar"} - \div {class="section indexIcon"} \emptyspan - \enddiv - \div {class="section"} - Qt is a cross-platform application and UI - framework. Using Qt, you can write web-enabled - applications once and deploy them across desktop, - mobile and embedded operating systems without - rewriting the source code. - \enddiv - \div {class="section sectionlist"} - \list - \li \l{Getting Started} - \li \l{Installation} {Installation} - \li \l{how-to-learn-qt.html} {How to learn Qt} - \li \l{tutorials.html} {Tutorials} - \li \l{Qt Examples} {Examples} - \li \l{qt4-7-intro.html} {What's new in Qt 4.7} - \endlist - \enddiv - \enddiv - \enddiv - \endcode - - When all the class attribute values are defined as they are in the - style.css file that is used for rendering the Qt documentation, - the above example is rendered as: - - \div {class="indexbox guide"} - \div {class="heading"} - Qt Developer Guide - \enddiv - \div {class="indexboxcont indexboxbar"} - \div {class="section indexIcon"} \emptyspan - \enddiv - \div {class="section"} - Qt is a cross-platform application and UI - framework. Using Qt, you can write web-enabled - applications once and deploy them across desktop, - mobile and embedded operating systems without - rewriting the source code. - \enddiv - \div {class="section sectionlist"} - \list - \li Getting Started - \li Installation - \li How to learn Qt - \li Tutorials - \li Examples - \li What's new in Qt 4.7 - \endlist - \enddiv - \enddiv - \enddiv - - When generating DITA XML, qdoc outputs the nested \e {div} commands as: - - \code - <sectiondiv outputclass="indexbox guide"> - <sectiondiv outputclass="heading"> - <p>Qt Developer Guide</p> - </sectiondiv> - <sectiondiv outputclass="indexboxcont indexboxbar"> - <sectiondiv outputclass="section indexIcon"/> - <sectiondiv outputclass="section"> - <p>Qt is a cross-platform application and UI - framework. Using Qt, you can write - web-enabled applications once and deploy - them across desktop, mobile and embedded - operating systems without rewriting the - source code. - </p> - </sectiondiv> - <sectiondiv outputclass="section sectionlist"> - <ul> - <li> - <xref href="gettingstarted.xml#id-606ee7a8-219b-47b7-8f94-91bc8c76e54c">Getting started</xref> - </li> - <li> - <xref href="installation.xml#id-075c20e2-aa1e-4f88-a316-a46517e50443">Installation</xref> - </li> - <li> - <xref href="how-to-learn-qt.xml#id-49f509b5-52f9-4cd9-9921-74217b9a5182">How to learn Qt</xref> - </li> - <li> - <xref href="tutorials.xml#id-a737f955-a904-455f-b4aa-0dc69ed5a64f">Tutorials</xref> - </li> - <li> - <xref href="all-examples.xml#id-98d95159-d65b-4706-b08f-13d80080448d">Examples</xref> - </li> - <li> - <xref href="qt4-7-intro.xml#id-519ae0e3-4242-4c2a-b2be-e05d1e95f177">What's new in Qt 4.7</xref> - </li> - </ul> - </sectiondiv> - </sectiondiv> - </sectiondiv> - \endcode - - Your DITA XML publishing program must recognize the values of the - \e {outputclass} attribute. - - See also \l {span-command} {\\span}. - - \target span-command - \section1 \\span - - The \\span command applies special formatting to a small block of text. - - Two arguments must be provided, each argument in curly braces, as - shown in the QDoc comment below. The first argument is not - interpreted, but specifies the formatting attribute(s) of the tag - output by QDoc. The second argument is the text to be rendered with - the special formatting attributes. - - For example, we might want to render the first word of each - element in a numeric list in blue. - - \code - / *! - Global variables with complex types: - \list 1 - \li \span {class="variableName"} {mutableComplex1} in globals.cpp at line 14 - \li \span {class="variableName"} {mutableComplex2} in globals.cpp at line 15 - \li \span {class="variableName"} {constComplex1} in globals.cpp at line 16 - \li \span {class="variableName"} {constComplex2} in globals.cpp at line 17 - \endlist - * / - \endcode - - Class \e {variableName} refers to a clause in your style.css. - - \code - .variableName - { - font-family: courier; - color: blue - } - \endcode - - Using the \e {variableName} clause shown above, the example is rendered as: - - Global variables with complex types: - \list 1 - \li \span {class="variableName"} {mutableComplex1} in globals.cpp at line 14 - \li \span {class="variableName"} {mutableComplex2} in globals.cpp at line 15 - \li \span {class="variableName"} {constComplex1} in globals.cpp at line 16 - \li \span {class="variableName"} {constComplex2} in globals.cpp at line 17 - \endlist - - \note The \b span command does not cause a new paragraph to be - started. - - See also \l {div-command} {\\div}. - - \target tt-command - \section1 \\tt (teletype font) - - The \\tt command renders its argument in a monospace font. This - command behaves just like the \l {c-command} {\\c} command, except - that \\tt allows you to nest QDoc commands within the argument - (e.g. \l {e-command} {\\e}, \l {b-command} {\\b} and \l - {underline-command} {\\underline}). - - \code - / *! - After having populated the main container with - child widgets, \c setupUi() scans the main container's list of - slots for names with the form - \tt{on_\e{objectName}_\e{signalName}().} - * / - \endcode - - QDoc renders this as: - - \quotation - After having populated the main container with - child widgets, \c setupUi() scans the main container's list of - slots for names with the form - \tt{on_\e{objectName}_\e{signalName}().} - \endquotation - - If the text to be rendered in the code font contains spaces, enclose the - entire text in curly brackets. - - \code - \tt {QLineEdit::QLineEdit(const QString &contents, QWidget *parent) :QWidget(parent)} - \endcode - - QDoc renders this as: - - \quotation - \tt {QLineEdit::QLineEdit(const QString &contents, QWidget *parent) :QWidget(parent)} - \endquotation - - See also \l {c-command} {\\c}. - - \target b-command - \section1 \\b - - The \\b command renders its argument in bold font. This command used - to be called \\bold. - - \code - / *! - This is regular text; \b {this text is - rendered using the \\b command}. - * / - \endcode - - QDoc renders this as: - - \quotation - This is regular text; \b {this text is rendered using - the \\b command}. - \endquotation - - \target e-command - \section1 \\e (emphasis, italics) \span {class="newStuff"} {(new 5/3/2012)} - - The \\e command renders its argument in a special font, normally italics. This - command used to be called \\i, which is now deprecated. Use \e for italics. - - If the argument contains spaces or other punctuation, enclose the - argument in curly brackets. - - \code - / *! - Here, we render \e {a few words} in italics. - * / - \endcode - - QDoc renders this as: - - \quotation - Here, we render \e {a few words} in italics. - \endquotation - - If you want to use other QDoc commands within an argument that - contains spaces, you always need to enclose the argument in - braces. But QDoc is smart enough to count parentheses [3], so you - don't need braces in cases like this: - - \code - / *! - An argument can sometimes contain whitespaces, - for example: \e QPushButton(tr("A Brand New Button")) - * / - \endcode - - QDoc renders this as: - - \quotation - An argument can sometimes contain whitespaces, - for example: \e QPushButton(tr("A Brand New Button")) - \endquotation - - Finally, trailing punctuation is not included in an argument [4], - nor is "'s" [5] - - \raw HTML - <table align="center" cellpadding="2" - cellspacing="1" border="0"> - <tr valign="top" bgcolor="#a2c511"> - <th></th> - <th>QDoc Syntax</th> - <th>Generated Documentation</th> - </tr> - - <tr valign="top" bgcolor="#d0d0d0"> - <td>1</td> - <td>A variation of a command button is a \e menu - button.</td> - <td>A variation of a command button is a <i>menu</i> - button.</td> - </tr> - - <tr valign="top" bgcolor="#c0c0c0"> - <td>2</td> - <td>The QPushButton widget provides a - \e {command button}.</td> - <td>The QPushButton widget provides a - <i>command button</i>.</td> - </tr> - - <tr valign="top" bgcolor="#d0d0d0"> - <td>3</td> - <td>Another class of buttons are option buttons - \e (see QRadioButton).</td> - <td>Another class of buttons are option buttons - <i> (see QRadioButton)</i>.</td> - </tr> - - <tr valign="top" bgcolor="#c0c0c0"> - <td>4</td> - <td>A push button emits the signal \e clicked().</td> - <td>A push button emits the signal <i>clicked</i>().</td> - </tr> - - <tr valign="top" bgcolor="#d0d0d0"> - <td>5</td> - <td>The \e QPushButton's checked property is - false by default.</td> - <td>The <i>QPushButton</i>'s checked property is - false by default.</td> - </tr> - - </table> - \endraw - - \target sub-command - \section1 \\sub - - The \\sub command renders its argument lower than the baseline of - the regular text, using a smaller font. - - \code - / *! - Definition (Range): Consider the sequence - {x\sub n}\sub {n > 1} . The set - - {x\sub 2, x\sub 3, x\sub 4, ...} = {x\sub n ; n = 2, 3, 4, ...} - - is called the range of the sequence. - * / - \endcode - - QDoc renders this as: - - \quotation - Definition (Range): Consider the sequence - {x\sub n}\sub {n > 1} . The set - - {x\sub 2, x\sub 3, x\sub 4, ...} = {x\sub n ; n = 2, 3, 4, ...} - - is called the range of the sequence. - \endquotation - - If the argument contains spaces or other punctuation, enclose the - argument in curly brackets. - - \target sup-command - \section1 \\sup - - The \\sup command renders its argument higher than - the baseline of the regular text, using a smaller font. - - \code - / *! - The series - - 1 + a + a\sup 2 + a\sup 3 + a\sup 4 + ... - - is called the \i {geometric series}. - * / - \endcode - - QDoc renders this as: - - \quotation - The series - - 1 + a + a\sup 2 + a\sup 3 + a\sup 4 + ... - - is called the \e {geometric series}. - \endquotation - - If the argument contains spaces or other punctuation, enclose the - argument in curly brackets. - - \target uicontrol-command - \section1 \\uicontrol - - The \\uicontrol command is used to mark content as being used for UI - control elements. When using HTML, the output is rendered in bold. - When using DITA XML the content is enclosed in a \c{uicontrol} tag. - - \sa \\b - - \target underline-command - \section1 \\underline - - The \\underline command renders its argument underlined. - - \code - / *! - The \underline {F}ile menu gives the users the possibility - to edit an existing file, or save a new or modified - file, and exit the application. - * / - \endcode - - QDoc renders this as: - - \quotation - The \underline {F}ile menu gives the users the possibility - to edit an existing file, or save a new or modified - file, and exit the application. - \endquotation - - If the argument contains spaces or other punctuation, enclose the - argument in curly brackets. - - \target backslash-command - \section1 \\\\ (double backslash) - - The \\\\ command expands to a double backslash. - - QDoc commands always start with a single backslash. To display a - single backslash in the text you need to type two backslashes. If - you want to display two backslashes, you need to type four. - - \code - / *! - The \\\\ command is useful if you want a - backslash to appear verbatim, for example, - writing C:\\windows\\home\\. - * / - \endcode - - QDoc renders this as: - - \quotation - The \\\\ command is useful if you want a - backslash to appear verbatim, for example, - writing C:\\windows\\home\\. - \endquotation - - However, if you want your text to appear in a monospace font as - well, you can use the \l {c-command} {\\c} command instead, which - accepts and renders the backslash as any other character. For - example: - - \code - / *! - The \\c command is useful if you want a - backslash to appear verbatim, and the word - that contains it written in a monospace font, - like this: \c {C:\windows\home\}. - * / - \endcode - - QDoc renders this as: - - \quotation - The \\c command is useful if you want a - backslash to appear verbatim, and the word - that contains it written in a monospace font, - like this: \c {C:\windows\home\}. - \endquotation - -*/ - - -/*! - \page 05-qdoc-commands-documentstructure.html - \previouspage Text Markup - \contentspage QDoc Manual - \nextpage Including Code Inline - - \title Document Structure - - The document structuring commands are for dividing your document - into sections. QDoc supports six kinds of sections: \c \part, \c - \chapter, \c \section1, \c \section2, \c \section3, and \c - \section4. The \c \section1..4 commands are the most useful. They - correspond to the traditional section, subsection, etc used in - outlining. - - \target part-command - \section1 \\part - - The \\part command is intended for use in a large document, like a - book. - - In general a document structuring command considers everything - that follows it until the first line break as its argument. The - argument is rendered as the unit's title. If the title needs to be - spanned over several lines, make sure that each line (except the - last one) is ended with a backslash. - - In total, there are six levels of sections in QDoc: \c \part, \c - \chapter, \c \section1, \c \section2, \c \section3 and \c - \section4. \c \section1 to \c \section4 correspond to the - traditional section, subsection, subsubsection and - subsubsubsection. - - There is a strict ordering of the section units: - - \code - part - | - chapter - | - section1 - | - section2 - | - section3 - | - section4 - \endcode - - For example, a \c section1 unit can only appear as the top level - section or inside a \c chapter unit. Skipping a section unit, for - example from \c part to \c section1, is not allowed. - - You can \e begin with either of the three: \c part, \c chapter or - \c section1. - - - \code - / *! - \part Basic Qt - - This is the first part. - - - \chapter Getting Started - - This is the first part's first chapter. - - - \section1 Hello Qt - - This is the first chapter's first section. - - - \section1 Making Connections - - This is the first chapter's second section. - - - \section1 Using the Reference Documentation - - This is the first chapter's third section. - - - \chapter Creating Dialogs - - This is the first part's second chapter. - - - \section1 Subclassing QDialog - - This is the second chapter's first section. - - ... - - - \part Intermediate Qt - - This is the second part. - - - \chapter Layout Management - - This is the second part's first chapter. - - - \section1 Basic Layouts - - This is the first chapter's first section. - - ... - * / - \endcode - - QDoc renders this as: - - \quotation - \raw HTML - <a name="Basic Qt"> - <h1>Basic Qt</h1> - </a> - <p>This is the first part.</p> - - <a name="Getting started"> - <h2>Getting Started</h2> - </a> - This is the first part's first chapter.</p> - - <a name="Hello Qt"> - <h3>Hello Qt</h3> - </a> - <p>This is the first chapter's first section.</p> - - <a name="Making Connections"> - <h3>Making Connections</h3> - </a> - <p>This is the first chapter's second section.</p> - - <a name="Using the Reference Documentation"> - <h3>Using the Reference Documentation</h3> - </a> - <p>This is the first chapter's third section.</p> - - <a name="Creating Dialogs"> - <h2>Creating Dialogs</h2> - </a> - <p>This is the first part's second chapter.</p> - - <a name="Subclassing QDialog"> - <h3>Subclassing QDialog</h3> - </a> - <p>This is the second chapter's first section.</p> - - ... - - <a name="Intermediate Qt"> - <h1>Intermediate Qt</h1> - </a> - <p>This is the second part.</p> - - <a name="Layout Management"> - <h2>Layout Management</h2> - </a> - <p>This is the second part's first chapter.</p> - - <a name="Basic Layouts"> - <h3>Basic Layouts</h3> - </a> - <p>This is the first chapter's first section.</p> - - ... - - \endraw - \endquotation - - Each section is a logical unit in the document. The section - heading appears in the automatically generated table of contents - that normally appears in the upper right-hand corner of the page. - - \target chapter-command - \section1 \\chapter - - The \\chapter command is intended for use in - larger documents, and divides the document into chapters. - - See \l{part} {\\part} for an explanation of the various - section units, command argument, and rendering. - - \target sectionOne-command - \section1 \\section1 - - The \\section1 command starts a new section. - - See \l{part} {\\part} for an explanation of the various - section units, command argument, and rendering. - - \target sectionTwo-command - \section1 \\section2 - - The \\section2 command starts a new section. - - See \l{part} {\\part} for an explanation of the various - section units, command argument, and rendering. - - \target sectionThree-command - \section1 \\section3 - - The \\section3 command starts a new section. - - See \l{part} {\\part} for an explanation of the various - section units, command argument, and rendering. - - \target sectionFour-command - \section1 \\section4 - - The \\section4 command starts a new section. - - See \l{part} {\\part} for an explanation of the various - section units, command argument, and rendering. - -*/ - - -/*! - \page 06-qdoc-commands-includecodeinline.html - \previouspage Document Structure - \contentspage QDoc Manual - \nextpage Including External Code - - \title Including Code Inline - - The following commands are used to render source code without - formatting. The source code begins on a new line, rendered in the - code. - - \b{Note:} Although all these commands are for rendering C++ - code, the - \l{07-0-qdoc-commands-includingexternalcode.html#snippet-command} - {\\snippet} and - \l{07-0-qdoc-commands-includingexternalcode.html#codeline-command} - {\\codeline} commands are preferred over the others. These - commands allow equivalent code snippets for other Qt language - bindings to be substituted for the C++ snippets in the - documentation. - - \target code-command - \section1 \\code - - The \\code and \\endcode commands enclose a snippet of source code. - - \note The \l {c-command} {\\c} command can be used for short code - fragments within a sentence. The \\code command is for longer code - snippets. It renders the code verbatim in a separate paragraph in - the code font. - - When processing any of the \\code, \l {newcode-command} {\\newcode} or \l - {oldcode-command} {\\oldcode} commands, QDoc removes all - indentation that is common for the verbatim code blocks within a - \c{/}\c{*!} ... \c{*}\c{/} comment before it adds the standard - indentation. For that reason the recommended style is to use 8 - spaces for the verbatim code contained within these commands - - \note This doesn't apply to externally quoted code using the \l - {quotefromfile-command} {\\quotefromfile} or \l - {quotefile-command} {\\quotefile} command. - - \code - / *! - \code - #include <QApplication> - #include <QPushButton> - - int main(int argc, char *argv[]) - { - ... - } - \ endcode - * / - \endcode - - QDoc renders this as: - - \code - #include <QApplication> - #include <QPushButton> - - int main(int argc, char *argv[]) - { - ... - } - \endcode - - Other QDoc commands are disabled within \\code... \\endcode, and - the special character '\\' is accepted and rendered like the rest - of the code. - - To include code snippets from an external file, use the - \l{07-0-qdoc-commands-includingexternalcode.html#snippet-command} - {\\snippet} and - \l{07-0-qdoc-commands-includingexternalcode.html#codeline-command} - {\\codeline} commands. - - See also \l {c-command} {\\c}, \l - {07-0-qdoc-commands-includingexternalcode.html#quotefromfile-command} - {\\quotefromfile}, \l{newcode-command} {\\newcode}, and \l {oldcode-command} - {\\oldcode}. - - \target newcode-command - \section1 \\newcode - - The \\newcode, \\oldcode, and \\endcode commands enable you to - show how to port a snippet of code to a new version of an API. - - The \\newcode command and its companion the \\oldcode command are - a convenience combination of the \l {code-command} {\\code} commands: - this combination provides a text relating the two code snippets to each - other. - - The \\newcode command requires a preceding \\oldcode statement. - - Like the \l{code-command}{\\code} command, the \\newcode command renders its - code on a new line in the documentation using a monospace font and the - standard indentation. - - \code - / *! - \oldcode - if (printer->setup(parent)) - ... - \newcode - QPrintDialog dialog(printer, parent); - if (dialog.exec()) - ... - \ endcode - * / - \endcode - - QDoc renders this as: - - \quotation - \oldcode - if (printer->setup(parent)) - ... - \newcode - QPrintDialog dialog(printer, parent); - if (dialog.exec()) - ... - \endcode - \endquotation - - Other QDoc commands are disabled within \\oldcode ... \\endcode, - and the '\\' character doesn't need to be escaped. - - \target oldcode-command - \section1 \\oldcode - - The \\oldcode command requires a corresponding - \\newcode statement; otherwise QDoc fails to parse the command - and emits a warning. - - See also \l {newcode-command} {\\newcode}. - - \target qml-command - \section1 \\qml - - The \\qml and \\endqml commands enclose a snippet of QML source - code. Currently, QDoc handles \\qml and \\endqml in exactly the same - way as \\code and \\endcode. - - \code - / *! - \qml - import QtQuick 1.0 - - Row { - Rectangle { - width: 100; height: 100 - color: "blue" - transform: Translate { y: 20 } - } - Rectangle { - width: 100; height: 100 - color: "red" - transform: Translate { y: -20 } - } - } - \endqml - * / - \endcode - - QDoc renders this as: - - \qml - import QtQuick 1.0 - - Row { - Rectangle { - width: 100; height: 100 - color: "blue" - transform: Translate { y: 20 } - } - Rectangle { - width: 100; height: 100 - color: "red" - transform: Translate { y: -20 } - } - } - \endqml -*/ - - -/*! - \page 07-0-qdoc-commands-includingexternalcode.html - \previouspage Including Code Inline - \contentspage QDoc Manual - \nextpage Creating Links - - \title Including External Code - - The following commands enable you to include code snippets from - external files. You can make QDoc include the complete contents of - a file, or you can quote specific parts of the file and skip - others. The typical use of the latter is to quote a file chunk by - chunk. - - \b{Note:} Although all these commands are for rendering C++ - code, the - \l{07-0-qdoc-commands-includingexternalcode.html#snippet-command} - {\\snippet} and - \l{07-0-qdoc-commands-includingexternalcode.html#codeline-command} - {\\codeline} commands are preferred over the others. These - commands allow equivalent code snippets for other Qt language - bindings to be substituted for the C++ snippets in the - documentation. - - \target quotefile-command - \section1 \\quotefile - - The \\quotefile command expands to the complete contents of the - file given as argument. - - The command considers the rest of the line as part of its - argument, make sure to follow the file name with a line break. - - The file's contents is rendered in a separate paragraph, using a - monospace font and the standard indentation. The code is shown - verbatim. - - \code - / *! - This is a simple "Hello world" example: - - \quotefile examples/main.cpp - - It contains only the bare minimum you need - to get a Qt application up and running. - * / - \endcode - - QDoc renders this as: - - \quotation - This is a simple "Hello world" example: - - \quotefile examples/main.cpp - - It contains only the bare minimum you need to get a Qt - application up and running. - \endquotation - - See also \l {quotefromfile-command} {\\quotefromfile} and - \l {code-command} {\\code}. - - - \target quotefromfile-command - \section1 \\quotefromfile - - The \\quotefromfile command opens the file given as argument for - quoting. - - The command considers the rest of the line as part of its - argument, make sure to follow the file name with a line break. - - The command is intended for use when quoting parts from file with - the walkthrough commands: \l {printline-command} {\\printline}, \l - {printto-command} {\\printto}, \l {printuntil-command} - {\\printuntil}, \l {skipline-command} {\\skipline}, \l - {skipto-command} {\\skipto}, \l {skipuntil-command} - {\\skipuntil}. This enables you to quote specific portions of a - file. - - \code - / *! - The whole application is contained within - the \c main() function: - - \quotefromfile examples/main.cpp - - \skipto main - \printuntil app(argc, argv) - - First we create a QApplication object using - the \c argc and \c argv parameters. - - \skipto QPushButton - \printuntil resize - - Then we create a QPushButton, and give it a reasonable - size using the QWidget::resize() function. - - ... - * / - \endcode - - QDoc renders this as: - - \quotation - The whole application is contained within - the \c main() function: - - \quotefromfile examples/main.cpp - - \skipto main - \printuntil app(argc, argv) - - First we create a QApplication object using the \c argc - and \c argv parameters. - - \skipto QPushButton - \printuntil resize - - Then we create a QPushButton, and give it a reasonable - size using the QWidget::resize() function. - - ... - \endquotation - - QDoc remembers which file it is quoting from, and the current - position in that file (see \l {file} {\\printline} for more - information). There is no need to "close" the file. - - See also \l {quotefile-command} {\\quotefile}, \l {code-command} - {\\code} and \l {dots} {\\dots}. - - \target printline-command - \section1 \\printline - - The \\printline command expands to the line from the current - position to the next non-blank line of the current source file. - - To ensure that the documentation remains synchronized with the - source file, a substring of the line must be specified as an - argument to the command. Note that the command considers the rest - of the line as part of its argument, make sure to follow the - substring with a line break. - - The line from the source file is rendered as a separate paragraph, - using a monospace font and the standard indentation. The code is - shown verbatim. - - \code - / *! - There has to be exactly one QApplication object - in every GUI application that uses Qt. - - \quotefromfile examples/main.cpp - - \printline QApplication - - This line includes the QApplication class - definition. QApplication manages various - application-wide resources, such as the - default font and cursor. - - \printline QPushButton - - This line includes the QPushButton class - definition. The QPushButton widget provides a command - button. - - \printline main - - The main function... - * / - \endcode - - QDoc renders this as: - - \quotation - There has to be exactly one QApplication object - in every GUI application that uses Qt. - - \quotefromfile examples/main.cpp - - \skipto QApplication - \printline QApplication - - This line includes the QApplication class - definition. QApplication manages various - application-wide resources, such as the - default font and cursor. - - \printline QPushButton - - This line includes the QPushButton class - definition. The QPushButton widget provides a command - button. - - \printline main - - The main function... - \endquotation - - \target file - - QDoc reads the file sequentially. To move the current position - forward you can use either of the \l {skipline-command} - {\\skip...} commands. To move the current position backward, you - can use the \l {quotefromfile-command} {\\quotefromfile} command - again. - - \target substring - - If the substring argument is surrounded by slashes it is - interpreted as a \l {QRegExp}{regular expression}. - - \code - / *! - \quotefromfile examples/mainwindow.cpp - - \skipto closeEvent - \printuntil /^\}/ - - Close events are sent to widgets that the users want to - close, usually by clicking \c File|Exit or by clicking - the \c X title bar button. By reimplementing the event - handler, we can intercept attempts to close the - application. - * / - \endcode - - QDoc renders this as: - - \quotation - \quotefromfile examples/mainwindow.cpp - - \skipto closeEvent - \printuntil /^\}/ - - Close events are sent to widgets that the users want to - close, usually by clicking \c File|Exit or by clicking - the \c X title bar button. By reimplementing the event - handler, we can intercept attempts to close the - application. - \endquotation - - (\l {widgets/scribble} {The complete example file...}) - - The regular expression \c /^\}/ makes QDoc print until the first - '}' character occurring at the beginning of the line without - indentation. /.../ encloses the regular expression, and '^' means - the beginning of the line. The '}' character must be escaped since - it is a special character in regular expressions. - - QDoc will emit a warning if the specified substring or regular - expression cannot be located, i.e. if the source code has changed. - - See also \l {printto-command} {\\printto} and \l - {printuntil-command} {\\printuntil}. - - \target printto-command - \section1 \\printto - - The \\printto command expands to all the lines from the current - position up to and \e excluding the next line containing a given - substring. - - The command considers the rest of the line as part of its - argument, make sure to follow the substring with a line break. The - command also follows the same conventions for \l {file} - {positioning} and \l {substring} {argument} as the \l - {printline-command} {\\printline} command. - - The lines from the source file are rendered in a separate - paragraph, using a monospace font and the standard - indentation. The code is shown verbatim. - - \code - / *! - The whole application is contained within the - \c main() function: - - \quotefromfile examples/main.cpp - \printto hello - - First we create a QApplication object using the \c argc and - \c argv parameters... - * / - \endcode - - QDoc renders this as: - - \quotation - The whole application is contained within the - \c main() function: - - \quotefromfile examples/main.cpp - \skipto main - \printto hello - - First we create a QApplication object using the \c argc - and \c argv parameters... - \endquotation - - See also \l {printline-command} {\\printline} and \l - {printuntil-command} {\\printuntil}. - - \target printuntil-command - \section1 \\printuntil - - The \\printuntil command expands to all the lines from the current - position up to and \e including the next line containing a given - substring. - - The command considers the rest of the line as part of its - argument, make sure to follow the substring with a line break. The - command also follows the same conventions for \l {file} - {positioning} and \l {substring} {argument} as the \l - {printline-command} {\\printline} command. - - The lines from the source file are rendered in a separate - paragraph, using a monospace font and the standard - indentation. The code is shown verbatim. - - \code - / *! - The whole application is contained within the - \c main() function: - - \quotefromfile examples/main.cpp - \skipto main - \printuntil hello - - First we create a QApplication object using the - \c argc and \c argv parameters, then we create - a QPushButton. - * / - \endcode - - QDoc renders this as: - - \quotation - The whole application is contained within the - \c main() function: - - \quotefromfile examples/main.cpp - \skipto main - \printuntil hello - - First we create a \l - {http://doc.qt.io/qt-5/qapplication.html} {QApplication} - object using the \c argc and \c argv parameters, then we - create a \l - {http://doc.qt.io/qt-5/qpushbutton.html} {QPushButton}. - \endquotation - - See also \l {printline-command} {\\printline} and \l - {printto-command} {\\printto}. - - \target skipline-command - \section1 \\skipline - - The \\skipline command ignores the next non-blank line in the - current source file. - - Doc reads the file sequentially, and the \\skipline command is - used to move the current position (omitting a line of the source - file). See the remark about \l {file} {file positioning} above. - - The command considers the rest of the line as part of its - argument, make sure to follow the substring with a line break. The - command also follows the same conventions for \l {substring} - {argument} as the \l {printline-command} {\\printline} command, - and it is used in conjunction with the \l {quotefromfile-command} - {\\quotefromfile} command. - - \code - / *! - QPushButton is a GUI push button that the user - can press and release. - - \quotefromfile examples/main.cpp - \skipline QApplication - \printline QPushButton - - This line includes the QPushButton class - definition. For each class that is part of the - public Qt API, there exists a header file of - the same name that contains its definition. - * / - \endcode - - QDoc renders this as: - - \quotation - \l - QPushButton is a GUI push button that the user - can press and release. - - \quotefromfile examples/main.cpp - \skipto QApplication - \skipline QApplication - \printline QPushButton - - This line includes the QPushButton class - definition. For each class that is part of the public - Qt API, there exists a header file of the same name - that contains its definition. - \endquotation - - See also \l {skipto-command} {\\skipto}, \l {skipuntil-command} - {\\skipuntil} and \l {dots} {\\dots}. - - \target skipto-command - \section1 \\skipto - - The \\skipto command ignores all the lines from the current - position up to and \e excluding the next line containing a given - substring. - - QDoc reads the file sequentially, and the \\skipto command is used - to move the current position (omitting one or several lines of the - source file). See the remark about \l {file} {file positioning} - above. - - The command considers the rest of the line as part of its - argument, make sure to follow the substring with a line break. - - The command also follows the same conventions for \l {substring} - {argument} as the \l {printline-command} {\\printline} command, - and it is used in conjunction with the \l {quotefromfile-command} - {\\quotefromfile} command. - - \code - / *! - The whole application is contained within - the \c main() function: - - \quotefromfile examples/main.cpp - \skipto main - \printuntil } - - First we create a QApplication object. There - has to be exactly one such object in - every GUI application that uses Qt. Then - we create a QPushButton, resize it to a reasonable - size... - * / - \endcode - - QDoc renders this as: - - \quotation - The whole application is contained within - the \c main() function: - - \quotefromfile examples/main.cpp - \skipto main - \printuntil } - - First we create a QApplication object. There has to be - exactly one such object in every GUI application that - uses Qt. Then we create a QPushButton, resize it to a - reasonable size ... - \endquotation - - See also \l {skipline-command} {\\skipline}, \l - {skipuntil-command} {\\skipuntil} and \l {dots} {\\dots}. - - \target skipuntil-command - \section1 \\skipuntil - - The \\skipuntil command ignores all the lines from the current - position up to and \e including the next line containing a given - substring. - - QDoc reads the file sequentially, and the \\skipuntil command is - used to move the current position (omitting one or several lines - of the source file). See the remark about \l {file} {file - positioning} above. - - The command considers the rest of the line as part of its - argument, make sure to follow the substring with a line break. - - The command also follows the same conventions for \l {substring} - {argument} as the \l {printline-command} {\\printline} command, - and it is used in conjunction with the \l {quotefromfile-command} - {\\quotefromfile} command. - - \code - / *! - The first thing we did in the \c main() function - was to create a QApplication object \c app. - - \quotefromfile examples/main.cpp - \skipuntil show - \dots - \printuntil } - - In the end we must remember to make \c main() pass the - control to Qt. QCoreApplication::exec() will return when - the application exits... - * / - \endcode - - QDoc renders this as: - - \quotation - The first thing we did in the \c main() function was to - create a QApplication object \c app. - - \quotefromfile examples/main.cpp - \skipuntil show - \dots - \printuntil } - - In the end we must remember to make \c main() pass the - control to Qt. QCoreApplication::exec() - will return when the application exits... - \endquotation - - See also \l {skipline-command} {\\skipline}, \l {skipto-command} - {\\skipto} and \l {dots} {\\dots}. - - \target dots-command - \section1 \\dots - - The \\dots command indicates that parts of the source file have - been omitted when quoting a file. - - The command is used in conjunction with the \l - {quotefromfile-command} {\\quotefromfile} command, and should be - stated on its own line. The dots are rendered on a new line, using - a monospace font. - - \code - / *! - \quotefromfile examples/main.cpp - \skipto main - \printuntil { - \dots - \skipuntil exec - \printline } - * / - \endcode - - QDoc renders this as: - - \quotefromfile examples/main.cpp - \skipto main - \printuntil { - \dots - \skipuntil exec - \printline } - - The default indentation is 4 spaces, but this can be adjusted - using the command's optional argument. - - \code - / *! - \dots 0 - \dots - \dots 8 - \dots 12 - \dots 16 - * / - \endcode - - QDoc renders this as: - - \dots 0 - \dots - \dots 8 - \dots 12 - \dots 16 - - See also \l {skipline-command} {\\skipline}, \l {skipto-command} - {\\skipto} and \l {skipuntil-command} {\\skipuntil}. - - \target snippet-command - \section1 \\snippet - - The \\snippet command causes a code snippet to be included - verbatim as preformatted text, which may be syntax highlighted. - - Each code snippet is referenced by the file that holds it and by - a unique identifier for that file. Snippet files are typically - stored in a \c{snippets} directory inside the documentation - directory (for example, \c{$QTDIR/doc/src/snippets}). - - For example, the following documentation references a snippet in a - file residing in a subdirectory of the documentation directory: - - \code - \snippet snippets/textdocument-resources/main.cpp Adding a resource - \endcode - - The text following the file name is the unique identifier for the - snippet. This is used to delimit the quoted code in the relevant - snippet file, as shown in the following example that corresponds to - the above \c{\\snippet} command: - - \dots - \code - QImage image(64, 64, QImage::Format_RGB32); - image.fill(qRgb(255, 160, 128)); - - //! [Adding a resource] - document->addResource(QTextDocument::ImageResource, - QUrl("mydata://image.png"), QVariant(image)); - //! [Adding a resource] - \endcode - \dots - - \target codeline-command - \section1 \\codeline - - The \\codeline command inserts a blank line of preformatted - text. It is used to insert gaps between snippets without closing - the current preformatted text area and opening a new one. - -*/ - - -/*! - \page 08-qdoc-commands-creatinglinks.html - \previouspage Including External Code - \contentspage QDoc Manual - \nextpage Including Images - - \title Creating Links - - These commands are for creating hyperlinks to classes, functions, - examples, and other targets. - - \target l-command - \section1 \\l (link) - - The \\l link command is used to create a hyperlink to many - different kinds of targets. The command's general syntax is: - - \code - \l [ link criteria ] { link target } { link text } - \endcode - - ...where the \c {link criteria} in square brackets are optional - but may be required when the \c {link target} is ambiguous. See - \l {Fixing Ambiguous Links} below. - - Here is an example using the \\l command to link to an external page: - - \code - / *! - Read the \l {http://doc.qt.io/qt-5/} - {Qt 5.0 Documentation} carefully. - * / - \endcode - - QDoc renders this as: - - \quotation - Read the \l {http://doc.qt.io/qt-5/} - {Qt 5.0 Documentation} carefully. - \endquotation - - If the link target is equivalent to the link text, the second - argument can be omitted. - - For example, if you have documentation like: - - \code - / *! - \target assertions - - Assertions make some statement about the text at the - point where they occur in the regexp, but they do not - match any characters. - - ... - - Regexps are built up from expressions, quantifiers, and - \l {assertions} {assertions}. - * / - \endcode - - You can simplify this as follows: - - \code - / *! - \target assertions - - Assertions make some statement about the text at the - point where they occur in the regexp, but they do not - match any characters. - - ... - - Regexps are built up from expressions, quantifiers, and - \l assertions. - * / - \endcode - - For the one-parameter version, the braces can often be omitted. - The \\l command supports several ways of linking: - - \list - - \li \c {\l QWidget} - The name of a class documented with the \l - {class-command} {\\class} command. - - \li \c {\l QWidget::sizeHint()} - The signature of a function without - parameters. If a matching function without parameters can't be found, - the link is satisfied with the first matching function found. - - \li \c {\l QWidget::removeAction(QAction* action)} - The signature - of a function with parameters. If an exact match is not found, the - link is not satisfied and qdoc reports a \e {Can't link to...} error. - - \li \c {\l <QtGlobal>} - The subject of a \l {headerfile-command} - {\\headerfile} command. - - \li \c {\l widgets/wiggly} - The relative path used in an \l - {example-command} {\\example} command. - - \li \c {\l {QWidget Class Reference}} - The title used in a - \l {title-command} {\\title} command. - - \li \c {\l {Introduction to QDoc}}- The text from one of the - \l{part-command} {\\part}, \l{chapter} {\\chapter}, or \l - {sectionOne-command} {\\section} commands. - - \li \c {\l fontmatching} - The argument of a \l {target-command} - {\\target} command. - - \li \c {\l {Shared Classes}} - A keyword named in a \l - {keyword-command} {\\keyword} command. - - \li \c {\l http://qt-project.org/} - A URL. - - \endlist - - QDoc also tries to make a link out of any word that doesn't - resemble a normal English word, for example, Qt class names or - functions, like QWidget or QWidget::sizeHint(). In these cases, - the \\l command can actually be omitted, but by using the command, - you ensure that QDoc will emit a warning if it cannot find the - link target. In addition, if you only want the function name to - appear in the link, you can use the following syntax: - - \list - \li \c {\l {QWidget::} {sizeHint()}} - \endlist - - QDoc renders this as: - - \quotation - \l {QWidget::} {sizeHint()} - \endquotation - - \section2 Fixing Ambiguous Links - - Because of the modularization of Qt beginning with Qt 5.0, The - possibility that qdoc will have to deal with ambiguous links has - increased. An ambiguous link is one that has a matching target in - more than one Qt module, e.g. the same section title can appear in - more than one Qt module, or the name of a C++ class in one module - can also be the name of a QML type in another module. A real - example in Qt5 is the name Qt itself. Qt is the name of both a C++ - namespace in QtCore and a QML type in QtQml. - - Suppose we want to link to the \l {Qt} {Qt C++ namespace}. At the - time qdoc generated this HTML page, that link was correct. Does - it still go to the C++ namespace? Qdoc generated that link from - this link command: - - \list - \li \c {\l {Qt} {Qt C++ namespace}} - \endlist - - Now suppose we want to link to the \l [QML] {Qt} {Qt QML type}. - At the time qdoc generated this HTML page, that link was also - correct, but we had to use this link command: - - \list - \li \c {\l [QML] {Qt} {Qt QML type}} - \endlist - - The \e {QML} in \e {square brackets} tells qdoc to accept a - matching target only if the traget is on a QML page. Qdoc actually - finds the C++ namespace target first, but since that target is on - a C++ page, qdoc ignores it and keeps looking until it finds the - same target on a QML page. - - Without the guidance in the \e{\\l command} in the optional \e - {square bracket} argument, qdoc links to the first matching target - it finds. qdoc can't warn that the link was ambiguous in such - cases because it doesn't know that another matching target exists. - - \section2 What arguments can appear in square brackets? - - A link command with square bracket argument has the following syntax: - \list - \c {\l [QML|CPP|DOC|QtModuleName] {link target} {link text}} - \endlist - - The \e {square bracket} argument is only allowed in the \c {\\l - (link)} command. The example above shows how \c QML is used as the - \e {square brackets} argument to force qdoc to match a QML target. - Most often, this will be a QML type, but it can also be a QML - member function of property. - - In the example, qdoc didn't need a \e {square bracket} argument to - find the Qt C++ namespace page, because that one was the first - matching target qdoc found anyway. However, to force qdoc to find - a C++ target when a matching QML target gets in the way, \c CPP - can be used as the \e {square bracket} argument. For example: - - \list - \li \c {\l [CPP] {Qt} {Qt C++ namespace}} - \endlist - - ...will force qdoc to ignore the Qt QML type and continue - searching until it matches the Qt C++ namespace. - - If the link target is neither a C++ nor a QML entity, \c {DOC} can - be used as the \e {square bracket} argument to prevent qdoc from - matching either of those. At this writing, there were no cases of - ambiguous links where using \c {DOC} was required. - - Often, the documentor knows which Qt module the link target is - in. When the module name is known, use the module name as the \e - {square bracket} argument. In the example above, if we know that - the QML type named Qt is located in the QtQml module, we can write - the link command like this: - - \list - \li \c {\l [QtQml] {Qt} {Qt QML type}} - \endlist - - When a module name is used as the \e {square bracket} argument, - qdoc will search for link the target in that module only. This - makes searching for link targets more efficient. - - Finally, the module name and entity type arguments can be - combined, separated by a blank, so something like this is also - allowed: - - \list - \li \c {\l [CPP QtQml] {Window} {C++ class Window}} - \endlist - - As of this writing, there were no cases where combining the two - was required. - - See also \l {sa-command} {\\sa}, \l {target-command} {\\target}, - and \l {keyword-command} {\\keyword}. - - - \target sa-command - \section1 \\sa (see also) - - The \\sa command defines a list of links that will be rendered in - a separate "See also" section at the bottom of the documentation - unit. - - The command takes a comma-separated list of links as its - argument. If the line ends with a comma, you can continue - the list on the next line. The general syntax is: - - \code - \sa {the first link}, {the second link}, - {the third link}, ... - \endcode - - QDoc will automatically try to generate "See also" links - interconnecting a property's various functions. For example, a - setVisible() function will automatically get a link to visible() - and vice versa. - - In general, QDoc will generate "See also" links that interconnect - the functions that access the same property. It recognizes four - different syntax versions: - - \list - \li \c property() - \li \c setProperty() - \li \c isProperty() - \li \c hasProperty() - \endlist - - The \\sa command supports the same kind of links as the \l - {l-command} {\\l} command. - - \code - / *! - Appends the actions \a actions to this widget's - list of actions. - - \sa removeAction(), QMenu, addAction() - * / - void QWidget::addActions(QList<QAction *> actions) - { - ... - } - \endcode - - QDoc renders this as: - - \quotation - \b {void QWidget::addActions ( QList<QAction*> - \e actions )} - - Appends the actions \e actions to this widget's list of - actions. - - See also \l {QWidget::removeAction()} {removeAction()}, - \l QMenu, and \l {QWidget::addAction()} {addAction()}. - \endquotation - - See also \l {l-command} {\\l}, \l {target-command} {\\target} and - \l {keyword-command} {\\keyword}. - - - \target target-command - \section1 \\target - - The \\target command names a place in the documentation that you - can link to using the \l {l-command} {\\l (link)} and \l - {sa-command} {\\sa (see also)} commands. - - The text up to the line break becomes the target name. Be sure to - follow the target name with a line break. Curly brackets are not - required around the target name, but they may be required when the - target name is used in a link command. See below. - - \code - / *! - \target capturing parentheses - \section1 Capturing Text - - Parentheses allow us to group elements together so that - we can quantify and capture them. - - ... - * / - \endcode - - The target name \e{capturing parentheses} can be linked from - within the same document containing the target in the following way: - - \list - \li \c {\l {capturing parentheses}} (from within the same QDoc comment) - \endlist - - \note The brackets in the link example are required because the - target name contains spaces. - - See also \l {l-command} {\\l}, \l {sa-command} {\\sa} and \l - {keyword-command} {\\keyword}. - - \target keyword-command - \section1 \\keyword - - The \\keyword command names a place in the documentation that you - can link to using the \l {l-command} {\\l (link)} and \l - {sa-command} {\\sa (see also)} commands. - - The \\keyword command is like the \l {target-command} {\\target} - command, except when linking to keyword the link goes to the top of - the QDoc comment where the \\keyword appears in. If you want to - create a link target to a \c section unit within a \\page, use - \\target instead. A keyword can be linked from anywhere using a - simple syntax. - - Keywords must be unique over all the documents processed during - the QDoc run. The command uses the rest of the line as its - argument. Be sure to follow the keyword with a line break. - - - \code - / *! - \class QRegExp - \reentrant - \brief The QRegExp class provides pattern - matching using regular expressions. - \ingroup tools - \ingroup misc - \ingroup shared - - \keyword regular expression - - Regular expressions, or "regexps", provide a way to - find patterns within text. - - ... - * / - \endcode - - The location marked with the keyword can be linked to with: - - \code - / *! - When a string is surrounded by slashes, it is - interpreted as a \l {QRegExp}{regular expression}. - * / - \endcode - - QDoc renders this as: - - \quotation - When a string is surrounded by slashes, it is - interpreted as a \l {regular expression}. - \endquotation - - If the keyword text contains spaces, the brackets are required. - - See also \l {l-command} {\\l (link)}, \l {sa-command} {\\sa (see - also)} and \l {target-command} {\\target}. - -*/ - - -/*! - \page 09-qdoc-commands-includingimages.html - \previouspage Creating Links - \contentspage QDoc Manual - \nextpage Tables and Lists - - \title Including Images - - The graphic commands makes it possible to include images in the - documentation. The images can be rendered as separate paragraphs, - or within running text. - - \target image-command - \section1 \\image - - The \\image command expands to the image specified by its first - argument, and renders it centered as a separate paragraph. - - The command takes two arguments. The first argument is the name of - the image file. The second argument is optional and is a simple - description of the image, equivalent to the HTML alt="" in an image - tag. The description is used for tooltips and for browsers that don't - support images, like the Lynx text browser. - - The remaining text \e{after} the file name is the optional, - description argument. Be sure to follow the file name or the - description with a line break. Curly brackets are required if the - description argument spans multiple lines. - - \code - / *! - Qt is a C++ toolkit for cross-platform GUI application development. - - \image happyguy.jpg "Happy guy" - - Qt provides single-source portability across Microsoft - Windows, OS X, Linux, and all major commercial Unix - variants. It is also available for embedded devices. - * / - \endcode - - QDoc renders this as: - - \quotation - Qt is a C++ toolkit for cross-platform GUI application development. - - \image happyguy.jpg image "Happy guy" - - Qt provides single-source portability across Microsoft - Windows, OS X, Linux, and all major commercial Unix - variants. It is also available for embedded devices. - \endquotation - - See also \l {inlineimage-command} {\\inlineimage} and \l - {caption-command} {\\caption}. - - \target inlineimage-command - \section1 \\inlineimage - - The \\inlineimage command expands to the image specified by its - argument. The image is rendered inline with the rest of the text. - - The command takes two arguments. The first argument is the name of - the image file. The second argument is optional and is a simple - description of the image, equivalent to the HTML alt="" in an image - tag. The description is used for tooltips, and for when a browser - doesn't support images, like the Lynx text browser. - - The most common use of the \\inlineimage command is in lists and - tables. Here is an example of including inline images in a list: - - \code - / *! - \list 1 - \li \inlineimage happy.gif Oh so happy! - \li \inlineimage happy.gif Oh so happy! - \li \inlineimage happy.gif Oh so happy! - \endlist - * / - \endcode - - QDoc renders this as: - - \list 1 - \li \inlineimage happy.gif Oh so happy! - \li \inlineimage happy.gif Oh so happy! - \li \inlineimage happy.gif Oh so happy! - \endlist - - Here is an example of including inline images in a table: - - \code - / *! - \table - \header - \li Qt - \li Qt Creator - \row - \li \inlineimage happy.gif Oh so happy! - \li \inlineimage happy.gif Oh so happy! - \row - \li \inlineimage happy.gif Oh so happy! - \li \inlineimage happy.gif Oh so happy! - \endtable - * / - \endcode - - QDoc renders this as: - - \raw HTML - <table align="center" cellpadding="2" - cellspacing="1" border="0"> - <tr valign="top" bgcolor="#a2c511"> - <th>Qt</th> - <th>Qt Creator</th> - </tr> - <tr valign="top" bgcolor="#f0f0f0"> - <td><img src="images/happy.gif" alt="Oh so happy!" /> - </td> - <td><img src="images/happy.gif" alt="Oh so happy!" /> - </td> - </tr> - <tr valign="top" bgcolor="#f0f0f0"> - <td><img src="images/happy.gif" alt="Oh so happy!"/> - </td> - <td><img src="images/happy.gif" alt="Oh so happy!" /> - </td> - </tr> - </table> - \endraw - - The command can also be used to insert an image inline with the - text. - - \code - / *! - \inlineimage training.jpg Qt Training - The Qt Programming course is offered as a - five day Open Enrollment Course. The classes - are open to the public. Although the course is open - to anyone who wants to learn, attendees should - have significant experience in C++ development - to derive maximum benefit from the course. - * / - \endcode - - QDoc renders this as: - - \quotation - \inlineimage training.jpg Qt Training - The Qt Programming course is offered as a - five day Open Enrollment Course. The classes - are open to the public. Although the course is open - to anyone who wants to learn, attendees should - have significant experience in C++ development - to derive maximum benefit from the course. - \endquotation - - See also \l {image-command} {\\image} and \l {caption-command} {\\caption}. - - \target caption-command - \section1 \\caption - - The \\caption command provides a caption for an image. - - The command takes all the text up to the end of the paragraph to - be the caption. Experiment until you get the effect you want. - - \code - / *! - \table 100% - \row - \li \image windowsvista-pushbutton.png - \caption The QPushButton widget provides a command button. - \li \image windowsvista-toolbutton.png - \caption The QToolButton class provides a quick-access button to commands - or options, usually used inside a QToolBar. - \endtable - * / - \endcode - - QDoc renders this as: - - \table 100% - \row - \li \image windowsvista-pushbutton.png - \caption The QPushButton widget provides a command button. - \li \image windowsvista-toolbutton.png - \caption The QToolButton class provides a quick-access button to commands - or options, usually used inside a QToolBar. - \endtable - - See also \l {image-command} {\\image} and \l {inlineimage-command} - {\\inlineimage} -*/ - - -/*! - \page 10-qdoc-commands-tablesandlists.html - \previouspage Including Images - \contentspage QDoc Manual - \nextpage Special Content - - \title Tables and Lists - - These commands enable creating lists and tables. A list is - rendered left aligned as a separate paragraph. A table is rendered - centered as a separate paragraph. The table width depends on the - width of its contents. - - \target table-command - \section1 \\table - - The \\table and \\endtable commands delimit the contents of a - table. - - The command accepts a single argument specifying the table's width - as a percentage of the page width: - - \code - / *! - \table 100 % - - ... - - \endtable - * / - \endcode - - The code above ensures that the table will fill all available - space. If the table's width is smaller than 100 %, the table will - be centered in the generated documentation. - - A table can contain headers, rows and columns. A row starts with a - \l {row-command} {\\row} command and consists of cells, each of which - starts with an \l {li-command} {\\li} command. There is also a \l - {header-command} {\\header} command which is a special kind of row - that has a special format. - - \code - / *! - \table - \header - \li Qt Core Feature - \li Brief Description - \row - \li \l {Signal and Slots} - \li Signals and slots are used for communication - between objects. - \row - \li \l {Layout Management} - \li The Qt layout system provides a simple - and powerful way of specifying the layout - of child widgets. - \row - \li \l {Drag and Drop} - \li Drag and drop provides a simple visual - mechanism which users can use to transfer - information between and within applications. - \endtable - * / - \endcode - - QDoc renders this as: - - \raw HTML - <table align="center" cellpadding="2" - cellspacing="1" border="0"> - <tr valign="top" bgcolor="#a2c511"> - <th>Qt Core Feature</th> - <th>Brief Description</th> - </tr> - - <tr valign="top" bgcolor="#d0d0d0"> - <td> - <a href="http://doc.qt.io/qt-5/signalsandslots.html"> - Signals and Slots</a> - </td> - <td>Signals and slots are used for communication - between objects.</td> - </tr> - - <tr valign="top" bgcolor="#c0c0c0"> - <td> - <a href="http://doc.qt.io/qt-5/layout.html"> - Layout Management</a></td> - <td>The Qt layout system provides a simple - and powerful way of specifying the layout - of child widgets.</td> - </tr> - - <tr valign="top" bgcolor="#d0d0d0"> - <td> - <a href="http://doc.qt.io/qt-5/dnd.html"> - Drag and Drop</a></td> - <td>Drag and drop provides a simple visual - mechanism which users can use to transfer - information between and within applications.</td> - </tr> - - </table> - \endraw - - You can also make cells span several rows and columns. For - example: - - \code - / *! - \table - \header - \li {3,1} This header cell spans three columns, - but only one row. - \row - \li {2, 1} This table cell spans two columns, - but only one row - \li {1, 2} This table cell spans only one column, - but two rows. - \row - \li A regular table cell - \li A regular table cell - \endtable - * / - \endcode - - QDoc renders this as: - - \raw HTML - <table align="center" cellpadding="2" cellspacing="1" - border="0"> - - <tr valign="top" bgcolor="#a2c511"> - <th colspan="3" rowspan=" 1"> - This header cell spans three columns, but only one row. - </th> - </tr> - - <tr valign="top" bgcolor="#d0d0d0"> - <td colspan="2" rowspan=" 1"> - This table cell spans two columns, but only one row. - </td> - <td rowspan=" 2"> - This table cell spans only one column, but two rows. - </td> - </tr> - - <tr valign="top" bgcolor="#c0c0c0"> - <td>A regular table cell</td> - <td>A regular table cell</td> - </tr> - - </table> - \endraw - - See also \l {header-command} {\\header}, \l {row-command} {\\row} and \l {li-command} {\\li}. - - \target header-command - \section1 \\header - - The \\header command indicates that the following table cells are - the current table's column headers. - - The command can only be used within the \l{table-command} - {\\table...\\endtable} commands. A header can contain several - cells. A cell is created with the \l {li-command} {\\li} command. - - A header cell's text is centered within the table cell and - rendered using a bold font. - - \code - / *! - \table - \header - \li Qt Core Feature - \li Brief Description - \row - \li \l {Signal and Slots} - \li Signals and slots are used for communication - between objects. - \endtable - * / - \endcode - - QDoc renders this as: - - \raw HTML - <table align="center" cellpadding="2" - cellspacing="1" border="0"> - <tr valign="top" bgcolor="#a2c511"> - <th>Qt Core Feature</th> - <th>Brief Description</th> - </tr> - - <tr valign="top" bgcolor="#d0d0d0"> - <td> - <a href="http://doc.qt.io/qt-5/signalsandslots.html"> - Signals and Slots</a> - </td> - <td>Signals and slots are used for communication - between objects.</td> - </tr> - </table> - \endraw - - See also \l {table-command} {\\table}, \l {row-command} {\\row} and \l {li-command} {\\li}. - - \target row-command - \section1 \\row - - The \\row command begins a new row in a table. The \l {li-command} - {\\li items} that belong in the new row will immediately follow the - \\row. - - The command can only be used within the \l{table-command} - {\\table...\\endtable} commands. A row can contain several - cells. A cell is created with the \l {li-command} {\\li} command. - - The background cell color of each row alternates between two - shades of grey, making it easier to distinguish the rows from each - other. The cells' contents is left aligned. - - \code - / *! - \table - \header - \li Qt Core Feature - \li Brief Description - \row - \li \l {Signal and Slots} - \li Signals and slots are used for communication - between objects. - \row - \li \l {Layout Management} - \li The Qt layout system provides a simple - and powerful way of specifying the layout - of child widgets. - \row - \li \l {Drag and Drop} - \li Drag and drop provides a simple visual - mechanism which users can use to transfer - information between and within applications. - \endtable - * / - \endcode - - QDoc renders this as: - - \raw HTML - <table align="center" cellpadding="2" - cellspacing="1" border="0"> - <tr valign="top" bgcolor="#a2c511"> - <th>Qt Core Feature</th> - <th>Brief Description</th> - </tr> - - <tr valign="top" bgcolor="#d0d0d0"> - <td> - <a href="http://doc.qt.io/qt-5/signalsandslots.html"> - Signals and Slots</a> - </td> - <td>Signals and slots are used for communication - between objects.</td> - </tr> - - <tr valign="top" bgcolor="#c0c0c0"> - <td> - <a href="http://doc.qt.io/qt-5/layout.html"> - Layout Management</a></td> - <td>The Qt layout system provides a simple - and powerful way of specifying the layout - of child widgets.</td> - </tr> - - <tr valign="top" bgcolor="#d0d0d0"> - <td> - <a href="http://doc.qt.io/qt-5/dnd.html"> - Drag and Drop</a></td> - <td>Drag and drop provides a simple visual - mechanism which users can use to transfer - information between and within applications.</td> - </tr> - - </table> - \endraw - - See also \l {table-command} {\\table}, \l {header-command} - {\\header}, and \l {li-command} {\\li}. - - \target value-command - \section1 \\value - - The \\value command starts the documentation of a C++ enum item. - - The command's first argument is the enum item. Then follows its - associated description. The description argument ends at the next - blank line or \\value. The arguments are rendered within a table. - - The documentation will be located in the associated class, header - file or namespace documentation. See the \l {enum-command} - {\\enum} documentation for an example. - - \note Since Qt 5.4, \\value command can also be used outside the - \l {enum-command} {\\enum} topic. In this case, QDoc renders a - two-column table listing the constant name (taken as-is from the - first argument) and its description. This can be used, for - example, in \l {qmlproperty-command}{\\qmlproperty} topic for - documenting acceptable values for a QML enumeration property. - - See also \l {enum-command} {\\enum} and \l {omitvalue-command} {\\omitvalue}. - - \target omitvalue-command - \section1 \\omitvalue - - The \\omitvalue command excludes a C++ enum item from the - documentation. - - The command's only argument is the name of the enum item that will - be omitted. See the \l {enum-command} {\\enum} documentation for - an example. - - See also \l {enum-command} {\\enum} and \l {value-command} - {\\value}. - - \target list-command - \section1 \\list - - The \\list and \\endlist commands delimit a list of items. - - Create each list item with the \l {li-command} {\\li} command. A - list always contains one or more items. Lists can be nested. For - example: - - \code - / *! - \list - \li Qt Reference Documentation: Getting Started - \list - \li How to Learn Qt - \li Installation - \list - \li Qt/X11 - \li Qt/Windows - \li Qt/Mac - \li Qt/Embedded - \endlist - \li Tutorial and Examples - \endlist - \endlist - * / - \endcode - - QDoc renders this as: - - \list - \li Qt Reference Documentation: Getting Started - \list - \li How to Learn Qt - \li Installation - \list - \li Qt/X11 - \li Qt/Windows - \li Qt/Mac - \li Qt/Embedded - \endlist - \li Tutorial and Examples - \endlist - \endlist - - The \\list command takes an optional argument providing - alternative appearances for the list items. - - \code - / *! - \list - \li How to Learn Qt - \li Installation - \li Tutorial and Examples - \endlist - * / - \endcode - - QDoc renders the list items with bullets (the default): - - \list - \li How to Learn Qt - \li Installation - \li Tutorial and Examples - \endlist - - \warning There appears to be a bug in qdoc here. If you include - any of the argument types, you get a numeric list. We're looking - into it. - - If you provide 'A' as an argument to the \\list command, the - bullets are replaced with characters in alphabetical order: - - \list A - \li How to Learn Qt - \li Installation - \li Tutorial and Examples - \endlist - - If you replace 'A' with '1', the list items are numbered in - ascending order: - - \list 1 - \li How to Learn Qt - \li Installation - \li Tutorial and Examples - - \endlist - - If you provide 'i' as the argument, the bullets are replaced with - roman numerals: - - \list i - \li How to Learn Qt - \li Installation - \li Tutorial and Examples - \endlist - - Finally, you can make the list items appear with roman numbers - following in ascending order if you provide 'I' as the optional - argument: - - \list I - \li How to Learn Qt - \li Installation - \li Tutorial and Examples - \endlist - - You can also make the listing start at any character or number by - simply provide the number or character you want to start at. For - example: - - \code - / *! - \list G - \li How to Learn Qt - \li Installation - \li Tutorial and Examples - \endlist - * / - \endcode - - \note This doesn't work in DITA XML, so don't use it because it - produces a DITA XML file that doesn't validate. There probably is - a way to do this in DITA, so if we figure it out, we will put it - in. But this capability is not used anywhere other than right - here, so it probably isn't important. For now, if you use this - option, qdoc will ignore it and produce a list without it. - - QDoc renders this as: - - \list G - \li How to Learn Qt - \li Installation - \li Tutorial and Examples - \endlist - - See also \l {li-command} {\\li}. - - \target li-command - \section1 \\li (table cell, list item) - - The \\li command marks a table cell or a list item. This command - is only used in \l{table-command} {tables} and \l{list-command} - {lists}. - - It considers everything as its argument until the next \\li command, until the - next \l {table-command} {\\endtable}, or \l {list-command} {\\endlist} - command. See \l {table-command} {\\table} and \l {list-command} {\\list} - for examples. - - If the command is used within a table, you can also specify - how many rows or columns the item should span. - - \code - / *! - \table - \header - \li {3,1} This header cell spans three columns - but only one row. - \row - \li {2, 1} This table item spans two columns - but only one row - \li {1, 2} This table item spans only one column, - but two rows. - \row - \li A regular table item - \li A regular table item - \endtable - * / - \endcode - - QDoc renders this as: - - \raw HTML - <table align="center" cellpadding="2" cellspacing="1" - border="0"> - - <tr valign="top" bgcolor="#a2c511"> - <th colspan="3" rowspan=" 1"> - This header cell spans three columns, but only one row. - </th> - </tr> - - <tr valign="top" bgcolor="#d0d0d0"> - <td colspan="2" rowspan=" 1"> - This table item spans two columns, but only one row. - </td> - <td rowspan=" 2"> - This table item spans only one column, but two rows. - </td> - </tr> - - <tr valign="top" bgcolor="#c0c0c0"> - <td>A regular table item</td> - <td>A regular table item</td> - </tr> - - </table> - \endraw - - If not specified, the item will span one column and one row. - - See also \l {table-command} {\\table}, \l {header-command} - {\\header}, and \l {list-command} {\\list}. - -*/ - - -/*! - \page 11-qdoc-commands-specialcontent.html - \previouspage Tables and Lists - \contentspage QDoc Manual - \nextpage Miscellaneous - - \title Special Content - - The document contents commands identify parts of the documentation, - parts with a special rendering, conceptual meaning or - function. - - \target quotation-command - \section1 \\quotation - - The \\quotation and \\endquotation commands delimit a long quotation. - - The text in the delimited block is surrounded by - \b{<blockquote>} and \b{</blockquote>} in the html output, - e.g.: - - \code - / *! - Although the prospect of a significantly broader market is - good news for Firstlogic, the notion also posed some - challenges. Dave Dobson, director of technology for the La - Crosse, Wisconsin-based company, said: - - \quotation - As our solutions were being adopted into new - environments, we saw an escalating need for easier - integration with a wider range of enterprise - applications. - \endquotation - * / - \endcode - - The text in the \b{\\quotation} block will appear in the generated HTML as: - - \code - <blockquote> - <p>As our solutions were being adopted into new environments, - we saw an escalating need for easier integration with a wider - range of enterprise applications.</p> - </blockquote> - \endcode - - The built-in style sheet for most browsers will render the - contents of the <blockquote> tag with left and right - indentations. The example above would be rendered as: - - \quotation - As our solutions were being adopted into new - environments, we saw an escalating need for easier - integration with a wider range of enterprise - applications. - \endquotation - - But you can redefine the \b{<blockquote>} tag in your style.css file. - - \target footnote-command - \section1 \\footnote - - The \\footnote and \\endfootnote commands delimit a footnote. - - The footnote is rendered at the bottom of the page. - - \warning The \b{\\footnote} and \b{\\endfootnote} commands - have not been implemented. The footnote is rendered as a regular - HTML paragraph. - - \target note-command - \section1 \\note - - The \\note command defines a new paragraph preceded by "Note:" - in bold. - - \target tableofcontents-command - \section1 \\tableofcontents - - The \\tableofcontents command has been disabled because QDoc - now generates a table of contents automatically. - - The automatically generated table of contents appears in the upper - righthand corner of the page. - - \target brief-command - \section1 \\brief - - The \\brief command introduces a one-sentence description of a - class, namespace, header file, property, or variable. - - The brief text is used to introduce the documentation of the - associated object, and in lists generated using the \l - {generatelist-command} {\\generatelist} command and the \l - {annotatedlist-command} {\\annotatedlist} command. - - The \\brief command can be used in two significant different ways: - \l {brief class} {One for classes, namespaces and header files}, - and \l {brief-property} {one for properties and variables}. - - \target brief-property - - When the \\brief command is used to describe a property or a - variable, the brief text must be a sentence fragment starting with - "whether" (for a boolean property or variable) or starting with - "the" (for any other property or variable). - - For example the boolean QWidget::isWindow property: - - \code - / *! - \property QWidget::isActiveWindow - \brief Whether this widget's window is the active window - - The active window is the window that contains the widget that - has keyboard focus. - - When popup windows are visible, this property is \c true - for both the active window \e and the popup. - - \sa activateWindow(), QApplication::activeWindow() - * / - \endcode - - and the QWidget::geometry property - - \code - / *! - \property QWidget::geometry - \brief The geometry of the widget relative to its parent and - excluding the window frame - - When changing the geometry, the widget, if visible, - receives a move event (moveEvent()) and/or a resize - event (resizeEvent()) immediately. - - ... - - \sa frameGeometry(), rect(), ... - * / - \endcode - - QDoc renders this as: - - \quotation - \raw HTML - <h3>geometry : - <a href="http://doc.qt.io/qt-5/qrect.html">QRect</a> - </h3> - \endraw - - This property holds the geometry of the widget relative - to its parent and excluding the window frame. - - ... - - Access functions: - \list - \li \b {const QRect & geometry () const} - \li \b {void setGeometry ( int x, int y, int w, int h )} - \li \b {void setGeometry ( const QRect & )} - \endlist - - See also \l - {QWidget::frameGeometry()} {frameGeometry()}, \l - {QWidget::rect()} {rect()}, ... - \endquotation - - \target brief class - - When the \\brief command is used to describe a class, we recommend - using a complete sentence like this: - - \code - The <classname> class is|provides|contains|specifies... - \endcode - - \warning Do not repeat your detailed description with the same sentence as - the brief statement will be the first paragraph of the detailed - description. - - \code - / *! - \class PreviewWindow - \brief The PreviewWindow class is a custom widget - displaying the names of its currently set - window flags in a read-only text editor. - - The PreviewWindow class inherits QWidget. The widget - displays the names of its window flags set with the - setWindowFlags() function. It is also provided with a - QPushButton that closes the window. - - ... - - \sa QWidget - * / - \endcode - - QDoc renders this as: - - \quotation - \raw HTML - <h1>PreviewWindow Class Reference</h1> - \endraw - - The PreviewWindow class is a custom widget displaying - the names of its currently set window flags in a - read-only text editor. \l {preview window} {More...} - - \raw HTML - <h3>Properties</h3> - \endraw - - \list - \li 52 properties inherited from QWidget - \li 1 property inherited from QObject - \endlist - - \raw HTML - <h3>Public Functions</h3> - \endraw - - \list - \li \l {constructor} {PreviewWindow}(QWidget *parent = 0) - \li void \l {function} {setWindowFlags}(Qt::WindowFlags flags) - \endlist - - \list - \li 183 public functions inherited from QWidget - \li 28 public functions inherited from QObject - \endlist - - \raw HTML - <h3>Public Slots</h3> - \endraw - - \list - \li 17 public slots inherited from QWidget - \li 1 public slot inherited from QObject - \endlist - - \raw HTML - <h3>Additional Inherited Members</h3> - \endraw - - \list - \li 1 signal inherited from QWidget - \li 1 signal inherited from QObject - \li 4 static public members inherited from QWidget - \li 4 static public members inherited from QObject - \li 39 protected functions inherited from QWidget - \li 7 protected functions inherited from QObject - \endlist - - \target preview window - - \raw HTML - <hr /> - <h2>Detailed Description</h2> - \endraw - - The PreviewWindow class is a custom widget displaying - the names of its currently set window flags in a - read-only text editor. - - The PreviewWindow class inherits QWidget. The widget - displays the names of its window flags set with the \l - {function} {setWindowFlags()} function. It is also - provided with a QPushButton that closes the window. - - ... - - See also QWidget. - - \raw HTML - <hr /> - <h2>Member Function Documentation</h2> - \endraw - - \target constructor - \raw HTML - <h3>PreviewWindow(QWidget *parent = 0)</h3> - \endraw - - Constructs a preview window widget with \e parent. - - \target function - \raw HTML - <h3>setWindowFlags(Qt::WindowFlags flags)</h3> - \endraw - - Sets the widgets flags using the - QWidget::setWindowFlags() function. - - Then runs through the available window flags, - creating a text that contains the names of the flags - that matches the flags parameter, displaying - the text in the widgets text editor. - \endquotation - - Using \\brief in a \l{namespace-command}{\\namespace}: - - \code - / *! - \namespace Qt - - \brief The Qt namespace contains miscellaneous identifiers - used throughout the Qt library. - * / - \endcode - - Using \\brief in a \l{headerfile-command}{\\headerfile}: - - \code - / *! - \headerfile <QtGlobal> - \title Global Qt Declarations - - \brief The <QtGlobal> header file provides basic - declarations and is included by all other Qt headers. - - \sa <QtAlgorithms> - * / - \endcode - - See also \l{property-command} {\\property}, \l{class-command} - {\\class}, \l{namespace-command} {\\namespace} and - \l{headerfile-command} {\\headerfile}. - - \target legalese-command - \section1 \\legalese - - The \\legalese and \\endlegalese commands delimit a license agreement. - - In the generated HTML, the delimited text is surrounded by a \b - {<div class="LegaleseLeft">} and \b {</div>} tags. - - An example of a license agreement enclosed in \\legalese - and \\endlegalese: - - \code - / *! - \legalese - Copyright 1996 Daniel Dardailler. - - Permission to use, copy, modify, distribute, and sell this - software for any purpose is hereby granted without fee, - provided that the above copyright notice appear in all - copies and that both that copyright notice and this - permission notice appear in supporting documentation, and - that the name of Daniel Dardailler not be used in - advertising or publicity pertaining to distribution of the - software without specific, written prior permission. Daniel - Dardailler makes no representations about the suitability of - this software for any purpose. It is provided "as is" - without express or implied warranty. - - Modifications Copyright 1999 Matt Koss, under the same - license as above. - \endlegalese - * / - \endcode - - It will appear in the generated HTML as: - - \code - <div class="LegaleseLeft"> - <p>Copyright 1996 Daniel Dardailler.</p> - <p>Permission to use, copy, modify, distribute, and sell - this software for any purpose is hereby granted without fee, - provided that the above copyright notice appear in all - copies and that both that copyright notice and this - permission notice appear in supporting documentation, and - that the name of Daniel Dardailler not be used in - advertising or publicity pertaining to distribution of the - software without specific, written prior permission. Daniel - Dardailler makes no representations about the suitability of - this software for any purpose. It is provided "as is" - without express or implied warranty.</p> - - <p>Modifications Copyright 1999 Matt Koss, under the same - license as above.</p> - </div> - \endcode - - If the \\endlegalese command is omitted, QDoc will process the - \\legalese command but considers the rest of the documentation - page as the license agreement. - - Ideally, the license text is located with the licensed code. - - Elsewhere, the documentation identified as \e{\\legalese} command - can be accumulated using \l {generatelist-command} {\\generatelist} - with \c {legalese-command} as the argument. This is useful for - generating an overview of the license agreements associated with - the source code. - - \target warning-command - \section1 \\warning - - The \\warning command prepends "Warning:" to the command's - argument, in bold font. - - \code - / *! - Qt::HANDLE is a platform-specific handle type - for system objects. This is equivalent to - \c{void *} on Windows and OS X, and to - \c{unsigned long} on X11. - - \warning Using this type is not portable. - * / - \endcode - - QDoc renders this as: - - \quotation - Qt::HANDLE is a platform-specific handle type - for system objects. This is equivalent to - \c{void *} on Windows and OS X, and to - \c{unsigned long} on X11. - - \warning Using this type is not portable. - \endquotation - -*/ - - -/*! - \page 12-0-qdoc-commands-miscellaneous.html - \previouspage Special Content - \contentspage QDoc Manual - \nextpage Creating DITA Maps - - \title Miscellaneous - - These commands provide miscellaneous functions connected to the - visual appearance of the documentation, and to the process of - generating the documentation. - - \target annotatedlist-command - \section1 \\annotatedlist - - The \\annotatedlist command expands to a list of the members of a - group, each member listed with its \e {brief} text. Below is an - example from the Qt Reference Documentation: - - \code - / *! - ... - \section1 Drag and Drop Classes - - These classes deal with drag and drop and the necessary mime type - encoding and decoding. - - \annotatedlist draganddrop - - * / - \endcode - - This generates a list of all the C++ classes and/or QML types in - the \e{draganddrop} group. A C++ class or QML type in the - \e{draganddrop} group will have \e{\\ingroup draganddrop} in its - \e{\\class} or \e{\\qmltype} comment. - - - \target generatelist-command - \section1 \\generatelist - - The \\generatelist command expands to a list of links to the - documentation entities in a group. Below is an example from the Qt - Reference Documentation: - - \code - / *! - \page classes.html - \title All Classes - - For a shorter list that only includes the most - frequently used classes, see \l{Qt's Main Classes}. - - \generatelist classes Q - * / - \endcode - - This generates the \e {All Classes} page. The command accepts the - following arguments: - - \target table example - \section2 \c annotatedclasses - - The \c annotatedclasses argument provides a table containing the - names of all the classes, and a description of each class. Each - class name is a link to the class's reference documentation. For - example: - - \table - \row - \li QDial - \li Rounded range control (like a speedometer or potentiometer) - \row - \li QDialog - \li The base class of dialog windows - \row - \li QDir - \li Access to directory structures and their contents - \endtable - - A C++ class is documented with the \l {class-command} {\\class} - command. The annotation for the class is taken from the argument - of the class comment's \l {brief-command} {\\brief} command. - - \target list example - \section2 \c {classes <prefix>} - - The \c classes argument provides a complete alphabetical list of - the classes. The second argument, \c{<prefix>}, is the common - prefix for the class names. The class names will be sorted on the - character that follows the common prefix. e.g. The common prefix - for the Qt classes is \c Q. The common prefix argument is - optional. If no common prefix is provided, the class names will - be sorted on their first character. - - Each class name becomes a link to the class's reference - documentation. This command is used to generate the - \e {All Classes} page this way: - - \code - / *! - \page classes.html - \title All Classes - \ingroup classlists - - \brief Alphabetical list of classes. - - This is a list of all Qt classes. For a list of the classes - provided for compatibility with Qt3, see \l{Qt3 Support - Classes}. For classes that have been deprecated, see the - \l{Obsolete Classes} list. - - \generatelist classes Q - * / - \endcode - - A C++ class is documented with the \l {class-command} {\\class} - command. - - \section2 \c classesbymodule - - When this argument is used, a second argument is required, which - specifies the module whose classes are to be listed. QDoc - generates a table containing those classes. Each class is listed - with the text of its \l{brief-command} {\\brief} command. - - For example, this command can be used on a module page as follows: - - \code - / *! - \page phonon-module.html - \module Phonon - \title Phonon Module - \ingroup modules - - \brief Contains namespaces and classes for multimedia functionality. - - \generatelist{classesbymodule Phonon} - - ... - - * / - \endcode - - Each class that is a member of the specified module must be marked - with the \l {inmodule-command} {\\inmodule} command in its \\class - comment. - - \section2 \c qmltypesbymodule - - Similar to \c classesbymodule argument, but used for listing the - QML types from the QML module specified with the second argument. - - \note Support for this argument was introduced in QDoc 5.6. - - \section2 \c jstypesbymodule - - Similar to \c classesbymodule argument, but used for listing the - JavaScript types from the module specified with the second argument. - - \note Support for this argument was introduced in QDoc 5.6. - - \section2 \c compatclasses - - The \c compatclasses argument generates a list in alphabetical - order of the support classes. It is normally used only to - generate the Qt3 Support Classes page this way: - - \code - / *! - \page compatclasses.html - \title Qt3 Support Classes - \ingroup classlists - - \brief Enable porting of code from Qt 3 to Qt 4. - - These are the classes that Qt provides for compatibility with Qt - 3. Most of these are provided by the Qt3Support module. - - \generatelist compatclasses - * / - \endcode - - A support class is identified in the \\class comment with the \l - {compat-command} {\\compat} command. - - \section2 \c functionindex - - The \c functionindex argument provides a complete alphabetical - list of all the documented member functions. It is normally used - only to generate the \e {Qt function index} page - this way: - - \code - / *! - \page functions.html - \title All Functions - \ingroup funclists - - \brief All documented Qt functions listed alphabetically with a - link to where each one is declared. - - This is the list of all documented member functions and global - functions in the Qt API. Each function has a link to the - class or header file where it is declared and documented. - - \generatelist functionindex - * / - \endcode - - \section2 \c legalese - - The \c legalese argument tells QDoc to generate a complete list of - licenses in the documentation. Each license is identified using - the \l {legalese-command} {\\legalese} command. This command is - used to generate the \e {Qt license information} - page this way: - - \code - / *! - \page licenses.html - \title Other Licenses Used in Qt - \ingroup licensing - \brief Information about other licenses used for Qt components and third-party code. - - Qt contains some code that is not provided under the - \l{GNU General Public License (GPL)}, - \l{GNU Lesser General Public License (LGPL)} or the - \l{Qt Commercial Edition}{Qt Commercial License Agreement}, but rather under - specific licenses from the original authors. Some pieces of code were developed - by The Qt Company and others originated from third parties. - This page lists the licenses used, names the authors, and links - to the places where it is used. - - The Qt Company gratefully acknowledges these and other contributions - to Qt. We recommend that programs that use Qt also acknowledge - these contributions, and quote these license statements in an - appendix to the documentation. - - See also: \l{Licenses for Fonts Used in Qt for Embedded Linux} - - \generatelist legalese - * / - \endcode - - \section2 \c overviews - - The \c overviews argument is used to tell QDoc to generate a list - by concatenating the contents of all the \l {group-command} - {\\group} pages. Qt uses it to generate the \e {overviews} page - this way: - - \code - / *! - \page overviews.html - - \title All Overviews and HOWTOs - - \generatelist overviews - * / - \endcode - - \section2 \c related - - The \c related argument is used in combination with the \l - {group-command} {\\group} and \l {ingroup-command} {\\ingroup} - commands to list all the overviews related to a specified - group. For example, the page for the \e {Programming with Qt} - page is generated this way: - - \code - / *! - \group qt-basic-concepts - \title Programming with Qt - - \brief The basic architecture of the Qt cross-platform application and UI framework. - - Qt is a cross-platform application and UI framework for - writing web-enabled applications for desktop, mobile, and - embedded operating systems. This page contains links to - articles and overviews explaining key components and - techniuqes used in Qt development. - - \generatelist {related} - * / - \endcode - - Each page listed on this group page contains the command: - - \code - \ingroup qt-basic-concepts - \endcode - - \target if-command - \section1 \\if - - The \\if command and the corresponding \\endif command - enclose parts of a QDoc comment that only will be included if - the condition specified by the command's argument is true. - - The command reads the rest of the line and parses it as an C++ #if - statement. - - \code - / *! - \if defined(opensourceedition) - - \b{Note:} This edition is for the development of - \l{Qt Open Source Edition} {Free and Open Source} - software only; see \l{Qt Commercial Editions}. - - \endif - * / - \endcode - - This QDoc comment will only be rendered if the \c - opensourceedition preprocessor symbol is defined, and specified in - the \l {defines-variable} {defines} variable in the configuration - file to make QDoc process the code within #ifdef and #endif: - - \code - defines = opensourceedition - \endcode - - You can also define the preprocessor symbol manually on the - command line. For more information see the documentation of the \l - {defines-variable} {defines} variable. - - See also \l{endif-command} {\\endif}, \l{else-command} {\\else}, - \l {defines-variable} {defines} and \l {falsehoods-variable} - {falsehoods}. - - \target endif-command - \section1 \\endif - - The \\endif command and the corresponding \\if command - enclose parts of a QDoc comment that will be included if - the condition specified by the \l {if-command} {\\if} command's - argument is true. - - For more information, see the documentation of the \l {if-command} - {\\if} command. - - See also \l{if-command} {\\if}, \l{else-command} {\\else}, \l - {defines-variable} {defines} and \l {falsehoods-variable} - {falsehoods}. - - \target else-command - \section1 \\else - - The \\else command specifies an alternative if the - condition in the \l {if-command} {\\if} command is false. - - The \\else command can only be used within \l {if-command} - {\\if...\\endif} commands, but is useful when there is only two - alternatives. - - \code - / *! - The Qt 3 support library is provided to keep old - source code working. - - In addition to the \c Qt3Support classes, Qt 4 provides - compatibility functions when it's possible for an old - API to cohabit with the new one. - - \if !defined(QT3_SUPPORT) - \if defined(QT3_SUPPORTWARNINGS) - The compiler emits a warning when a - compatibility function is called. (This works - only with GCC 3.2+ and MSVC 7.) - \else - To use the Qt 3 support library, you need to - have the line QT += qt3support in your .pro - file (qmake automatically define the - QT3_SUPPORT symbol, turning on compatibility - function support). - - You can also define the symbol manually (for example, - if you don't want to link against the \c - Qt3Support library), or you can define \c - QT3_SUPPORT_WARNINGS instead, telling the - compiler to emit a warning when a compatibility - function is called. (This works only with GCC - 3.2+ and MSVC 7.) - \endif - \endif - * / - \endcode - - If the \c QT3_SUPPORT is defined, the comment will be rendered - like this: - - \quotation - The Qt 3 support library is provided to keep old source - code working. - - In addition to the Qt3Support classes, Qt 4 provides - compatibility functions when it's possible for an old - API to cohabit with the new one. - \endquotation - - If \c QT3_SUPPORT is not defined but \c QT3_SUPPORT_WARNINGS is - defined, the comment will be rendered like this: - - \quotation - The Qt 3 support library is provided to keep old source - code working. - - In addition to the Qt3Support classes, Qt 4 provides - compatibility functions when it's possible for an old - API to cohabit with the new one. - - The compiler emits a warning when a compatibility - function is called. (This works only with GCC 3.2+ and - MSVC 7.) - \endquotation - - If none of the symbols are defined, the comment will be - rendered as - - \quotation - The Qt 3 support library is provided to keep old - source code working. - - In addition to the \c Qt3Support classes, Qt 4 provides - compatibility functions when it's possible for an old - API to cohabit with the new one. - - To use the Qt 3 support library, you need to have the - line QT += qt3support in your .pro file (qmake - automatically define the QT3_SUPPORT symbol, turning on - compatibility function support). - - You can also define the symbol manually (e.g., if you - don't want to link against the \c Qt3Support library), - or you can define \c QT3_SUPPORT_WARNINGS instead, - telling the compiler to emit a warning when a - compatibility function is called. (This works only with - GCC 3.2+ and MSVC 7.) - \endquotation - - See also \l{if-command} {\\if}, \l{endif-command} {\\endif}, \l - {defines-variable} {defines} and \l {falsehoods-variable} - {falsehoods}. - - \target include-command - \section1 \\include - - The \\include command sends all or part of the file specified by - its first argument to the QDoc input stream to be processed as a - QDoc comment snippet. This command is often assigned the alias, - \e {input}, in the QDoc configuration file, for example \e {alias.include - = input}. - - The command is useful when some snippet of commands and text is to - be used in multiple places in the documentation. In that case, - move the snippet into a separate file and use the \\include - command wherever you want to insert the snippet into the - documentation. To prevent QDoc from reading the file as a - stand-alone page of documentation, we recommend that you use the - \c .qdocinc extension for these \e {include} files. - - The command can have either one or two arguments. The first - argument is always a file name. The contents of the file must be - QDoc input, in other words, a sequence of QDoc commands and text, but - without the enclosing QDoc comment \c{/}\c{*!} ... \c{*}\c{/} delimiters. - If you want to include the entire named file, don't use the second - argument. If you want to include only part of the file, see the - \l{2-argument-form}{two argument form} below. Here is an example - of the one argument form: - - \code - / *! - \page corefeatures.html - \title Core Features - - \include examples/signalandslots.qdocinc - \include examples/objectmodel.qdocinc - \include examples/layoutmanagement.qdocinc - * / - \endcode - - QDoc renders this page \l{corefeatures.html} {as shown here}. - - \target 2-argument-form} - \section2 \\include filename snippet-identifier - - It is a waste of time to make a separate \c .qdocinc file for every - QDoc include snippet you want to use in multiple places in the - documentation, especially given that you probably have to put the - copyright/license notice in every one of these files. So if you - have a large number of snippets to be included, you can put them all in a - single file if you want, and surround each one with: - \code - //! [snippet-id1] - - QDoc commands and text... - - //! [snippet-id1] - - //! [snippet-id2] - - More QDoc commands and text... - - //! [snippet-id2] - \endcode - - Then you can use the two-argument form of the command: - - \code - \input examples/signalandslots.qdocinc snippet-id2 - \input examples/objectmodel.qdocinc another-snippet-id - \endcode - - It works as expected. The sequence of QDoc commands and text found - between the two tags with the same name as the second argument is - sent to the QDoc input stream. You can even nest these snippets, - although it's not clear why you would want to do that. - - \target meta-command - \section1 \\meta - - The \\meta command is mainly used for including metadata in DITA - XML files. It is also used when generating HTML output for specifying - the \e maintainer(s) of a C++ class. - - The command has two arguments: the first argument is the name of the - metadata attribute, and the second argument is the - value for the attribute. Each argument should be enclosed in curly - brackets, as shown in this example: - - \code - / *! - \class QWidget - \brief The QWidget class is the base class of all user interface objects. - - \ingroup basicwidgets - - \meta {technology} {User Interface} - \meta {platform} {OS X 10.6} - \meta {platform} {Symbian} - \meta {platform} {MeeGo} - \meta {audience} {user} - \meta {audience} {programmer} - \meta {audience} {designer} - * / - \endcode - - When running QDoc to generate HTML, the example above will have no - effect on the generated output, but if you run QDoc to generate - DITA XML, the example will generate the following: - - \code - <?xml version="1.0" encoding="UTF-8"?> - <!DOCTYPE cxxClass PUBLIC "-//NOKIA//DTD DITA C++ API Class Reference Type v0.6.0//EN" "dtd/cxxClass.dtd"> - <!--qwidget.cpp--> - <cxxClass id="id-9a14268e-6b09-4eee-b940-21a00a0961df"> - <apiName>QWidget</apiName> - <shortdesc>the QWidget class is the base class of all user interface objects.</shortdesc> - <prolog> - <author>Qt Development Frameworks</author> - <publisher>Qt Project</publisher> - <copyright> - <copyryear year="2015"/> - <copyrholder>Qt Project</copyrholder> - </copyright> - <permissions view="all"/> - <metadata> - <audience type="designer"/> - <audience type="programmer"/> - <audience type="user"/> - <category>Class reference</category> - <prodinfo> - <prodname>Qt Reference Documentation</prodname> - <vrmlist> - <vrm version="4" release="7" modification="3"/> - </vrmlist> - <component>QtGui</component> - </prodinfo> - <othermeta name="platform" content="MeeGo"/> - <othermeta name="platform" content="Symbian"/> - <othermeta name="platform" content="OS X 10.6"/> - <othermeta name="technology" content="User Interface"/> - </metadata> - </prolog> - \endcode - - In the example output, several values have been set using default - values obtained from the QDoc configuration file. See \l - {Generating DITA XML Output} for details. - - \target noautolist-command - \section1 \\noautolist - - The \\noautolist command indicates that the annotated list of C++ - classes or QML types, which is automatically generated at the - bottom of the C++ or QML module page should be omitted, because - the classes or types have been listed manually. This command can - also be used with the \l {group-command}{\\group} command to omit - the list of group members, when they are listed manually. - - The command must stand on its own line. See \l {Qt Sensors QML Types} for - an example. The page is generated from \c {qtsensors5.qdoc}. There you will - find a qdoc comment containing the \c{\qmlmodule} command for the QtSensors - module. The same qdoc comment contains two \c {\annotated-list} commands to - list the QML types in two separate groups. The QML types have been divided - into these two groups because it makes more sense to list them this way than - it does to list them in a single alphabetical list. At the bottom of the - comment, \c {\noautolist} has been used to tell qdoc not to generate the - automatic annotated list. - - This command was introduced in QDoc 5.6. - - \target omit-command - \section1 \\omit - - The \\omit command and the corresponding \\endomit command - delimit parts of the documentation that you want QDoc to skip. For - example: - - \code - / *! - \table - \row - \li Basic Widgets - \li Basic GUI widgets such as buttons, comboboxes - and scrollbars. - - \omit - \row - \li Component Model - \li Interfaces and helper classes for the Qt - Component Model. - \endomit - - \row - \li Database Classes - \li Database related classes, e.g. for SQL databases. - \endtable - * / - \endcode - - QDoc renders this as: - - \raw HTML - <table align="center" cellpadding="2" - cellspacing="1" border="0"> - - <tr valign="top" bgcolor="#d0d0d0"> - <td>Basic Widgets</td> - <td>Basic GUI widgets such as buttons, comboboxes - and scrollbars.</td> - </tr> - - <tr valign="top" bgcolor="#c0c0c0"> - <td>Database Classes</td> - <td>Database related classes, e.g. for SQL databases.</td> - </tr> - </table> - \endraw - - \target raw-command - \section1 \\raw \span {class="newStuff"} {(avoid)} - - The \\raw command and the corresponding - \\endraw command delimit a block of raw mark-up language code. - - \note Avoid using this command if possible, because it generates - DITA XML code that causes problems. If you are trying to generate - special table or list behavior, try to get the behavior you want - using the \l {span-command} {\\span} and \l {div-command} {\\div} - commands in your \l {table-command} {\\table} or \l {list-command} - {\\list}. - - The command takes an argument specifying the code's format. - Currently, the only supported format is HTML. - - The \\raw command is useful if you want some special HTML effects - in your documentation. - - \code - / *! - Qt has some predefined QColor objects. - - \raw HTML - <style type="text/css" id="colorstyles"> - #color-blue { background-color: #0000ff; color: #ffffff } - #color-darkBlue { background-color: #000080; color: #ffffff } - #color-cyan { background-color: #00ffff; color: #000000 } - </style> - - <p> - <tt id="color-blue">Blue(#0000ff)</tt>, - <tt id="color-darkBlue">dark blue(#000080)</tt> and - <tt id="color-cyan">cyan(#00ffff)</tt>. - </p> - \endraw - * / - \endcode - - QDoc renders this as: - - \quotation - Qt has some predefined QColor objects. - - \raw HTML - <style type="text/css" id="colorstyles"> - #color-blue { background-color: #0000ff; color: #ffffff } - #color-darkBlue { background-color: #000080; color: #ffffff } - #color-cyan { background-color: #00ffff; color: #000000 } - </style> - - <p> - <tt id="color-blue">Blue(#0000ff)</tt>, - <tt id="color-darkBlue">dark blue(#000080)</tt> and - <tt id="color-cyan">cyan(#00ffff)</tt>. - </p> - \endraw - \endquotation - - \note But you can achieve the exact same thing using qdoc - commands. In this case, all you have to do is include the color - styles in your style.css file. Then you can write: - - \code - \tt {\span {id="color-blue"} {Blue(#0000ff)}}, - \tt {\span {id="color-darkBlue"} {dark blue(#000080)}} and - \tt {\span {id="color-cyan"} {cyan(#00ffff)}}. - \endcode - - ...which is rendered as: - - \tt {\span {id="color-blue"} {Blue(#0000ff)}}, - \tt {\span {id="color-darkBlue"} {dark blue(#000080)}} and - \tt {\span {id="color-cyan"} {cyan(#00ffff)}}. - - \target unicode-command - \section1 \\unicode - - The \\unicode command allows you to insert an arbitrary Unicode - character in the document. - - The command takes an argument specifying the character as an - integer. By default, base 10 is assumed, unless a '0x' or '0' - prefix is specified (for base 16 and 8, respectively). For - example: - - \code - O G\unicode{0xEA}nio e as Rosas - - \unicode 0xC0 table en famille avec 15 \unicode 0x20AC par jour - - \unicode 0x3A3 \e{a}\sub{\e{i}} - \endcode - - QDoc renders this as: - - \quotation - O G\unicode{0xEA}nio e as Rosas - - \unicode 0xC0 table en famille avec 15 \unicode 0x20AC par jour - - \unicode 0x3A3 \e{a}\sub{\e{i}} - \endquotation -*/ - diff --git a/src/tools/qdoc/doc/qdoc-manual-qdocconf.qdoc b/src/tools/qdoc/doc/qdoc-manual-qdocconf.qdoc deleted file mode 100644 index 69980c1e18..0000000000 --- a/src/tools/qdoc/doc/qdoc-manual-qdocconf.qdoc +++ /dev/null @@ -1,1714 +0,0 @@ -/**************************************************************************** -** -** Copyright (C) 2015 The Qt Company Ltd. -** Contact: http://www.qt.io/licensing/ -** -** This file is part of the documentation of the Qt Toolkit. -** -** $QT_BEGIN_LICENSE:FDL$ -** Commercial License Usage -** Licensees holding valid commercial Qt licenses may use this file in -** accordance with the commercial license agreement provided with the -** Software or, alternatively, in accordance with the terms contained in -** a written agreement between you and The Qt Company. For licensing terms -** and conditions see http://www.qt.io/terms-conditions. For further -** information use the contact form at http://www.qt.io/contact-us. -** -** GNU Free Documentation License Usage -** Alternatively, this file may be used under the terms of the GNU Free -** Documentation License version 1.3 as published by the Free Software -** Foundation and appearing in the file included in the packaging of -** this file. Please review the following information to ensure -** the GNU Free Documentation License version 1.3 requirements -** will be met: http://www.gnu.org/copyleft/fdl.html. -** $QT_END_LICENSE$ -** -****************************************************************************/ - -/*! - \page 21-0-qdoc-configuration.html - \previouspage Creating DITA Maps - \contentspage QDoc Manual - \nextpage Generic Configuration Variables - - \title The QDoc Configuration File - - Before running QDoc, you must create a QDoc configuration file to - tell QDoc where to find the source files that contain the QDoc - comments. The pathname to your configuration file is passed to - QDoc on the command line: - - \quotation - \c {/current/dir$ ../../bin/qdoc ./config.qdocconf} - \endquotation - - \section1 General Description - - The configuration file is a list of entries of the form \e - {"variable = value"}. Using the configuration variables, you can - define where QDoc should find the various source files, images and - examples, where to put generated documentation etc. The - configuration file can also contain directives like \c - include. For an example, see \l {minimal-qdocconf}{a minimal qdocconf file}. - - You can also use configuration variables to get QDoc to support - \l{Supporting Derived Projects} {derived projects}, i.e QDoc can - generate links in your project's documentation to elements in the - Qt online documentation. See the \l {Supporting Derived projects} - section. - - The value of a configuration variable can be set using either '=' - or '+='. The difference is that '=' overrides the previous value, - while '+=' adds a new value to the current one. - - Some configuration variables accept a list of strings as their - value, for example: - \l {sourcedirs-variable} - {\c{sourcedirs}}, while others accept only a single string. Double - quotes around a value string are optional, but including them allows - you to use special characters like '=' and ' \" ' within the value - string, for example: - - \badcode - HTML.postheader = "<a href=\"index.html\">Home</a>" - \endcode - - If an entry spans many lines, use a backslash at the end of every - line but the last: - - \badcode - sourcedirs = kernel \ - tools \ - widgets - \endcode - - \section1 Configuration Variables - - \section1 Variable List - - \list - \li \l {alias-variable} {alias} - \li \l {Cpp.ignoredirectives-variable} {Cpp.ignoredirectives} - \li \l {Cpp.ignoretokens-variable} {Cpp.ignoretokens} - \li \l {defines-variable} {defines} - \li \l {edition-variable} {edition} - \li \l {exampledirs-variable} {exampledirs} - \li \l {examples-variable} {examples} - \li \l {examples.fileextensions-variable} {examples.fileextensions} - \li \l {excludedirs-variable} {excludedirs} - \li \l {excludefiles-variable} {excludefiles} - \li \l {extraimages-variable} {extraimages} - \li \l {falsehoods-variable} {falsehoods} - \li \l {headerdirs-variable} {headerdirs} - \li \l {headers-variable} {headers} - \li \l {headers.fileextensions-variable} {headers.fileextensions} - \li \l {HTML.footer-variable} {HTML.footer} - \li \l {HTML.postheader-variable} {HTML.postheader} - \li \l {HTML.style-variable} {HTML.style} - \li \l {imagedirs-variable} {imagedirs} - \li \l {images-variable} {images} - \li \l {images.fileextensions-variable} {images.fileextensions} - \li \l {language-variable} {language} - \li \l {macro-variable} {macro} - \li \l {manifestmeta-variable} {manifestmeta} - \li \l {outputdir-variable} {outputdir} - \li \l {outputformats-variable} {outputformats} - \li \l {outputprefixes-variable} {outputprefixes} - \li \l {outputsuffixes-variable} {outputsuffixes} - \li \l {sourcedirs-variable} {sourcedirs} - \li \l {sources-variable} {sources} - \li \l {sources.fileextensions-variable} {sources.fileextensions} - \li \l {spurious-variable} {spurious} - \li \l {tabsize-variable} {tabsize} - \li \l {version-variable} {version} - \li \l {versionsym-variable} {versionsym} - \endlist - - \section1 Categories - - \list - \li \l {Generic Configuration Variables} - \li \l {C++ Specific Configuration Variables} - \li \l {HTML Specific Configuration Variables} - \endlist - - \section1 Configuration File Examples - - \list - \li A minimum configuration file: \l minimum.qdocconf - \li The Qt configuration file: \l qtgui.qdocconf - \endlist -*/ - - -/*! - \page 22-qdoc-configuration-generalvariables.html - \previouspage The QDoc Configuration File - \contentspage QDoc Manual - \nextpage Creating Help Project Files - - \title Generic Configuration Variables - - With the general QDoc configuration variables, you can define - where QDoc will find the various source files it needs to generate - the documentation, as well as the directory to put the generated - documentation. You can also do some minor manipulation of QDoc - itself, controlling its output and processing behavior. - - \target alias-variable - \section1 alias - - The \c alias variable renames a QDoc command. - - The general syntax is \tt {alias.\e{original-command-name} = \e - temporary-command-name}. - - \badcode - alias.e = i - \endcode - - This renames the built-in command \\e (italics) to be \\i. The \c - alias variable is often used for compatibility reasons. - - See also \l {macro-variable} {macro}. - - \target codeindent-variable - \section1 codeindent - - The \c codeindent variable specifies the level of indentation that - QDoc uses when writing code snippets. - - QDoc originally used a hard-coded value of four spaces for code - indentation to ensure that code snippets could be easily - distinguished from surrounding text. Since we can use \l{HTML - Specific Configuration Variables#HTML.stylesheets} {stylesheets} - to adjust the appearance of certain types of HTML elements, this - level of indentation is not always required. - - \target codeprefix-variable - \target codesuffix-variable - \section1 codeprefix, codesuffix - - The \c codeprefix and \c codesuffix variables specify a pair of - strings that each code snippet is enclosed in. - - \target defines-variable - \section1 defines - - The \c defines variable specifies the C++ preprocessor symbols - that QDoc will recognize and respond to. - - When a preprocessor symbol is specified using the \c defines - variable, you can also use the \l {if-command} {\\if} command to - enclose documentation that only will be included if the - preprocessor symbol is defined. - - The values of the variable are regular expressions (see QRegExp - for details). By default, no symbol is defined, meaning that code - protected with #ifdef...#endif will be ignored. - - \badcode - defines = Q_QDOC \ - QT_.*_SUPPORT \ - QT_.*_LIB \ - QT_COMPAT \ - QT3_SUPPORT \ - Q_OS_.* \ - Q_BYTE_ORDER \ - __cplusplus - \endcode - - This ensures that QDoc will process the code that requires these - symbols to be defined. For example: - - \code - #ifdef Q_OS_WIN - HDC getDC() const; - void releaseDC(HDC) const; - #endif - \endcode - - Since the Q_OS_.* regular expression (specified using the \c - defines variable) matches Q_OS_WIN, QDoc will process the code - within #ifdef and #endif in our example. - - You can also define preprocessor symbols manually on the command - line using the -D option. For example: - - \badcode - currentdirectory$ qdoc -Dconsoleedition qtgui.qdocconf - \endcode - - In this case the -D option ensures that the \c consoleedition - preprocessor symbol is defined when QDoc processes the source - files defined in the qtgui.qdocconf file. - - See also \l {falsehoods-variable} {falsehoods} and \l {if-command} {\\if}. - - \target edition-variable - \section1 edition - - The \c edition variable specifies which modules are included in - each edition of a package, and provides QDoc with information to - provide class lists for each edition. - - This feature is mostly used when providing documentation for Qt - packages. - - The \c edition variable is always used with a particular edition - name to define the modules for that edition: - - \badcode - edition.Console = QtCore QtNetwork QtSql QtXml - edition.Desktop = QtCore QtGui QtNetwork QtOpenGL QtSql QtXml \ - QtDesigner QtAssistant Qt3Support QAxContainer \ - QAxServer - edition.DesktopLight = QtCore QtGui Qt3SupportLight - \endcode - - In the above examples, the \c Console edition only includes the - contents of four modules. Only the classes from these modules will - be used when the \l{Miscellaneous#generatelist-command} - {generatelist} command is used to generate a list of classes for - this edition: - - \badcode - \generatelist{classesbyedition Console} - \endcode - - \target exampledirs-variable - \section1 exampledirs - - The \c exampledirs variable specifies the directories containing - the source code of the example files. - - The \l {examples-variable} {examples} and \l - {exampledirs-variable} {exampledirs} variables are used by the \l - {quotefromfile-command} {\\quotefromfile}, \l {quotefile-command} - {\\quotefile} and \l {example-command} {\\example} commands. If - both the \l {examples-variable} {examples} and \l - {exampledirs-variable} {exampledirs} variables are defined, QDoc - will search in both, first in \l {examples-variable} {examples} - then in \l {exampledirs-variable} {exampledirs}. - - QDoc will search through the directories in the specified order, - and accept the first matching file it finds. It will only search - in the specified directories, \e not in subdirectories. - - \badcode - exampledirs = $QTDIR/doc/src \ - $QTDIR/examples \ - $QTDIR \ - $QTDIR/qmake/examples - - examples = $QTDIR/examples/widgets/analogclock/analogclock.cpp - \endcode - - When processing - - \badcode - \quotefromfile widgets/calculator/calculator.cpp - \endcode - - QDoc will see if there is a file called \c calculator.cpp - listed as a value in the \l {examples-variable} {\c examples} variable. If - there isn't, it will search in the \c exampledirs variable, and - first see if there exists a file called - - \badcode - $QTDIR/doc/src/widgets/calculator/calculator.cpp - \endcode - - If it doesn't, QDoc will continue looking for a file called - - \badcode - $QTDIR/examples/widgets/calculator/calculator.cpp - \endcode - - and so forth. - - See also \l {examples-variable}{examples}. - - \target examples-variable - \section1 examples - - The \c examples variable allows you to specify individual example - files in addition to those located in the directories specified by - the \l {exampledirs-variable} {\c exampledirs} variable. - - The \c examples and \l {exampledirs-variable} {\c exampledirs} - variables are used by the \l {quotefromfile-command} - {\\quotefromfile}, \l {quotefile-command} {\\quotefile} and \l - {example-command} {\\example} commands. If both the \c examples and \l - {exampledirs-variable} {\c exampledirs} variables are defined, - QDoc will search in both, first in \c examples then in \l - {exampledirs-variable} {\c exampledirs}. - - QDoc will search through the values listed for the \c examples - variable, in the specified order, and accept the first one it - finds. - - For an extensive example, see the \l {exampledirs-variable} {\c - exampledirs} command. But note that if you know the file is listed - in the \c examples variable, you don't need to specify its path: - - \badcode - \quotefromfile calculator.cpp - \endcode - - See also \l {exampledirs-variable} {exampledirs}. - - \target examples.fileextensions-variable - \section1 examples.fileextensions - - The \c examples.fileextensions variable specifies the file - extensions that qdoc will look for when collecting example files - for display in the documentation. - - The default extensions are *.cpp, *.h, *.js, *.xq, *.svg, *.xml - and *.ui. - - The extensions are given as standard wildcard expressions. You - can add a file extension to the filter using '+='. For example: - - \badcode - examples.fileextensions += *.qrc - \endcode - - See also \l{headers.fileextensions}. - - \target excludedirs-variable - \section1 excludedirs - - The \c excludedirs variable is for listing directories that should \e{not} - be processed by qdoc, even if the same directories are included by the - \l {sourcedirs-variable} {sourcedirs} or \l {headerdirs-variable} {headerdirs} - variables. - - For example: - - \badcode - sourcedirs = src/corelib - excludedirs = src/corelib/tmp - \endcode - - When executed, QDoc will exclude the listed directories from - further consideration. Files in these directories will not be - read by qdoc. - - See also \l {excludefiles-variable} {excludefiles}. - - \target excludefiles-variable - \section1 excludefiles - - The \c excludefiles variable allows you to specify individual files - that should \e{not} be processed by qdoc. - - \badcode - excludefiles += $QT_CORE_SOURCES/../../src/widgets/kernel/qwidget.h \ - $QT_CORE_SOURCES/../../src/widgets/kernel/qwidget.cpp - \endcode - - If you include the above in your qdocconf file for qtbase, there - will be no qwidget.html generated for html and no qwidget.xml - generated for DITA XML. - - See also \l {excludedirs-variable} {excludedirs}. - - \target extraimages-variable - \section1 extraimages - - The \c extraimages variable tells QDoc to incorporate specific - images in the generated documentation. - - QDoc will not recognize images used within HTML (or any other - markup language). If we want the images to be copied from the - directories specified by \l {imagedirs} {\c imagedirs} (the images - in question must be located in these directories) to the output - directory, we must specify the images using the \c extraimages - variable. - - The general syntax is \tt {extraimages.\e{format} = \e image}. The - file extension is optional. - - For example, in \l qtgui.qdocconf we use a couple of images within - the HTML.postheader variable which value is pure HTML. For that - reason, these images are specified using the \c extraimages - variable: - - \badcode - extraimages.HTML = qt-logo - \endcode - - See also \l images and \l imagedirs. - - \target falsehoods-variable - \section1 falsehoods - - The \c falsehoods variable defines the truth value of specified - preprocessor symbols as false. - - If this variable is not set for a preprocessor symbol, QDoc - assumes its truth value is true. The exception is '0', which value - always is false. - - QDoc will recognize, and is able to evaluate, the following - preprocessor syntax: - - \code - #ifdef NOTYET - ... - #endif - - #if defined (NOTYET) - ... - #end if - \endcode - - However, faced with unknown syntax like - - \code - #if NOTYET - ... - #endif - \endcode - - QDoc will evaluate it as true by default, \e unless the - preprocessor symbol is specified within the \c falsehoods variable - entry: - - \badcode - falsehoods = NOTYET - \endcode - - See also \l defines. - - \target generateindex-variable - \section1 generateindex - - The \c generateindex variable contains a boolean value that - specifies whether to generate an index file when HTML - documentation is generated. - - By default, an index file is always generated with HTML - documentation, so this variable is typically only used when - disabling this feature (by setting the value to \c false) or when - enabling index generation for the WebXML output (by setting the - value to \c true). - - \target headerdirs-variable - \section1 headerdirs - - The \c headerdirs variable specifies the directories containing - the header files associated with the \c .cpp source files used in - the documentation. - - \badcode - headerdirs = $QTDIR/src \ - $QTDIR/extensions/activeqt \ - $QTDIR/extensions/motif \ - $QTDIR/tools/designer/src/lib/extension \ - $QTDIR/tools/designer/src/lib/sdk \ - $QTDIR/tools/designer/src/lib/uilib - \endcode - - When executed, the first thing QDoc will do is to read through the - headers specified in the \l {headers} {\c headers} variable, and - the ones located in the directories specified in the \c headerdir - variable (including all subdirectories), building an internal - structure of the classes and their functions. - - Then it will read through the sources specified in the \l - {sources-variable} {\c sources}, and the ones located in the - directories specified in the \l {sourcedirs-variable} {\c - sourcedirs} varible (including all subdirectories), merging the - documentation with the structure it retrieved from the header - files. - - If both the \c headers and \c headerdirs variables are defined, - QDoc will read through both, first \l {headers} {\c headers} then - \c headerdirs. - - In the specified directories, QDoc will only read the files with - the \c fileextensions specified in the \l {headers.fileextensions} - {\c headers.fileextensions} variable. The default extensions are - *.ch, *.h, *.h++, *.hh, *.hpp, and *.hxx". The files specified by - \l {headers} {\c headers} will be read without taking into account - their fileextensions. - - See also \l headers and \l headers.fileextensions. - - \target headers-variable - \section1 headers - - The \c headers variable allows you to specify individual header - files in addition to those located in the directories specified by - the \l {headerdirs} {\c headerdirs} variable. - - \badcode - headers = $QTDIR/src/gui/widgets/qlineedit.h \ - $QTDIR/src/gui/widgets/qpushbutton.h - \endcode - - When processing the \c headers variable, QDoc behaves in the same - way as it does when processing the \l {headerdirs} {\c headerdirs} - variable. For more information, see the \l {headerdirs} {\c - headerdirs} variable. - - See also \l headerdirs. - - \target headers.fileextensions-variable - \section1 headers.fileextensions - - The \c headers.fileextensions variable specify the extension used - by the headers. - - When processing the header files specified in the \l {headerdirs} - {\c headerdirs} variable, QDoc will only read the files with the - fileextensions specified in the \c headers.fileextensions - variable. In this way QDoc avoids spending time reading irrelevant - files. - - The default extensions are *.ch, *.h, *.h++, *.hh, *.hpp, and - *.hxx. - - The extensions are given as standard wildcard expressions. You - can add a file extension to the filter using '+='. For example: - - \badcode - header.fileextensions += *.H - \endcode - - \warning The above assignment may not work as described. - - See also \l headerdirs. - - \target imagedirs-variable - \section1 imagedirs - - The \c imagedirs variable specifies the directories containing the - images used in the documentation. - - The \l {images} {\c images} and \c imagedirs variables are used by - the \l {image-command} {\\image} and \l {inlineimage-command} - {\\inlineimage} commands. If both the \l {images} {\c images} and - \c imagedirs variables are defined, QDoc will search in both. First - in \l {images} {\c images}, then in \c imagedirs. - - QDoc will search through the directories in the specified order, - and accept the first matching file it finds. It will only search - in the specified directories, \e not in subdirectories. - - \badcode - imagedirs = $QTDIR/doc/src/images \ - $QTDIR/examples - - images = $QTDIR/doc/src/images/calculator-example.png - \endcode - - When processing - - \badcode - \image calculator-example.png - \endcode - - QDoc will then see if there is a file called - calculator-example.png listed as a value in the \c images - variable. If there isn't, it will search in the \c imagedirs - variable for: - - \badcode - $QTDIR/doc/src/images/calculator-example.png - \endcode - - If the file doesn't exist, QDoc will look for a file called - - \badcode - $QTDIR/examples/calculator-example.png - \endcode - - You can filter the images in an image directory using the \l - {images.fileextensions} {\c images.fileextensions} variable. The - general idea behind the \l {images.fileextensions} {\c images.fileextensions} - variable is to enable different image format for different output format. - - \warning The \l {images.fileextensions} {\c images.fileextensions} - variable's functionality is preliminary since QDoc at this point - only supports HTML. - - See also \l images and \l images.fileextensions. - - \target images-variable - \section1 images - - The \c images variable allows you to specify individual image - files in addition to those located in the directories specified by - the \l {imagedirs} {\c imagedirs} variable. - - \badcode - images = $QTDIR/doc/src/images/calculator-example.png - \endcode - - When processing the \c images variable, QDoc behaves in the same - way as it does when processing the \l {imagedirs} {\c imagedirs} - variable. For more information, see the \l {imagedirs} {\c - imagedirs} variable. - - See also \l imagedirs and \l images.fileextensions. - - \target images.fileextensions-variable - \section1 images.fileextensions - - The images.fileextensions variable filters the files within an - image directory. - - The variable's values (the extensions) are given as standard - wildcard expressions. The general syntax is: \tt - {images.fileextensions.\e{format} = *.\e{extension}}. - - The idea is to enable different image format for different output - format. - - \badcode - images.fileextensions.HTML = *.png - images.fileextensions.LOUT = *.eps - \endcode - - Then, when processing the \l {image-command} {\\image} and \l - {inlineimage-command} {\\inlineimage} commands, QDoc will only - search for files with extensions specified in the variable - containing the list of output formats. - - \warning This is only a preliminary functionality since QDoc at this - point only supports HTML. - - The default extensions for HTML are *.png, *.jpg, *.jpeg, and - *.gif. - - You can add a file extension to the filter using '+='. For - example: - - \badcode - images.fileextensions.HTML += *.eps - \endcode - - See also \l imagedirs and \l images. - - \target language-variable - \section1 language - - The \c language variable specifies the language of the source code - that is used in the documentation. - - Currently, C++ is the only language that QDoc understands. It is - also the default language, and doesn't really need to be - specified. However, a possible example of a language variable - statement: - - \badcode - language = Cpp - \endcode - - This identifies C++ as the language of the Qt source code. - - \target macro-variable - \section1 macro - - The \c macro variable is used to create your own simple QDoc - commands. The syntax is \tt {macro.\e{command} = \e{definition}}, - where the definition is written using QDoc syntax. - - A macro variable can be restricted for use in one type of output - generation. By appending \c {.HTML} to the macro name, for - example, the macro is only used when generating HTML output. By - appending \c {.DITAXML} to the macro name, the macro is only used - when generating DITA XML. - - \badcode - macro.gui = "\\b" - macro.raisedaster.HTML = "<sup>*</sup>" - \endcode - - The first macro defines the \\gui command to render its argument - using a bold font. The second macro defines the \\raisedaster - command to render a superscript asterisk, but only when generating - HTML. - - A macro can also take up to seven parameters: - - \badcode - macro.hello = "Hello \1!" - \endcode - - Parameters are passed to macros the same way as to other commands: - - \badcode - \hello World - \endcode - - See also \l {alias-variable} {alias}. - - \target manifestmeta-variable - \section1 manifestmeta - - The \c manifestmeta variable specifies additional meta-content - for the example manifest files generated by QDoc. - - See the \l{Manifest Meta Content} section for more information. - - \target naturallanguage-variable - \section1 naturallanguage - - The \c naturallanguage variable specifies the natural language - used for the documentation generated by qdoc. - - \badcode - naturallanguage = zh-Hans - \endcode - - By default, the natural language is \c en for compatibility with - legacy documentation. - - qdoc will add the natural language information to the HTML it - generates, using the \c lang and \c xml:lang attributes. - - See also \l {sourceencoding-variable} {sourceencoding}, - \l {outputencoding-variable} {outputencoding}, - \l{http://www.w3.org/TR/xhtml1/#C_7} - {C.7. The lang and xml:lang Attributes} and - \l{http://www.w3.org/TR/i18n-html-tech-lang/#ri20040429.113217290} - {Best Practice 13: Using Hans and Hant codes}. - - \target outputdir-variable - \section1 outputdir - - The \c outputdir variable specifies the directory where QDoc will - put the generated documentation. - - \badcode - outputdir = $QTDIR/doc/html - \endcode - - locates the generated Qt reference documentation in - $QTDIR/doc/html. For example, the documentation of the QWidget - class is located in - - \badcode - $QTDIR/doc/html/qwidget.html - \endcode - - The associated images will be put in an \c images subdirectory. - - \warning When running QDoc multiple times using the same output - directory, all files from the previous run will be lost. - - \target outputencoding-variable - \section1 outputencoding - - The \c outputencoding variable specifies the encoding used for the - documentation generated by qdoc. - - \badcode - outputencoding = UTF-8 - \endcode - - By default, the output encoding is \c ISO-8859-1 (Latin1) for - compatibility with legacy documentation. When generating - documentation for some languages, particularly non-European - languages, this is not sufficient and an encoding such as UTF-8 is - required. - - qdoc will encode HTML using this encoding and generate the correct - declarations to indicate to browsers which encoding is being - used. The \l naturallanguage configuration variable should also be - specified to provide browsers with a complete set of character - encoding and language information. - - See also \l outputencoding and \l naturallanguage. - - \target outputformats-variable - \section1 outputformats - - The \c outputformats variable specifies the format of - the generated documentation. - - Currently, QDoc only supports the HTML format. It is also - the default format, and doesn't need to be specified. - - \target outputprefixes-variable - \section1 outputprefixes - - The \c outputprefixes variable specifies a mapping between types of files - and the prefixes to prepend to the HTML file names in the generated - documentation. - - \badcode - outputprefixes = QML JS - outputprefixes.QML = uicomponents- - outputprefixes.JS = uicomponents- - \endcode - - By default, files containing the API documentation for QML types - are prefixed with "qml-", and javaScript types with "js-". In the - above example, the prefix \c "uicomponents" is used instead for - both. - - The output prefix is applied to file names for documentation on - QML and JS types. - - \target outputsuffixes-variable - \section1 outputsuffixes - - The \c outputsuffixes variable specifies a mapping between types of - files and module name suffixes to append to the HTML file names. - - \badcode - outputsuffixes = QML - outputsuffixes.QML = -tp - \endcode - - Given a QML module name \e FooBar and the default - \l {outputprefixes-variable}{output prefix} ("qml-"), the file name of - the generated HTML page for a QML type \e FooWidget would be - \c qml-foobar-tp-foowidget.html. - - By default, no suffix is used. The output suffix, if defined, is applied - to file names for documentation on QML and JS types, and their respective - module pages. - - The \c outputsuffixes variable was introduced in QDoc 5.6. - - \target qhp-variable - \section1 qhp - - The \c qhp variable is used to define the information to be - written out to Qt Help Project (\c{qhp}) files. - - See the \l{Creating Help Project Files} chapter for information - about this process. - - \target sourcedirs-variable - \section1 sourcedirs - - The \c sourcedirs variable specifies the directories containing - the \c .cpp or \c .qdoc files used in the documentation. - - \badcode - sourcedirs += .. \ - ../../../examples/gui/doc/src - \endcode - - When executed, the first thing QDoc will do is to read through the - headers specified in the \l {header-command} {\c header} variable, - and the ones located in the directories specified in the \c - headerdir variable (including all subdirectories), building an - internal structure of the classes and their functions. - - Then it will read through the sources specified in the \l - {sources} {\c sources}, and the ones located in the directories - specified in the \l {sourcedirs} {\c sourcedirs} variable - (including all subdirectories), merging the documentation with the - structure it retrieved from the header files. - - If both the \c sources and \c sourcedirs variables are defined, - QDoc will read through both, first \l {sources} {\c sources} then - \c sourcedirs. - - In the specified directories, QDoc will only read the files with - the \c fileextensions specified in the \l {sources.fileextensions} - {\c sources.fileextensions} variable. The default extensions are - *.c++, *.cc, *.cpp and *.cxx. The files specified by \l {sources} - {\c sources} will be read independent of their fileextensions. - - See also \l {sources-variable} {sources} and - \l {sources.fileextensions-variable} {sources.fileextensions}. - - \target sourceencoding-variable - \section1 sourceencoding - - The \c sourceencoding variable specifies the encoding used for the - source code and documentation. - - \badcode - sourceencoding = UTF-8 - \endcode - - By default, the source encoding is \c ISO-8859-1 (Latin1) for - compatibility with legacy documentation. For some languages, - particularly non-European languages, this is not sufficient and an - encoding such as UTF-8 is required. - - Although qdoc will use the encoding to read source and - documentation files, limitations of C++ compilers may prevent you - from using non-ASCII characters in source code comments. In cases - like these, it is possible to write API documentation completely - in documentation files. - - See also \l {naturallanguage-variable} {naturallanguage} and - \l {outputencoding-variable} {outputencoding}. - - \target sources-variable - \section1 sources - - The \c sources variable allows you to specify individual source - files in addition to those located in the directories specified by - the \l {sourcedirs-variable} {sourcedirs} variable. - - \badcode - sources = $QTDIR/src/gui/widgets/qlineedit.cpp \ - $QTDIR/src/gui/widgets/qpushbutton.cpp - \endcode - - When processing the \c sources variable, QDoc behaves in the same - way as it does when processing the \l {sourcedirs-variable} - {sourcedirs} variable. For more information, see the \l - {sourcedirs-variable} {sourcedirs} variable. - - See also \l {sourcedirs-variable} {sourcedirs}. - - \target sources.fileextensions-variable - \section1 sources.fileextensions - - The \c sources.fileextensions variable filters the files within a - source directory. - - When processing the source files specified in the \l {sourcedirs} - {\c sourcedirs} variable, QDoc will only read the files with the - fileextensions specified in the \c sources.fileextensions - variable. In this way QDoc avoid spending time reading irrelevant - files. - - The default extensions are *.c++, *.cc, *.cpp and *.cxx. - - The extensions are given as standard wildcard expressions. You - can add a file extension to the filter using '+='. For example: - - \badcode - sources.fileextensions += *.CC - \endcode - - \warning The above assignment may not work as described. - - See also \l {sourcedirs-variable} {sourcedirs} and \l - (sources-variable} {sources}. - - - \target spurious-variable - \section1 spurious - - The \c spurious variable excludes specified QDoc warnings from the - output. The warnings are specified using standard wildcard - expressions. - - \badcode - spurious = "Cannot find .*" \ - "Missing .*" - \endcode - - makes sure that warnings matching either of these expressions, - will not be part of the output when running QDoc. For example - would the following warning be omitted from the output: - - \badcode - src/opengl/qgl_mac.cpp:156: Missing parameter name - \endcode - - \target syntaxhighlighting - \section1 syntaxhighlighting - - The \c syntaxhighlighting variable specifies whether QDoc should - perform syntax highlighting on source code quoted in the - documentation it generates. - - \badcode - syntaxhighlighting = true - \endcode - - will enable syntax highlighting for all supported programming - languages. - - \target tabsize-variable - \section1 tabsize - - The \c tabsize variable defines the size of a tab character. - - \badcode - tabsize = 4 - \endcode - - will give the tab character the size of 4 spaces. The default - value of the variable is 8, and doesn't need to be specified. - - \target tagfile-variable - \section1 tagfile - - The \c tagfile variable specifies the Doxygen tag file to be - written when HTML is generated. - - \target version-variable - \section1 version - - The \c version variable specifies the version number of the - documented software. - - \badcode - version = 5.6.0 - \endcode - - When a version number is specified (using the \tt{\l version} or - \tt {\l versionsym} variables in a \c .qdocconf file), it is - accessible through the corresponding \\version command for use in - the documentation. - - \warning The \\version command's functionality is not fully - implemented; currently it only works within raw HTML code. - - See also \l versionsym. - - \target versionsym-variable - \section1 versionsym - - The \c versionsym variable specifies a C++ preprocessor symbol - that defines the version number of the documented software. - - \badcode - versionsym = QT_VERSION_STR - \endcode - - QT_VERSION_STR is defined in qglobal.h as follows - - \badcode - #define QT_VERSION_STR "4.0.1" - \endcode - - When a version number is specified (using the \tt{\l version} or - \tt {\l versionsym} variables in a \c .qdocconf file), it is - accessible through the corresponding \\version command for use in - the documentation. - - \warning The \\version command's functionality is not fully - implemented. Currently, it only works within raw HTML code. - - See also \l {version} {\\version}. -*/ - -/*! - \page 22-creating-help-project-files.html - \previouspage Generic Configuration Variables - \contentspage QDoc Manual - \nextpage C++ Specific Configuration Variables - - \title Creating Help Project Files - - \section1 Overview - - Qt Assistant uses a system for managing Qt documentation that requires - QDoc to generate inventories of files in a format that is similar to the - old style DCF format, but with additional features. - - QDoc allows configuration variables to be used to specify which pages are - to be used in each documentation set it generates. These are specified as - subvariables of the \c qhp variable with each set declared using a unique - identifier as a subvariable. - - For example, the configuration file for the Qt Quick documentation set - specifies information about the set as subvariables with the - \c{qhp.QtQuick} prefix: - - \badcode - qhp.projects = QtQuick - - qhp.QtQuick.file = qtquick.qhp - qhp.QtQuick.namespace = org.qt-project.qtquick.$QT_VERSION_TAG - qhp.QtQuick.virtualFolder = qtquick - qhp.QtQuick.indexTitle = Qt Quick - qhp.QtQuick.indexRoot = - - qhp.QtQuick.filterAttributes = qtquick $QT_VERSION qtrefdoc - qhp.QtQuick.customFilters.Qt.name = QtQuick $QT_VERSION - qhp.QtQuick.customFilters.Qt.filterAttributes = qtquick $QT_VERSION - - qhp.QtQuick.subprojects = qmltypes classes examples - - qhp.QtQuick.subprojects.qmltypes.title = QML Types - qhp.QtQuick.subprojects.qmltypes.indexTitle = Qt Quick QML Types - qhp.QtQuick.subprojects.qmltypes.selectors = qmlclass - qhp.QtQuick.subprojects.qmltypes.sortPages = true - - qhp.QtQuick.subprojects.classes.title = Classes - qhp.QtQuick.subprojects.classes.title = C++ Classes - qhp.QtQuick.subprojects.classes.indexTitle = Qt Quick C++ Classes - qhp.QtQuick.subprojects.classes.selectors = class fake:headerfile - qhp.QtQuick.subprojects.classes.sortPages = true - - qhp.QtQuick.subprojects.examples.title = Examples - qhp.QtQuick.subprojects.examples.indexTitle = Qt Quick Examples and Tutorials - qhp.QtQuick.subprojects.examples.selectors = fake:example - \endcode - - The documentation set may include one or more subprojects, which are added - to the table of contents under the name specified by \c title. The page - in the documentation referred to by the \c indexTitle acts as the index page - for the subproject. The page types to list under the subproject are specified - by \c selectors. The entries are alphabetically sorted if \c sortPages is set - to \c true. - - \section2 Using Selectors - - The \c selectors property specifies which page types are listed under the - table of contents entry for a subproject. Multiple selectors can be listed, - separated by whitespace. - - \table - \header \li Selector \li Description - \row \li \c namespace \li Namespaces - \row \li \c class \li Classes - \row \li \c qmltype \li QML Types - \row \li \c qmlclass \li Alias for \c qmltype. - \row \li \c module \li C++ Modules - \row \li \c qmlmodule \li QML Modules - \row \li \c doc[:subtype] \li Documentation pages with a specified - \c subtype. Multiple subtypes can be - listed as a comma-separated list. - \row \li \c fake \li Alias for \c doc. - \row \li \c group[:groupname] \li Documentation pages for members of a - specified group, as added using the - \l {ingroup-command} - {\\ingroup} groupname command. - Multiple group names can be listed as - a comma-separated list. - (Introduced in QDoc 5.6). - \endtable - - Available subtypes for the \c doc selector: - - \table - \header \li Subtype \li Description - \row \li \c example \li Examples - \row \li \c headerfile \li Header files - \row \li \c page \li Documentation pages defined with the - \l {page-command} {\\page} command. - \endtable - - For example, the following configuration would select example pages and - pages that include the \c {\ingroup tutorials} command: - - \badcode - qhp.QtQuickControls.subprojects = examples - qhp.QtQuickControls.subprojects.examples.title = Examples and Tutorials - qhp.QtQuickControls.subprojects.examples.indexTitle = Qt Quick Controls Examples - qhp.QtQuickControls.subprojects.examples.selectors = doc:example group:tutorials - qhp.QtQuickControls.subprojects.examples.sortPages = true - \endcode - - \section2 Adding Table of Contents - - To create a table of contents for a manual, create a subproject with - a \c{type} property and set it to \c{manual}. The page in the documentation - referred to by the \c{indexTitle} property must contain a list of links - that acts as a table of contents for the whole manual. QDoc will take the - information in this list and create a table of contents for the subproject. - - For example, the configuration file for Qt Creator defines only one - subproject for its documentation, including all the documentation in a - single manual: - - \badcode - qhp.QtCreator.subprojects = manual - qhp.QtCreator.subprojects.manual.title = Qt Creator Manual - qhp.QtCreator.subprojects.manual.indexTitle = Qt Creator Manual - qhp.QtCreator.subprojects.manual.type = manual - \endcode - - In this example, the page entitled "Qt Creator Manual" contains a nested - list of links to pages in the documentation which is duplicated in - Qt Assistant's Contents tab. -*/ - -/*! - \page 23-qdoc-configuration-cppvariables.html - \previouspage Creating Help Project Files - \contentspage QDoc Manual - \nextpage HTML Specific Configuration Variables - - \title C++ Specific Configuration Variables - - The C++ specific configuration variables are provided to avoid - erroneous documentation due to non-standard C++ constructs. - - \target Cpp.ignoredirectives-variable - \section1 Cpp.ignoredirectives - The \c Cpp.ignoredirectives variable makes QDoc ignore the - specified non-standard constructs, within C++ source code. - - If not specified by the \tt {\l Cpp.ignoretokens} or \tt {\l - Cpp.ignoredirectives} variables, non-standard constructs - (typically macros) can result in erroneous documentation. - - \badcode - Cpp.ignoredirectives = Q_DECLARE_INTERFACE \ - Q_DECLARE_OPERATORS_FOR_FLAGS \ - Q_DECLARE_PRIVATE \ - Q_DECLARE_PUBLIC \ - Q_DISABLE_COPY \ - Q_DUMMY_COMPARISON_OPERATOR \ - Q_ENUMS \ - Q_FLAGS \ - Q_INTERFACES \ - __attribute__ - \endcode - - makes sure that when processing the code below, for example, QDoc - will simply ignore the 'Q_ENUMS' and 'Q_FLAGS' expressions: - - \code - class Q_CORE_EXPORT Qt { - Q_OBJECT - Q_ENUMS(Orientation TextFormat BackgroundMode - DateFormat ScrollBarPolicy FocusPolicy - ContextMenuPolicy CaseSensitivity - LayoutDirection ArrowType) - Q_ENUMS(ToolButtonStyle) - Q_FLAGS(Alignment) - Q_FLAGS(Orientations) - Q_FLAGS(DockWidgetAreas) - - public: - ... - }; - \endcode - - The Q_OBJECT macro, however, is an exception: QDoc recognizes this - particular non-standard construct, so there is no need specifying - it using the \tt {\l Cpp.ignoredirectives} variable. - - Regarding the Q_CORE_EXPORT macro; see the documentation of the - \tt {\l Cpp.ignoretokens} variable. - - See also \l Cpp.ignoretokens. - - \target Cpp.ignoretokens-variable - \section1 Cpp.ignoretokens - - The \c Cpp.ignoretokens variable makes QDoc ignore the specified - non-standard constructs, within C++ source code. - - If not specified by the \tt {\l Cpp.ignoretokens} or \tt {\l - Cpp.ignoredirectives} variables, non-standard constructs - (typically macros) can result in erroneous documentation. - - In \l qtgui.qdocconf: - - \badcode - Cpp.ignoretokens = QAXFACTORY_EXPORT \ - QM_EXPORT_CANVAS \ - ... - Q_COMPAT_EXPORT \ - Q_CORE_EXPORT \ - Q_EXPLICIT \ - Q_EXPORT \ - ... - Q_XML_EXPORT - \endcode - - makes sure that when processing the code below, for example, QDoc - will simply ignore the 'Q_CORE_EXPORT' expression: - - \code - class Q_CORE_EXPORT Qt { - Q_OBJECT - Q_ENUMS(Orientation TextFormat BackgroundMode - DateFormat ScrollBarPolicy FocusPolicy - ContextMenuPolicy CaseSensitivity - LayoutDirection ArrowType) - Q_ENUMS(ToolButtonStyle) - Q_FLAGS(Alignment) - Q_FLAGS(Orientations) - Q_FLAGS(DockWidgetAreas) - public: - ... - }; - \endcode - - Regarding the Q_OBJECT, Q_ENUMS and Q_FLAGS macros; see the - documentation of the \tt {\l Cpp.ignoredirectives} variable. - - See also \l Cpp.ignoredirectives. -*/ - -/*! - \page 24-qdoc-configuration-htmlvariables.html - \previouspage C++ Specific Configuration Variables - \contentspage QDoc Manual - \nextpage Supporting Derived Projects - - \title HTML Specific Configuration Variables - - The HTML specific configuration variables define the generated - documentation's style, or define the contents of the - documentation's footer or postheader. The format of the variable - values are raw HTML. - - \target HTML.footer-variable - \section1 HTML.footer - - The \c HTML.footer variable defines the content of the generated - HTML documentation's footer. - - The footer is rendered at the bottom of the generated - documentation page. - - The variable's value is given as raw HTML code enclosed by - quotation marks. Note that if the value spans several lines, each - line needs to be enclosed by quotation marks. - - \badcode - HTML.footer = "<p /><address><hr /><div align=\"center\">\n" \ - ... - "</tr></table></div></address>" - \endcode - - \target HTML.postheader-variable - \section1 HTML.postheader - - The \c HTML.postheader variable defines the content of the - generated HTML documentation's postheader. - - The header is rendered at the top of the generated documentation - page. - - The variable's value is given as raw HTML enclosed by quotation - marks. Note that if the value spans several lines, each line needs - to be enclosed by quotation marks. - - \badcode - HTML.postheader = "<table border=\"0\"..." \ - ... - "<img src=\"images/qt-logo.png\" \ - "align=\"right\" width=\"203\" height=\"32\""\ - "border=\"0\" />" \ - "</td></tr>" \ - "</table>" - \endcode - - The complete variable entry in \l qtgui.qdocconf provides the - standard header of the \l {http://doc.qt.io/qt-5/qtgui-index.html} - {Qt GUI Documentation}. - - \target HTML.style-variable - \section1 HTML.style - - The HTML.style variable defines the style for - the generated HTML documentation. - - The variable's value is given as raw HTML enclosed by quotation - marks. Note that if the value spans several lines, each line needs - to be enclosed by quotation marks. - - \badcode - HTML.style = "h3.fn,span.fn" \ - "{ margin-left: 1cm; text-indent: -1cm; }\n" \ - "a:link { color: #004faf; text-decoration: none }\n" \ - "a:visited" \ - "{ color: #672967; text-decoration: none }\n" \ - "td.postheader { font-family: sans-serif }\n" \ - "tr.address { font-family: sans-serif }\n" \ - "body { background: #ffffff; color: black; }" - \endcode - - \target HTML.stylesheets-variable - \section1 HTML.stylesheets - - The HTML.stylesheets variable defines a list of stylesheets - to use for the generated HTML documentation. - - Using separate stylesheets for the documentation makes it easier - to customize and experiment with the style used once the contents - has been generated. Typically, it is only necessary to define a - single stylesheet for any set of documentation; for example: - - \badcode - HTML.stylesheets = classic.css - \endcode - - QDoc expects to find stylesheets in the directory containing the - \l qtgui.qdocconf file, and it will copy those specified to the output - directory alongside the HTML pages. - - \target HTML.tocdepth - \section1 HTML.tocdepth - - The HTML.tocdepth variable defines how many document sections are printed in - the table of contents. Setting tocdepth to \c 0 disables the table of - contents while not setting the variable prints all document sections. - -*/ - -/*! - \page 25-qdoc-configuration-derivedprojects.html - \previouspage HTML Specific Configuration Variables - \contentspage QDoc Manual - \nextpage Example Manifest Files - - \title Supporting Derived Projects - - Some configuration variables allow you to use QDoc to support - Qt-based projects. They allow your project to contain links to the - online Qt documentation, which means that QDoc will be able to - create links to the class reference documentation, without any - explicit linking command. - - \target description-variable - \section1 description - - The description variable holds a short description of the - associated project. - - See also \l project. - - \target indexes-variable - \section1 indexes - - The \c indexes variable lists the index files that will be used to - generate references. - - For example. to make a derived Qt project contain links to the Qt - Reference documentation, you need to specify the associated index - file: - - \badcode - indexes = $QTDIR/doc/html/qt.index - \endcode - - See also \l project and \l url. - - \target project-variable - \section1 project - - The \c project variable provides a name for the project associated - with the \c .qdocconf file. - - The project's name is used to form a file name for the associated - project's \e index file. - - \badcode - project = QtCreator - \endcode - - This will cause an index file called \c qtcreator.index to be - created. - - See also \l description and \l indexes. - - \target url-variable - \section1 url - - The \c url variable holds the base URL for the reference - documentation associated with the current project. - - The URL is stored in the generated index file for the - project. When we use the index on its own, QDoc will use this as - the base URL when constructing links to classes, functions, and - other things listed in the index. - - \badcode - project = Qt - description = Qt Reference Documentation - url = http://doc.qt.io/qt-4.8/ - - ... - \endcode - - This makes sure that whenever \c qt.index is used to generate - references to for example Qt classes, the base URL is \c - http://doc.qt.io/qt-4.8/. - - See also \l indexes. - - \target howto - \section1 How to Support Derived Projects - - This feature makes use of the comprehensive indexes generated by - QDoc when it creates the Qt reference documentation. - - For example, \l qtgui.qdocconf (the configuration file for Qt) - contains the following variable definitions: - - \badcode - project = Qt - description = Qt Reference Documentation - url = http://doc.qt.io/qt-4.8/ - - ... - \endcode - - The \l project variable name is used to form a file name for the - index file; in this case the \c qt.index file is created. The \l - url is stored in the index file. Afterwards, QDoc will use this - as the base URL when constructing links to classes, functions, - and other things listed in the index. - -*/ - -/*! - \page 26-qdoc-configuration-example-manifest-files.html - \previouspage Supporting Derived Projects - \contentspage QDoc Manual - - \title Example Manifest Files - - QDoc generates XML files that contain information about all documented - examples and demos. These files, named \c {examples-manifest.xml} and - \c {demos-manifest.xml}, are used by Qt Creator to present a list of - examples in its welcome screen and to link to their documentation. - - \section1 Manifest XML Structure - - A manifest file has the following structure: - - \badcode - <?xml version="1.0" encoding="UTF-8"?> - <instructionals module="QtGui"> - <examples> - <example - name="Analog Clock Window Example" - docUrl="qthelp://org.qt-project.qtgui.502/qtgui/analogclock.html" - projectPath="gui/analogclock/analogclock.pro" - imageUrl="qthelp://org.qt-project.qtgui.502/qtgui/images/analogclock-window-example.png"> - <description><![CDATA[The Analog Clock Window example shows how - to draw the contents of a custom window.]]></description> - <tags>analog,clock,window</tags> - <fileToOpen>gui/analogclock/main.cpp</fileToOpen> - </example> - ... - </examples> - </instructionals> - \endcode - - Each \c {<example>} element contains information about a name, - description, the location of the project file and documentation, - as well as a list of tags associated with the example. - - \target metacontent - \section1 Manifest Meta Content - - It is possible to augment the manifest files with additional - meta-content - that is, extra attributes and tags for selected - examples, using the \c manifestmeta configuration command. - - One use case for meta-content is highlighting a number of prominent - examples. Another is improving search functionality by adding - relevant keywords as tags for a certain category of examples. - - The examples for which meta-content is applied to is specified using - one or more filters. Matching examples to filters is done based on - names, with each example name prefixed with a module name and a - slash. Simple wildcard matching is supported; by using \c {*} at the - end it's possible to match multiple examples with a single string. - - Example: - - \badcode - manifestmeta.filters = highlighted sql webkit global - - manifestmeta.highlighted.names = "QtGui/Analog Clock Window Example" \ - "QtWidgets/Analog Clock Example" - manifestmeta.highlighted.attributes = isHighlighted:true - - manifestmeta.sql.names = "QtSql/*" - manifestmeta.sql.tags = database,sql - - manifestmeta.webkit.names = "QtWebKitExamples/*" - manifestmeta.webkit.tags = webkit - - manifestmeta.global.names = * - manifestmeta.global.tags = qt5 - \endcode - - Above, an \c isHighlighted attribute is added to two examples. If - the attribute value is omitted, QDoc uses the string \c {true} by - default. Extra tags are added for Qt WebKit and Qt SQL examples, and - another tag is applied to all examples by using just \c {*} as the - match string. -*/ -/*! - \page 21-3-qt-dita-xml-output.html - \previouspage minimum.qdocconf - \contentspage QDoc Manual - \nextpage QA Pages - - \title Generating DITA XML Output - - QDoc can generate \l {http://dita.xml.org} {DITA XML output}. - - In your configuration file, set your \c {outputformats} variable - to \c {DITAXML}, and send the output to an appropriate directory: - - \badcode - outputdir = $QTDIR/doc/ditaxml - outputformats = DITAXML - \endcode - - And include these macros in your configuration file to prevent - QDoc from doing some escaping that doesn't validate in XML: - - \badcode - macro.aacute.DITAXML = "á" - 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/tools/qdoc/doc/qdoc-manual-topiccmds.qdoc b/src/tools/qdoc/doc/qdoc-manual-topiccmds.qdoc deleted file mode 100644 index 1dfd031633..0000000000 --- a/src/tools/qdoc/doc/qdoc-manual-topiccmds.qdoc +++ /dev/null @@ -1,1594 +0,0 @@ -/**************************************************************************** -** -** Copyright (C) 2015 The Qt Company Ltd. -** Contact: http://www.qt.io/licensing/ -** -** This file is part of the documentation of the Qt Toolkit. -** -** $QT_BEGIN_LICENSE:FDL$ -** Commercial License Usage -** Licensees holding valid commercial Qt licenses may use this file in -** accordance with the commercial license agreement provided with the -** Software or, alternatively, in accordance with the terms contained in -** a written agreement between you and The Qt Company. For licensing terms -** and conditions see http://www.qt.io/terms-conditions. For further -** information use the contact form at http://www.qt.io/contact-us. -** -** GNU Free Documentation License Usage -** Alternatively, this file may be used under the terms of the GNU Free -** Documentation License version 1.3 as published by the Free Software -** Foundation and appearing in the file included in the packaging of -** this file. Please review the following information to ensure -** the GNU Free Documentation License version 1.3 requirements -** will be met: http://www.gnu.org/copyleft/fdl.html. -** $QT_END_LICENSE$ -** -****************************************************************************/ - -/*! - \page 13-qdoc-commands-topics.html - \previouspage Command Index - \contentspage QDoc Manual - \nextpage Context Commands - - \title Topic Commands - - A topic command tells QDoc which source code element is being - documented. Some topic commands allow you to create documentation - pages that aren't tied to any underlying source code element. - - When QDoc processes a QDoc comment, it tries to connect the - comment to an element in the source code by first looking for a - topic command that names the source code element. If there is no - topic command, QDoc tries to connect the comment to the source - code element that immediately follows the comment. If it can't do - either of these and if there is no topic command that indicates - the comment does not have an underlying source code element (e.g. - \l{page-command} {\\page}), then the comment is discarded. - - \target topic argument - - The name of the entity being documented is usually the only - argument for a topic command. Use the complete name. Sometimes - there can be a second parameter in the argument. See e.g. \l - {page-command} {\\page}. - - \code - \enum QComboBox::InsertPolicy - \endcode - - The \l {fn-command} {\\fn} command is a special case. For the \l - {fn-command} {\\fn} command, use the function's signature - including the class qualifier. - - \code - \fn void QGraphicsWidget::setWindowFlags(Qt::WindowFlags wFlags) - \endcode - - A topic command can appear anywhere in a comment but must stand - alone on its own line. It is good practice is to let the topic command - be the first line of the comment. If the argument spans several - lines, make sure that each line (except the last one) is ended - with a backslash. Moreover, QDoc counts parentheses, which means - that if it encounters a '(' it considers everything until the - closing ')' as its argument. - - If a topic command is repeated with different arguments, the - same documentation will appear for both the units. - - \code - / *! - \fn void PreviewWindow::setWindowFlags() - \fn void ControllerWindow::setWindowFlags() - - Sets the widgets flags using the QWidget::setWindowFlags() - function. - - Then runs through the available window flags, creating a text - that contains the names of the flags that matches the flags - parameter, displaying the text in the widgets text editor. - * / - \endcode - - The \c PreviewWindow::setWindowFlags() and \c - ControllerWindow::setWindowFlags() functions will get the same - documentation. - - \target class-command - \section1 \\class - - The \\class command is for documenting a C++ class. The argument - is the complete name of the class. The command tells QDoc that a - class is part of the public API, and lets you enter a detailed - description. - - \code - / *! - \class QMap::iterator - - \brief The QMap::iterator class provides an STL-style - non-const iterator for QMap and QMultiMap. - - QMap features both \l{STL-style iterators} and - \l{Java-style iterators}. The STL-style iterators ... - * / - \endcode - - The HTML documentation for the named class is written to a - \c{.html} file named from the class name, in lower case, and with - the double colon qualifier(s) replaced with '-'. For example, the - documentation for the \c QMap::Iterator class is written to \c - qmap-iterator.html. - - \target framework - - The file contains the class description from the \\class comment, - plus the documentation generated from QDoc comments for all the - class members: a list of the class's types, properties, - functions, signals, and slots. - - In addition to the detailed description of the class, the \\class - comment typically contains a \l {brief-command} {\\brief} command - and one or more \l{Markup Commands}. See the \\class command for - any of the Qt class for examples. Here is a very simple example: - - \code - / *! - \class PreviewWindow - \brief The PreviewWindow class is a custom widget. - displaying the names of its currently set - window flags in a read-only text editor. - - \ingroup miscellaneous - - The PreviewWindow class inherits QWidget. The widget - displays the names of its window flags set with the \l - {function} {setWindowFlags()} function. It is also - provided with a QPushButton that closes the window. - - ... - - \sa QWidget - * / - \endcode - - The way QDoc renders this \\class will depend a lot on your \c - {style.css} file, but the general outline of the class reference - page will look like this: - - \quotation - \raw HTML - <h1>PreviewWindow Class Reference</h1> - \endraw - - The PreviewWindow class is a custom widget displaying - the names of its currently set window flags in a - read-only text editor. \l {preview window} {More...} - - \raw HTML - <h3>Properties</h3> - \endraw - - \list - \li 52 properties inherited from QWidget - \li 1 property inherited from QObject - \endlist - - \raw HTML - <h3>Public Functions</h3> - \endraw - - \list - \li \l {constructor} {PreviewWindow}(QWidget *parent = 0) - \li void \l {function} {setWindowFlags}(Qt::WindowFlags flags) - \endlist - - \list - \li 183 public functions inherited from QWidget - \li 28 public functions inherited from QObject - \endlist - - \raw HTML - <h3>Public Slots</h3> - \endraw - - \list - \li 17 public slots inherited from QWidget - \li 1 public slot inherited from QObject - \endlist - - \raw HTML - <h3>Additional Inherited Members</h3> - \endraw - - \list - \li 1 signal inherited from QWidget - \li 1 signal inherited from QObject - \li 4 static public members inherited from QWidget - \li 4 static public members inherited from QObject - \li 39 protected functions inherited from QWidget - \li 7 protected functions inherited from QObject - \endlist - - \target preview window - - \raw HTML - <hr /> - <h2>Detailed Description</h2> - \endraw - - The PreviewWindow class is a custom widget displaying - the names of its currently set window flags in a - read-only text editor. - - The PreviewWindow class inherits QWidget. The widget - displays the names of its window flags set with the \l - {function} {setWindowFlags()} function. It is also - provided with a QPushButton that closes the window. - - ... - - See also QWidget. - - \raw HTML - <hr /> - <h2>Member Function Documentation</h2> - \endraw - - \target constructor - \raw HTML - <h3>PreviewWindow(QWidget *parent = 0)</h3> - \endraw - - Constructs a preview window widget with \e parent. - - \target function - \raw HTML - <h3>setWindowFlags(Qt::WindowFlags flags)</h3> - \endraw - - Sets the widgets flags using the - QWidget::setWindowFlags() function. - - Then runs through the available window flags, - creating a text that contains the names of the flags - that matches the flags parameter, displaying - the text in the widgets text editor. - \endquotation - - \target enum-command - \section1 \\enum - - The \\enum command is for documenting a C++ enum type. The - argument is the full name of the enum type. - - The enum values are documented in the \\enum comment using the \l - {value-command} {\\value} command. If an enum value is not - documented with \\value, QDoc emits a warning. These warnings can - be avoided using the \l {omitvalue-command} {\\omitvalue} command - to tell QDoc that an enum value should not be documented. The enum - documentation will be included on the class reference page, header - file page, or namespace page where the enum type is defined. For - example, consider the enum type \c {Corner} in the Qt namespace: - - \code - enum Corner { - TopLeftCorner = 0x00000, - TopRightCorner = 0x00001, - BottomLeftCorner = 0x00002, - BottomRightCorner = 0x00003 - #if defined(QT3_SUPPORT) && !defined(Q_MOC_RUN) - ,TopLeft = TopLeftCorner, - TopRight = TopRightCorner, - BottomLeft = BottomLeftCorner, - BottomRight = BottomRightCorner - #endif - }; - \endcode - - This enum can be cocumented this way: - - \code - / *! - \enum Qt::Corner - - This enum type specifies a corner in a rectangle: - - \value TopLeftCorner - The top-left corner of the rectangle. - \value TopRightCorner - The top-right corner of the rectangle. - \value BottomLeftCorner - The bottom-left corner of the rectangle. - \value BottomRightCorner - The bottom-right corner of the rectangle. - - \omitvalue TopLeft - \omitvalue TopRight - \omitvalue BottomLeft - \omitvalue BottomRight - * / - \endcode - - Note the inclusion of the namespace qualifier. QDoc will render - this enum type in \c {qt.html} like this: - - \quotation - \raw HTML - <h3 class="fn"><a name="Corner-enum"></a>enum Qt::Corner</h3> - - <p>This enum type specifies a corner in a rectangle:</p> - - <table border="1" cellpadding="2" cellspacing="1" width="100%"> - <tr> - <th width="25%">Constant</th> - <th width="15%">Value</th> - <th width="60%">Description</th> - </tr> - - <tr> - <td valign="top"><tt>Qt::TopLeftCorner</tt></td> - <td align="center" valign="top"><tt>0x00000</tt></td> - <td valign="top">The top-left corner of the rectangle.</td> - </tr> - - <tr> - <td valign="top"><tt>Qt::TopRightCorner</tt></td> - <td align="center" valign="top"><tt>0x00001</tt></td> - <td valign="top">The top-right corner of the rectangle.</td> - </tr> - - <tr> - <td valign="top"><tt>Qt::BottomLeftCorner</tt></td> - <td align="center" valign="top"><tt>0x00002</tt></td> - <td valign="top">The bottom-left corner of the rectangle.</td> - </tr> - - <tr> - <td valign="top"><tt>Qt::BottomRightCorner</tt></td> - <td align="center" valign="top"><tt>0x00003</tt></td> - <td valign="top">The bottom-right corner of the rectangle.</td> - </tr> - - </table> - \endraw - \endquotation - - See also \l {value-command} {\\value} and \l {omitvalue-command} {\\omitvalue}. - - \target example-command - \section1 \\example - - The \\example command is for documenting an example. The argument - is the example's path relative to omne of the paths listed in the - \l {exampledirs-variable} {exampledirs} variable in the QDoc - configuration file. - - The documentation page will be output to \c {path-to-example}.html. - QDoc will add a list of all the example's source files at the top - of the page. - - For example, if \l {exampledirs-variable} {exampledirs} contains - \c $QTDIR/examples/widgets/imageviewer, then - - \code - / *! - \example widgets/imageviewer - \title ImageViewer Example - \subtitle - - The example shows how to combine QLabel and QScrollArea - to display an image. - - ... - * / - \endcode - - QDoc renders this example in widgets-imageviewer.html: - - \quotation - \raw HTML - <center><h1>Image Viewer Example</h1></center> - \endraw - - Files: - \list - \li \l{http://doc.qt.io/qt-5/qtwidgets-widgets-imageviewer-imageviewer-cpp.html} - {widgets/imageviewer/imageviewer.cpp} - \li \l{http://doc.qt.io/qt-5/qtwidgets-widgets-imageviewer-imageviewer-h.html} - {widgets/imageviewer/imageviewer.h} - \li \l{http://doc.qt.io/qt-5/qtwidgets-widgets-imageviewer-main-cpp.html} - {widgets/imageviewer/main.cpp} - \endlist - - The example shows how to combine QLabel and QScrollArea - to display an image. - - ... - \endquotation - - \target externalpage-command - \section1 \\externalpage - - The \\externalpage command assigns a title to an external URL. - - \code - / *! - \externalpage http://doc.qt.io/ - \title Qt Documentation Site - * / - \endcode - - This allows you to include a link to the external page in your - documentation this way: - - \code - / *! - At the \l {Qt Documentation Site} you can find the latest - documentation for Qt, Qt Creator, the Qt SDK and much more. - * / - \endcode - - QDoc renders this as: - - \quotation - At the \l {http://doc.qt.io/}{Qt Documentation Site} - you can find the latest documentation for Qt, Qt Creator, the Qt SDK - and much more. - \endquotation - - To achieve the same result without using the \\externalpage - command, you would have to hard-code the address into your - documentation: - - \code - / *! - At the \l {http://doc.qt.io/}{Qt Documentation Site} - you can find the latest documentation for Qt, Qt Creator, the Qt SDK - and much more. - * / - \endcode - - The \\externalpage command makes it easier to maintain the - documentation. If the address changes, you only need to change the - argument of the \\externalpage command. - - \target fn-command - \section1 \\fn (function) - - The \\fn command is for documenting a function. The argument is - the function's signature, including its return type, const-ness, - and list of formal arguments with types. If the named function - doesn't exist, QDoc emits a warning. - - \note The \\fn command is QDoc's default command: when no - topic command can be found in a QDoc comment, QDoc tries to tie - the documentation to the following code as if it is the - documentation for a function. Hence, it is normally not necessary - to include this command when documenting a function, if the - function's QDoc comment is written immediately above the function - implementation in the \c .cpp file. But it must be present when - documenting an inline function in the \c .cpp file that is - implemented in the \c .h file. - - \code - / *! - \fn bool QToolBar::isAreaAllowed(Qt::ToolBarArea area) const - - Returns \c true if this toolbar is dockable in the given - \a area; otherwise returns \c false. - * / - \endcode - - QDoc renders this as: - - \quotation - \raw HTML - <h3>bool QToolBar::isAreaAllowed(Qt::ToolBarArea area) const - </h3> - \endraw - - Returns \c true if this toolbar is dockable in the given - \a area; otherwise returns \c false. - \endquotation - - See also \l {overload-command} {\\overload}. - - \target group-command - \section1 \\group - - The \\group command creates a separate page that lists the classes - belonging to the group. The argument is the group name. - - A class is included in a group by using the \l {ingroup-command} - {\\ingroup} command. Overview pages can also be related to a group - using the same command, but the list of overview pages must be - requested explicitly using the \l {generatelist-command} - {\\generatelist} command (see example below). - - The \\group command is typically followed by a \l {title-command} - {\\title} command and a short introduction to the group. The - HTML page for the group is written to a \c {.html} file put in - <lower-case>\e{group}.html. - - Each class name is listed as a link to the class reference page - followed by the text from the class's \l {brief-command} {\\brief} - texts. - - \code - / *! - \group io - - \title Input/Output and Networking - - These classes are used to handle input and output to - and from external devices, processes, files etc., as - well as manipulating files and directories. - * / - \endcode - - QDoc generates a group page in \c{io.html} that will look - like this: - - \quotation - \raw HTML - - <h1>Input/Output and Networking</h1> - - <p>These classes are used to handle input and output - to and from external devices, processes, files etc., as - well as manipulating files and directories.</p> - - <p> - <table width="100%"> - <tr valign="top" bgcolor="#e0e0e0"> - <td><b> - <a href="http://doc.qt.io/qt-5/qabstractsocket.html">QAbstractSocket</a> - </b></td> - <td> - The base functionality common to all socket types - </td></tr> - - <tr valign="top" bgcolor="#e0e0e0"> - <td><b> - <a href="http://doc.qt.io/qt-5/qbuffer.html">QBuffer</a> - </b></td> - <td> - QIODevice interface for a QByteArray - </td></tr> - - <tr valign="top" bgcolor="#e0e0e0"> - <td><b> - <a href="http://doc.qt.io/qt-5/qclipboard.html">QClipboard</a> - </b></td> - <td> - Access to the window system clipboard - </td></tr> - </table> - \endraw - \endquotation - - Note that overview pages related to the group, must be listed - explicitly using the \l {generatelist-command} {\\generatelist} - command with the \c related argument. - - \code - / *! - \group architecture - - \title Architecture - - These documents describe aspects of Qt's architecture - and design, including overviews of core Qt features and - technologies. - - \generatelist{related} - * / - \endcode - - See also \l {ingroup-command} {\\ingroup} and \l - {generatelist-command} {\\generatelist}. - - \target headerfile-command - \section1 \\headerfile - - The \\headerfile command is for documenting the global functions, - types and macros that are declared in a header file, but not in a - namespace. The argument is the name of the header file. The HTML - page is written to a \c {.html} file constructed from the header - file argument. - - The documentation for a function, type, or macro that is declared - in the header file being documented, is included in the header file - page using the \l {relates-command} {\\relates} command. - - If the argument doesn't exist as a header file, the \\headerfile - command creates a documentation page for the header file anyway. - - \code - / *! - \headerfile <QtAlgorithms> - - \title Generic Algorithms - - \brief The <QtAlgorithms> header file provides - generic template-based algorithms. - - Qt provides a number of global template functions in \c - <QtAlgorithms> that work on containers and perform - well-know algorithms. - * / - \endcode - - QDoc generates a header file page \c{qtalgorithms.html} that looks - like this: - - \quotation - \raw HTML - <center><h1><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/tools/qdoc/doc/qdoc-manual.qdoc b/src/tools/qdoc/doc/qdoc-manual.qdoc deleted file mode 100644 index a0e35c2e9c..0000000000 --- a/src/tools/qdoc/doc/qdoc-manual.qdoc +++ /dev/null @@ -1,78 +0,0 @@ -/**************************************************************************** -** -** Copyright (C) 2015 The Qt Company Ltd. -** Contact: http://www.qt.io/licensing/ -** -** This file is part of the documentation of the Qt Toolkit. -** -** $QT_BEGIN_LICENSE:FDL$ -** Commercial License Usage -** Licensees holding valid commercial Qt licenses may use this file in -** accordance with the commercial license agreement provided with the -** Software or, alternatively, in accordance with the terms contained in -** a written agreement between you and The Qt Company. For licensing terms -** and conditions see http://www.qt.io/terms-conditions. For further -** information use the contact form at http://www.qt.io/contact-us. -** -** GNU Free Documentation License Usage -** Alternatively, this file may be used under the terms of the GNU Free -** Documentation License version 1.3 as published by the Free Software -** Foundation and appearing in the file included in the packaging of -** this file. Please review the following information to ensure -** the GNU Free Documentation License version 1.3 requirements -** will be met: http://www.gnu.org/copyleft/fdl.html. -** $QT_END_LICENSE$ -** -****************************************************************************/ - -/*! - \page qdoc-index.html - \nextpage Introduction to QDoc - - \title QDoc Manual - - \list - \li \l {Introduction to QDoc} - \li \l {Getting Started with QDoc} - \li \l {Command Index} - \li \l {Topic Commands} - \li \l {Context Commands} - \list - \li \l {Document Navigation} - \li \l {Status} - \li \l {Thread Support} - \li \l {Relating Things} - \li \l {Grouping Things} - \li \l {Naming Things} - \endlist - \li \l{Markup Commands} - \list - \li \l {Text Markup} - \li \l {Document Structure} - \li \l {Including Code Inline} - \li \l {Including External Code} - \li \l {Creating Links} - \li \l {Including Images} - \li \l {Tables and Lists} - \li \l {Special Content} - \li \l {Miscellaneous} - \endlist - \li \l{Creating DITA Maps} - \li \l {The QDoc Configuration File} - \list - \li \l {Generic Configuration Variables} - \li \l {Creating Help Project Files} - \li \l {C++ Specific Configuration Variables} - \li \l {HTML Specific Configuration Variables} - \li \l {Supporting Derived Projects} - \li \l {Example Manifest Files} - \li \l {qtgui.qdocconf} - \li \l {minimum.qdocconf} - \li \l {Generating DITA XML Output} - \endlist - \li \l {QA Pages} - \endlist - -*/ - - diff --git a/src/tools/qdoc/doc/qdoc-minimum-qdocconf.qdoc b/src/tools/qdoc/doc/qdoc-minimum-qdocconf.qdoc deleted file mode 100644 index 1fcd23a0f8..0000000000 --- a/src/tools/qdoc/doc/qdoc-minimum-qdocconf.qdoc +++ /dev/null @@ -1,89 +0,0 @@ -/**************************************************************************** -** -** Copyright (C) 2015 The Qt Company Ltd. -** Contact: http://www.qt.io/licensing/ -** -** This file is part of the documentation of the Qt Toolkit. -** -** $QT_BEGIN_LICENSE:FDL$ -** Commercial License Usage -** Licensees holding valid commercial Qt licenses may use this file in -** accordance with the commercial license agreement provided with the -** Software or, alternatively, in accordance with the terms contained in -** a written agreement between you and The Qt Company. For licensing terms -** and conditions see http://www.qt.io/terms-conditions. For further -** information use the contact form at http://www.qt.io/contact-us. -** -** GNU Free Documentation License Usage -** Alternatively, this file may be used under the terms of the GNU Free -** Documentation License version 1.3 as published by the Free Software -** Foundation and appearing in the file included in the packaging of -** this file. Please review the following information to ensure -** the GNU Free Documentation License version 1.3 requirements -** will be met: http://www.gnu.org/copyleft/fdl.html. -** $QT_END_LICENSE$ -** -****************************************************************************/ -/*! -\page qdoc-minimum-qdocconf.html -\keyword minimal-qdocconf -\title A Minimal qdocconf File - -\brief Describes a minimal .qdocconf file - -Below you will find the full contents of qtgui.qdocconf. The subsequent section -will discuss every statement in the qdocconf file. - -Each line from the qdocconf file is first quoted. Below each statement you will -find the meaning. - -\badcode - include(compat.qdocconf) - outputdir = html - headerdirs = . - sourcedirs = . - exampledirs = . - imagedirs = ./images -\endcode - -\b Notes: - -\badcode - include(compat.qdocconf) -\endcode - -For compatibility with older versions of Qt, it is recommended -to include compat.qdocconf. - -\code - outputdir = html -\endcode - -QDoc will put the documentation generated in the html directory. - -\badcode - headerdirs = . -\endcode - -The header file associated with the \e .cpp source files can be found in the -current directory. - -\badcode - sourcedirs = . -\endcode - -The current directory is the directory containing the source files: the \e .cpp -and \e .qdoc files used in the documentation. - -\badcode - exampledirs = . -\endcode - -The source code of the example files can be found in the current directory. - -\badcode - imagedirs = ./images -\endcode - -The image files can be found in the underlying directory \c images. -*/ diff --git a/src/tools/qdoc/doc/qtgui-qdocconf.qdoc b/src/tools/qdoc/doc/qtgui-qdocconf.qdoc deleted file mode 100644 index d90584ff42..0000000000 --- a/src/tools/qdoc/doc/qtgui-qdocconf.qdoc +++ /dev/null @@ -1,299 +0,0 @@ -/**************************************************************************** -** -** Copyright (C) 2015 The Qt Company Ltd. -** Contact: http://www.qt.io/licensing/ -** -** This file is part of the documentation of the Qt Toolkit. -** -** $QT_BEGIN_LICENSE:FDL$ -** Commercial License Usage -** Licensees holding valid commercial Qt licenses may use this file in -** accordance with the commercial license agreement provided with the -** Software or, alternatively, in accordance with the terms contained in -** a written agreement between you and The Qt Company. For licensing terms -** and conditions see http://www.qt.io/terms-conditions. For further -** information use the contact form at http://www.qt.io/contact-us. -** -** GNU Free Documentation License Usage -** Alternatively, this file may be used under the terms of the GNU Free -** Documentation License version 1.3 as published by the Free Software -** Foundation and appearing in the file included in the packaging of -** this file. Please review the following information to ensure -** the GNU Free Documentation License version 1.3 requirements -** will be met: http://www.gnu.org/copyleft/fdl.html. -** $QT_END_LICENSE$ -** -****************************************************************************/ - -/*! - -\page qtgui-qdocconf.html -\title qtgui.qdocconf with Comments - -\brief A walkthrough of a typical qdocconf file. - -This document goes through a typical Qt 5 qdocconf file. The contents is taken from -Qt GUI's \e qtgui.qdocconf file. - -Below you will find the full contents of \c qtgui.qdocconf. The subsequent section will discuss -every statement in the qdocconf file. - -\badcode - include($QT_INSTALL_DOCS/global/qt-module-defaults.qdocconf) - - project = QtGui - description = Qt GUI Reference Documentation - url = http://doc.qt.io/qt-5 - version = $QT_VERSION - - examplesinstallpath = gui - - qhp.projects = QtGui - - qhp.QtGui.file = qtgui.qhp - qhp.QtGui.namespace = org.qt-project.qtgui.$QT_VERSION_TAG - qhp.QtGui.virtualFolder = qtgui - qhp.QtGui.indexTitle = Qt GUI - qhp.QtGui.indexRoot = - - qhp.QtGui.filterAttributes = qtgui $QT_VERSION qtrefdoc - qhp.QtGui.customFilters.Qt.name = Qtgui $QT_VERSION - qhp.QtGui.customFilters.Qt.filterAttributes = qtgui $QT_VERSION - - qhp.QtGui.subprojects = classes - qhp.QtGui.subprojects.classes.title = C++ Classes - qhp.QtGui.subprojects.classes.indexTitle = Qt GUI C++ Classes - qhp.QtGui.subprojects.classes.selectors = class fake:headerfile - qhp.QtGui.subprojects.classes.sortPages = true - - tagfile = ../../../doc/qtgui/qtgui.tags - - depends += \ - qtcore \ - qtnetwork \ - qtopengl \ - qtsvg \ - qtqml \ - qtquick \ - qtwidgets \ - qtdoc - - headerdirs += .. - - sourcedirs += .. \ - ../../../examples/gui/doc/src - - excludedirs = ../../../examples/gui/doc/src/tmp - - exampledirs += ../../../examples/gui \ - snippets - - imagedirs += images \ - ../../../examples/gui/doc/images \ - ../../../doc/src/images \ -\endcode - -\title Qtgui.qdocconf with notes - -\badcode - include($QT_INSTALL_DOCS/global/qt-module-defaults.qdocconf) -\endcode - -QDoc inherits the default templates, macros, and settings from the directory -specified from the \c $QT_INSTALL_DOCS variable. \c qmake prints the value of -the variable. -\badcode - qmake -query -\endcode - -\b {See also}: \l {include}. - -\badcode - project = QtGui -\endcode - -The \c project variable sets the name of the QDoc build. This name is also -used to form the index file, which, in this case, will be \e qtgui.index. The -name of the index file doesn't adopt the uppercase letters of the project name. - -\b {See also}: \l {project}. - -\badcode - description = Qt GUI Reference Documentation -\endcode - -A short description of the project concerned. - -\badcode - url = http://doc.qt.io/qt-5 -\endcode - -The \c url variable holds the base url of the project. - -The URL is stored in the generated index file for the project. -QDoc will use this as the base URL when constructing external links -to content listed in the index. - -\note QDoc omits this value when the -installdir argument -is specified when running QDoc. - -\keyword examplesinstallpath - -\badcode - examplesinstallpath = gui -\endcode - -This \c examplesinstallpath variable indicates that the examples will be -installed in the \e gui directory under the parent examples directory -(for Qt, this is $QT_INSTALL_EXAMPLES). - -\note The examplepath variable has to match the example directory specified in - \c exampledirs. - -\b {See also}: \l {exampledirs}. - -\badcode - qhp.projects = QtGui - qhp.QtGui.file = qtgui.qhp -\endcode - -The following parameters are for creating a QHP file (\e .qhp). The -\e qhelpgenerator program can convert the QHP file into a QCH file (\e .qch), -which can be opened in Qt Assistant or Qt Creator. - -\badcode - qhp.QtGui.namespace = org.qt-project.qtgui.$QT_VERSION_TAG -\endcode - -A unique identifier which enables QHelpEngine to retrieve the helpfile -from a given link. This namespace is also used as a base url for links -to the helpfile. - -\badcode - qhp.QtGui.virtualFolder = qtgui -\endcode - -Virtual folders group documentation together into a single location. A -virtual folder will become the root directory of all files referenced in -a compressed help file. - -When two manuals are located in the same virtual folder, it is possible to -refer to sections of the other manual using relative paths. The virtual -folder tag is mandatory and the folder must not contain any '/'. - -\badcode - qhp.QtGui.indexTitle = Qt GUI -\endcode - -This is the title of the page that has the contents. - -\badcode - qhp.QtGui.indexRoot = -\endcode - -Specifies the title of the root (namespace) page to generate the documentation for. -Typically defined as an empty string. - -\badcode - qhp.QtGui.filterAttributes = qtgui $QT_VERSION qtrefdoc - qhp.QtGui.customFilters.Qt.name = QtGui $QT_VERSION - qhp.QtGui.customFilters.Qt.filterAttributes = qtgui $QT_VERSION -\endcode - -The documentation set (one per QDoc project) can have any number of filter -attributes assigned to it. A filter attribute is an ordinary string which -can be freely chosen. Additionally, custom filters that reference above -attributes can be defined. Qt Assistant will display the name of the custom -filter in its \gui{Filtered by} drop-down list. Only the documentation sets -that have their filter attributes match the attributes of the selected -custom filter will be shown. - -\badcode - qhp.QtGui.subprojects = classes - qhp.QtGui.subprojects.classes.title = C++ Classes - qhp.QtGui.subprojects.classes.indexTitle = Qt GUI C++ Classes -\endcode -The subprojects specify the sections that are displayed in the table of contents -for this project. In this example, the subproject, which is displayed in -the Assistant's sidebar, is named "C++ Classes" and its index is the page -titled "QT GUI C++ Classes". - -\badcode - qhp.QtGui.subprojects.classes.selectors = class fake:headerfile -\endcode - -Lists all C++ classes and header files. - -See \l {Creating Help Project Files} for more information. - -\badcode - tagfile = ../../../doc/qtgui/qtgui.tags -\endcode - -This specifies the Doxygen tag file that needs to be written when the html is generated -by QDoc. - -\badcode -depends += \ - qtcore \ - qtnetwork \ - qtopengl \ - qtsvg \ - qtqml \ - qtquick \ - qtwidgets \ - qtdoc -\endcode - -Specifies the modules QDoc needs to load for generating output for Qt GUI. -QDoc loads the index files for all modules listed in the depends statement in -order to enable linking to pages in these modules. - -\badcode - headerdirs += .. -\endcode - -Add the parent directory to the list of directories containing the header files -associated with the \e .cpp source files. - -\badcode - sourcedirs += .. \ - ../../../examples/gui/doc/src -\endcode - -Add the specified directories to the list of directories containing the \e .cpp and -\e .qdoc files used in the documentation. - -\badcode - excludedirs = ../../../examples/gui/doc/src/tmp -\endcode - -The \c excludedirs variable is for listing directories that should not be processed -by qdoc, even if the same directories are included by the \c sourcedirs or \c headerdirs -variables. - -When executed, QDoc will ignore the directories listed. -\b {See also}: \l {excludefiles}. - -\badcode - exampledirs += ../../../examples/gui \ - snippets -\endcode -\b {See also}: \l {examples-variable}{examples}, \l {examplesinstallpath}. - -Add the two directories specified to the list of directories containing the source -code of the example files. - -If QDoc encounters both \c exampledirs and \c examples, it will look first in the -\c examples directory. QDoc will accept the first matching file it finds. QDoc will -search in the directories specified, not in their subdirectories. - -\badcode - imagedirs += images \ - ../../../examples/gui/doc/images \ - ../../../doc/src/images \ -\endcode - -Add the directories specified above to the list of directories where the images -can be found. -*/ |
