diff options
Diffstat (limited to 'src/qdoc/qdoc/doc')
35 files changed, 11080 insertions, 0 deletions
diff --git a/src/qdoc/qdoc/doc/config/qdoc.qdocconf b/src/qdoc/qdoc/doc/config/qdoc.qdocconf new file mode 100644 index 000000000..d886ff75b --- /dev/null +++ b/src/qdoc/qdoc/doc/config/qdoc.qdocconf @@ -0,0 +1,61 @@ +include($QT_INSTALL_DOCS/global/qt-module-defaults.qdocconf) +include($QT_INSTALL_DOCS/config/exampleurl-qttools.qdocconf) + +project = QDoc +description = QDoc Manual +version = $QT_VERSION +moduleheader = + +sourcedirs = .. + +exampledirs = .. \ + ../examples + +imagedirs = ../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.subprojects = overviews +qhp.QDoc.subprojects.overviews.title = Overviews +qhp.QDoc.subprojects.overviews.indexTitle = QDoc Manual +qhp.QDoc.subprojects.overviews.selectors = doc:page + +depends += \ + qtconcurrent \ + qtcore \ + qtdbus \ + qtdesigner \ + qtdoc \ + qthelp \ + qtgui \ + qtlinguist \ + qtnetwork \ + qtopengl \ + qtprintsupport \ + qtqml \ + qtquick \ + qtquickcontrols \ + qtsql \ + qtsvg \ + qttestlib \ + qtuitools \ + qtwidgets \ + qtxml + +ignorewords += QDoc + +navigation.landingpage = "QDoc Manual" + +# Convenience macros for creating links to QDoc commands & configuration variables +macro.qdoccmd = \\l{\1-command}{\\c{\\\1}} +macro.qdocvar = \\l{\1-variable}{\\c{\1}} diff --git a/src/qdoc/qdoc/doc/corefeatures.qdoc b/src/qdoc/qdoc/doc/corefeatures.qdoc new file mode 100644 index 000000000..e1edc3a92 --- /dev/null +++ b/src/qdoc/qdoc/doc/corefeatures.qdoc @@ -0,0 +1,11 @@ +// Copyright (C) 2023 The Qt Company Ltd. +// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only + +/*! + \page corefeatures.html + \title Core Features + + \include examples/signalandslots.qdocinc + \include examples/objectmodel.qdocinc + \include examples/layoutmanagement.qdocinc +*/ diff --git a/src/qdoc/qdoc/doc/examples/cpp.qdoc.sample b/src/qdoc/qdoc/doc/examples/cpp.qdoc.sample new file mode 100644 index 000000000..39c77f63c --- /dev/null +++ b/src/qdoc/qdoc/doc/examples/cpp.qdoc.sample @@ -0,0 +1,102 @@ +// Copyright (C) 2016 The Qt Company Ltd. +// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only + +//![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 omitted + + \sa QPixmapCache, QHash, QMap +*/ +//![class] + +//![function] +/*! + \fn QString &QString::remove(int position, int n) + + Removes \a n characters from the string, starting at the given \a + position index, and returns a reference to the string. + + If the specified \a position index is within the string, but \a + position + \a n is beyond the end of the string, the string is + truncated at the specified \a position. + + \snippet qstring/main.cpp 37 + + \sa insert(), replace() +*/ +QString &QString::remove(int pos, int len) +//! [function] + +//! [return] +/*! + Returns \c true if a QScroller object was already created for \a target; \c false otherwise. + + \sa scroller() +*/ +bool QScroller::hasScroller(QObject *target) +//! [return] + +//! [property] +/*! + \property QVariantAnimation::duration + \brief the duration of the animation + + This property describes the duration in milliseconds of the + animation. The default duration is 250 milliseconds. + + \sa QAbstractAnimation::duration() + */ +int QVariantAnimation::duration() const +//! [property] + +//! [signals] +/*! + \fn QAbstractTransition::triggered() + + This signal is emitted when the transition has been triggered (after + onTransition() has been called). +*/ +//! [signals] + +//! [enums] +/*! + \enum QSql::TableType + + This enum type describes types of SQL tables. + + \value Tables All the tables visible to the user. + \value SystemTables Internal tables used by the database. + \value Views All the views visible to the user. + \value AllTables All of the above. +*/ +//! [enums] + +//! [overloaded notifier] +/*! +\property QSpinBox::value +\brief the value of the spin box + +setValue() will emit valueChanged() if the new value is different +from the old one. The \l{QSpinBox::}{value} property has a second notifier +signal which includes the spin box's prefix and suffix. +*/ +//! [overloaded notifier] diff --git a/src/qdoc/qdoc/doc/examples/layoutmanagement.qdocinc b/src/qdoc/qdoc/doc/examples/layoutmanagement.qdocinc new file mode 100644 index 000000000..780b03c8f --- /dev/null +++ b/src/qdoc/qdoc/doc/examples/layoutmanagement.qdocinc @@ -0,0 +1,13 @@ +\section1 Layout Classes + +The Qt layout system provides a simple and powerful way of specifying +the layout of child widgets. + +By specifying the logical layout once, you get the following benefits: + +\list + \li Positioning of child widgets. + \li Sensible default sizes for windows. + \li Sensible minimum sizes for windows. + \li ... +\endlist diff --git a/src/qdoc/qdoc/doc/examples/main.cpp b/src/qdoc/qdoc/doc/examples/main.cpp new file mode 100644 index 000000000..0898fa5f7 --- /dev/null +++ b/src/qdoc/qdoc/doc/examples/main.cpp @@ -0,0 +1,16 @@ +// Copyright (C) 2016 The Qt Company Ltd. +// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR BSD-3-Clause + +#include <QApplication> +#include <QPushButton> + +int main(int argc, char *argv[]) +{ + QApplication app(argc, argv); + + QPushButton hello("Hello world!"); + hello.resize(100, 30); + + hello.show(); + return app.exec(); +} diff --git a/src/qdoc/qdoc/doc/examples/mainwindow.cpp b/src/qdoc/qdoc/doc/examples/mainwindow.cpp new file mode 100644 index 000000000..4e67f0a79 --- /dev/null +++ b/src/qdoc/qdoc/doc/examples/mainwindow.cpp @@ -0,0 +1,213 @@ +// Copyright (C) 2016 The Qt Company Ltd. +// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR BSD-3-Clause + +#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())); + + const QByteArrayList formats = QImageWriter::supportedImageFormats(); + for (const QByteArray &format : formats) { + 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); + saveAsMenu->addActions(saveAsActs); + + fileMenu = new QMenu(tr("&File"), this); + fileMenu->addAction(openAct); + fileMenu->addMenu(saveAsMenu); + fileMenu->addAction(printAct); + fileMenu->addSeparator(); + fileMenu->addAction(exitAct); + + optionMenu = new QMenu(tr("&Options"), this); + optionMenu->addAction(penColorAct); + optionMenu->addAction(penWidthAct); + optionMenu->addSeparator(); + optionMenu->addAction(clearScreenAct); + + helpMenu = new QMenu(tr("&Help"), this); + helpMenu->addAction(aboutAct); + helpMenu->addAction(aboutQtAct); + + menuBar()->addMenu(fileMenu); + menuBar()->addMenu(optionMenu); + menuBar()->addMenu(helpMenu); +} +//! [16] + +//! [17] +bool MainWindow::maybeSave() +//! [17] //! [18] +{ + if (scribbleArea->isModified()) { + QMessageBox::StandardButton ret; + ret = QMessageBox::warning(this, tr("Scribble"), + tr("The image has been modified.\n" + "Do you want to save your changes?"), + QMessageBox::Save | QMessageBox::Discard + | QMessageBox::Cancel); + if (ret == QMessageBox::Save) { + return saveFile("png"); + } else if (ret == QMessageBox::Cancel) { + return false; + } + } + return true; +} +//! [18] + +//! [19] +bool MainWindow::saveFile(const QByteArray &fileFormat) +//! [19] //! [20] +{ + QString initialPath = QDir::currentPath() + "/untitled." + fileFormat; + + QString fileName = QFileDialog::getSaveFileName(this, tr("Save As"), + initialPath, + tr("%1 Files (*.%2);;All Files (*)") + .arg(QString(fileFormat.toUpper())) + .arg(QString(fileFormat))); + if (fileName.isEmpty()) { + return false; + } else { + return scribbleArea->saveImage(fileName, fileFormat); + } +} +//! [20] diff --git a/src/qdoc/qdoc/doc/examples/minimum.qdocconf b/src/qdoc/qdoc/doc/examples/minimum.qdocconf new file mode 100644 index 000000000..fca0cd757 --- /dev/null +++ b/src/qdoc/qdoc/doc/examples/minimum.qdocconf @@ -0,0 +1,46 @@ +# QDoc is a tool that constantly evolves and there may be compatibility issues +# between old and new practices. For that reason, QDoc configuration files in +# the Qt Project includes compat.qdocconf: +#include(compat.qdocconf) + +# Give the documentation project a title: +project = My documentation project + +# Pass additional include paths to QDoc when parsing C++ code for documentation +# comments. +#includepaths += -I/some/path + +# QDoc needs a lists of file extensions to know which files to process in +# different situations. Uncomment the following include statement to get +# a pre-defined list of file extensions. +#include(fileextensions.qdocconf) + +# You can also specify file extensions manually. +headers.fileextensions = "*.h *.hpp" +sources.fileextensions = "*.cpp *.qml *.qdoc" + +# The outputdir variable specifies the directory where QDoc places the generated +# documentation. +outputdir = public + +# The headerdirs variable specifies the directories that contain the header +# files associated with the .cpp source files used in the documentation. +headerdirs = . + +# The sourcedirs variable specifies the directories that contain the .cpp or +# .qdoc files used in the documentation. +sourcedirs = . + +# The exampledirs variable specifies the directories that contain the source +# code of the example files. +exampledirs = ./examples + +# The imagedirs variable specifies the directories that contain images used in +# the documentation. +imagedirs = ./images + +# Set a warning limit. QDoc will exit with a non-zero exit code if it generates +# documentation warnings during the documentation build. Useful for tracking +# down documentation issues. +#warninglimit = 0 +#warninglimit.enabled = true diff --git a/src/qdoc/qdoc/doc/examples/objectmodel.qdocinc b/src/qdoc/qdoc/doc/examples/objectmodel.qdocinc new file mode 100644 index 000000000..02b5991c4 --- /dev/null +++ b/src/qdoc/qdoc/doc/examples/objectmodel.qdocinc @@ -0,0 +1,11 @@ +\section1 Qt Object Model + +The standard C++ object model provides very efficient runtime support +for the object paradigm. But its static nature is inflexibile in +certain problem domains. Graphical user interface programming is a +domain that requires both runtime efficiency and a high level of +flexibility. Qt provides this, by combining the speed of C++ with the +flexibility of the Qt Object Model. + +... + diff --git a/src/qdoc/qdoc/doc/examples/qml.qdoc.sample b/src/qdoc/qdoc/doc/examples/qml.qdoc.sample new file mode 100644 index 000000000..e2c1277d2 --- /dev/null +++ b/src/qdoc/qdoc/doc/examples/qml.qdoc.sample @@ -0,0 +1,90 @@ +// Copyright (C) 2016 The Qt Company Ltd. +// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only + +//![qmltype] + \qmltype TextEdit + \nativetype 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: +\value Font.Light +\value Font.Normal The default +\value Font.DemiBold +\value Font.Bold +\value Font.Black + +//! [enums] diff --git a/src/qdoc/qdoc/doc/examples/samples.qdocinc b/src/qdoc/qdoc/doc/examples/samples.qdocinc new file mode 100644 index 000000000..ea257852f --- /dev/null +++ b/src/qdoc/qdoc/doc/examples/samples.qdocinc @@ -0,0 +1,85 @@ +// Copyright (C) 2016 The Qt Company Ltd. +// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only + +//! [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. + + \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 (\c {qdoc}) + \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 + \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 + \title Overview of a Qt Technology + + \brief provides a technology never seen before. + +*/ +//! [sample-overview] + diff --git a/src/qdoc/qdoc/doc/examples/signalandslots.qdocinc b/src/qdoc/qdoc/doc/examples/signalandslots.qdocinc new file mode 100644 index 000000000..e14ede144 --- /dev/null +++ b/src/qdoc/qdoc/doc/examples/signalandslots.qdocinc @@ -0,0 +1,9 @@ +\section1 Signals and Slots + +Signals and slots are used for communication between objects. The signals and +slots mechanism is a central feature of Qt and probably the part that differs +most from the features provided by other frameworks. + +\section2 Introduction + +In GUI programming, when we ... diff --git a/src/qdoc/qdoc/doc/files/basicqt.qdoc.sample b/src/qdoc/qdoc/doc/files/basicqt.qdoc.sample new file mode 100644 index 000000000..1243387b2 --- /dev/null +++ b/src/qdoc/qdoc/doc/files/basicqt.qdoc.sample @@ -0,0 +1,64 @@ + /*! + \page basicqt.html + \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 + \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 + + \indexpage Index + \startpage Basic Qt + + \title Creating Dialogs + + This chapter will teach you how to create dialog boxes using Qt. +*/ + +/*! + \page index.html + + \indexpage Index + \startpage Basic Qt + + \title Index + + \list + \li \l {Basic Qt} + \li \l {Creating Dialogs} + \li \l {Getting Started} + \endlist +*/ + diff --git a/src/qdoc/qdoc/doc/files/compat.qdocconf b/src/qdoc/qdoc/doc/files/compat.qdocconf new file mode 100644 index 000000000..94e2ffd7d --- /dev/null +++ b/src/qdoc/qdoc/doc/files/compat.qdocconf @@ -0,0 +1,10 @@ +macro.0 = "\\\\0" +macro.b = "\\\\b" +macro.n = "\\\\n" +macro.r = "\\\\r" +macro.img = "\\image" +macro.endquote = "\\endquotation" +macro.relatesto = "\\relates" + +spurious = "Missing comma in .*" \ + "Missing pattern .*" diff --git a/src/qdoc/qdoc/doc/files/qtgui.qdocconf b/src/qdoc/qdoc/doc/files/qtgui.qdocconf new file mode 100644 index 000000000..ae873e83d --- /dev/null +++ b/src/qdoc/qdoc/doc/files/qtgui.qdocconf @@ -0,0 +1,45 @@ +include($QT_INSTALL_DOCS/global/qt-module-defaults.qdocconf) + +project = QtGui +description = Qt GUI Reference Documentation +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.subprojects = classes +qhp.QtGui.subprojects.classes.title = C++ Classes +qhp.QtGui.subprojects.classes.indexTitle = Qt GUI C++ Classes +qhp.QtGui.subprojects.classes.selectors = class fake:headerfile +qhp.QtGui.subprojects.classes.sortPages = true + +tagfile = ../../../doc/qtgui/qtgui.tags + +depends += \ + qtcore \ + qtnetwork \ + qtopengl \ + qtsvg \ + qtqml \ + qtquick \ + qtwidgets \ + qtdoc + +headerdirs += .. + +sourcedirs += .. \ + ../../../examples/gui/doc/src + +exampledirs += ../../../examples/gui \ + snippets + +imagedirs += images \ + ../../../examples/gui/doc/images \ + ../../../doc/src/images \ diff --git a/src/qdoc/qdoc/doc/images/happyguy.jpg b/src/qdoc/qdoc/doc/images/happyguy.jpg Binary files differnew file mode 100644 index 000000000..e8604793c --- /dev/null +++ b/src/qdoc/qdoc/doc/images/happyguy.jpg diff --git a/src/qdoc/qdoc/doc/images/link-to-qquickitem.png b/src/qdoc/qdoc/doc/images/link-to-qquickitem.png Binary files differnew file mode 100644 index 000000000..00e03c371 --- /dev/null +++ b/src/qdoc/qdoc/doc/images/link-to-qquickitem.png diff --git a/src/qdoc/qdoc/doc/images/links-to-broken-links.png b/src/qdoc/qdoc/doc/images/links-to-broken-links.png Binary files differnew file mode 100644 index 000000000..775143bd4 --- /dev/null +++ b/src/qdoc/qdoc/doc/images/links-to-broken-links.png diff --git a/src/qdoc/qdoc/doc/images/links-to-links.png b/src/qdoc/qdoc/doc/images/links-to-links.png Binary files differnew file mode 100644 index 000000000..9d2cc2fae --- /dev/null +++ b/src/qdoc/qdoc/doc/images/links-to-links.png diff --git a/src/qdoc/qdoc/doc/images/qt-logo.png b/src/qdoc/qdoc/doc/images/qt-logo.png Binary files differnew file mode 100644 index 000000000..835f5a3fe --- /dev/null +++ b/src/qdoc/qdoc/doc/images/qt-logo.png diff --git a/src/qdoc/qdoc/doc/images/training.jpg b/src/qdoc/qdoc/doc/images/training.jpg Binary files differnew file mode 100644 index 000000000..c2ce5c3b2 --- /dev/null +++ b/src/qdoc/qdoc/doc/images/training.jpg diff --git a/src/qdoc/qdoc/doc/images/windows-pushbutton.png b/src/qdoc/qdoc/doc/images/windows-pushbutton.png Binary files differnew file mode 100644 index 000000000..14528d680 --- /dev/null +++ b/src/qdoc/qdoc/doc/images/windows-pushbutton.png diff --git a/src/qdoc/qdoc/doc/images/windows-toolbutton.png b/src/qdoc/qdoc/doc/images/windows-toolbutton.png Binary files differnew file mode 100644 index 000000000..9ceb846ed --- /dev/null +++ b/src/qdoc/qdoc/doc/images/windows-toolbutton.png diff --git a/src/qdoc/qdoc/doc/qdoc-guide/qdoc-guide.qdoc b/src/qdoc/qdoc/doc/qdoc-guide/qdoc-guide.qdoc new file mode 100644 index 000000000..ff9ac808c --- /dev/null +++ b/src/qdoc/qdoc/doc/qdoc-guide/qdoc-guide.qdoc @@ -0,0 +1,670 @@ +// Copyright (C) 2020 The Qt Company Ltd. +// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only +/*! + \page qdoc-guide.html + \title Getting Started with QDoc + \nextpage Installing Clang for QDoc + + Qt uses QDoc to generate its documentation set into HTML and DocBook 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 + + \note \l{QDoc Manual}{QDoc} requires \l{http://clang.llvm.org}{Clang} + for parsing C++ header and source files, and for parsing the function + signatures in \l {fn-command} {\\fn} commands. See \l {Installing Clang for QDoc} + for details. + + 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{Installing Clang for QDoc} + \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{How to Resolve QDoc Warnings} + \endlist + +*/ + +/*! + \page qdoc-guide-conf.html + \title Creating QDoc Configuration Files + \previouspage Installing Clang for 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 DocBook XML + format. The main distinction between the two outputs is that HTML + documentation needs to have its HTML styling information in the + configuration files. DocBook documentation does not, and a separate process + can style the documentation in DocBook at a later time. DocBook 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. + + The main configuration variables are: + \badcode + HTML.postheader + HTML.postpostheader + HTML.postheader + HTML.footer + + HTML.headerstyles + HTML.stylesheets = template/style/style.css \ + template/style/style1.css + + HTML.scripts = template/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. In addition, QDoc will embed the string + in the \c postheader, \c footer, and related variables into each HTML file. + + The \l {Format-specific Configuration Variables} article outlines the usage + of each variable. + + \section2 QDoc Index Files + + Documentation projects can link to targets in other projects by specifying + a set of dependencies, or a set of direct paths to index file(s) this + project depends on. When QDoc generates documentation for a project, + it will also generate an \c .index file containing URLs to each linkable + entity in the project. Other projects can then define a dependency to the + index file in order to link to the documentation within that project. + + \b {See also}: \l {depends-variable}{depends} and + \l {indexes-variable}{indexes}. + + \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. + + \b {See also:} \l {macro-variable}{macro}. + + \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++ and QML. + + Within a QDoc comment, \c {//!} is used as a single-line documentation + comment; the comment itself and anything after it, until a newline, + is omitted from the generated output. + + 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 + + A QDoc comment can contain multiple topic commands in the same category, with + some restrictions. This way, it's possible to write a single comment that + documents all overloads of a function (using multiple \l {fn-command}{\\fn} + commands), or all properties in a QML property group (using + \l {qmlproperty-command}{\\qmlproperty} commands) in one go. + + If a QDoc comment contains multiple topic commands, it's possible to + provide additional \e {context commands} for individual topics in + follow-up comments: + + \badcode * + /\1! + \qmlproperty string Type::element.name + \qmlproperty int Type::element.id + + \brief Holds the element name and id. + \1/ + + /\1! + \qmlproperty int Type::element.id + \readonly + \1/ + \endcode + + Here, the follow-up comment marks the \e element.id property as read-only, + while \e element.name remains writable. + + \note A follow-up comment cannot contain any additional text, only + \l {writing-context}{context commands} that document the context of + the item. + + 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 attribution - used for documenting license attributions + \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 deprecated, then it should be marked as such + with the \l{deprecated-command}{\\deprecated} 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 deprecated functions when the documentation is + marked with \l{deprecated-command}{\\deprecated}. + + \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 How to Resolve QDoc Warnings + \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{qmlvaluetype-command}{\\qmlvaluetype} + \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{nativetype-command}{\\nativetype} + + \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{nativetype-command}{\\nativetype} 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}. + + \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. + + \badcode + readonly property int sampleReadOnlyProperty: 0 + \endcode + + 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. +*/ + + +/*! + \page qdoc-guide-clang.html + \title Installing Clang for QDoc + \previouspage Getting Started with QDoc + \nextpage Creating QDoc Configuration Files + + QDoc uses Clang when parsing C++ files as well as function signatures in + \l {fn-command} {\\fn} commands. Clang is part of + \l {https://llvm.org/}{the LLVM Compiler Infrastructure Project}. + If you're going to build QDoc from source, you must install + \l{http://clang.llvm.org}{Clang 15.0} or later. + + You can get Clang through various channels: + + \list + \li Qt provides the + \l{http://download.qt.io/development_releases/prebuilt/libclang/qt} + {prebuilt Clang packages} that are used for the Qt binaries in the + online installer. These let you link LLVM/Clang libraries statically, + but only support Release builds on Windows. + \li Linux distributions often provide a package called \e libclang-dev or + \e libclang-devel. Qt's build system instructs CMake to look for + \e {ClangConfig.cmake}, so make sure you install the package that + provides this file if you want to build QDoc. Running QDoc requires + only \e libclang. + \li On macOS, you can also use Homebrew's + \l{https://formulae.brew.sh/formula/llvm}{llvm formula}. + \endlist + + \note the prebuilt binaries from \l{http://releases.llvm.org/download.html} + cannot be used, as they miss certain components required by QDoc. + + If you install Clang in a custom location you need to tell CMake where + to find it. This can be done by specifying your LLVM installation path + using the \c LLVM_INSTALL_DIR environment variable when configuring Qt. + Alternatively, you can add the installation path to the \c CMAKE_PREFIX_PATH + CMake cache variable. +*/ diff --git a/src/qdoc/qdoc/doc/qdoc-guide/qtwritingstyle-cpp.qdoc b/src/qdoc/qdoc/doc/qdoc-guide/qtwritingstyle-cpp.qdoc new file mode 100644 index 000000000..43387ca7e --- /dev/null +++ b/src/qdoc/qdoc/doc/qdoc-guide/qtwritingstyle-cpp.qdoc @@ -0,0 +1,163 @@ +// Copyright (C) 2016 The Qt Company Ltd. +// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only + +/*! +\page qtwritingstyle-cpp.html +\title C++ Documentation Style +\brief Style guidelines for C++ documentation + +To generate the documentation, QDoc goes through the source code and generates +documentation for C++ types such as classes. QDoc then associates member +functions, properties, and other types to the appropriate class. + +Note that the documentation must be in the implementation files such as \c .cpp. + +\section1 Class Documentation + +Class documentation is generated using the \l{class-command}{\\class} command and +the name of the class as the first argument. + +\snippet examples/cpp.qdoc.sample class + +\l{Context commands} add information about the class, such as its module or +which version the class was added. + +Some common context commands are: +\list +\li \l{brief-command}{\\brief} - the class' brief description \b (mandatory) +\li \l{since-command}{\\since} - the version to which the class was added \b (mandatory) +\li \l{internal-command}{\\internal} - marks the class as internal. Internal +classes do not appear in the public API documentation. +\endlist + + +\section2 The Brief and Detailed Description + +The \e{brief description} is marked with the \l{brief-command}{\\brief} command +and it is for summarizing the purpose or functionality of the class. For C++ +classes, QDoc will take the class and create annotated information for the +class. The annotated information appears in lists and tables which display the +class. + +The C++ brief should start with: +\code +"The <C++ class name> class" +\endcode + +The \e{detailed description} section starts after the brief description. It +provides more information about the class. The detailed description may contain +images, snippet code, or links to other relevant documents. There +must be an empty line which separates the brief and detailed description. + +\section1 Member Functions + +Typically, function documentation immediately precedes the implementation of the +function in the \c .cpp file. For function documentation that is not immediately +above the implementation, the \l{fn-command}{\\fn} is needed. + +\snippet examples/cpp.qdoc.sample function + +The function documentation starts with a verb, indicating the operation the +function performs. This also applies to constructors and destructors. + +Some common verbs for function documentation: +\list +\li "Constructs..." - for constructors +\li "Destroys..." - for destructors +\li "Returns..." - for accessor functions +\endlist + +The function documentation must document: +\list +\li the return type +\li the parameters +\li the actions of the functions +\endlist + +The \l{a-command}{\\a} command marks the parameter in the documentation. +The return type documentation should link to the type documentation or be +marked with the \l{c-command}{\\c} command in the case of boolean values. + +\snippet examples/cpp.qdoc.sample return + +\section1 Properties + +The property documentation resides immediately above the read function's +implementation. The \l{writing-topic-commands}{topic command} for properties is +\l{property-command}{\\property}. + +\snippet examples/cpp.qdoc.sample property + +Property documentation usually starts with "This property...", but these are +alternate expressions: +\list +\li "This property holds..." +\li "This property describes..." +\li "This property represents..." +\li "Returns \c true when... and \c false when..." - for properties that +are read. +\li "Sets the..." - for properties that configure a type. +\endlist + +Property documentation must include: +\list +\li description and behavior of the property +\li accepted values for the property +\li the default value of the property +\endlist +Similar to \l{Member Functions}{functions}, the default type may be linked +or marked with the \c{\c} command. + +An example of a value range style is: +\quotation +The values range from 0.0 (no blur) to maximumRadius (maximum blur). By default, the property is set to 0.0 (no blur). +\endquotation + +\section1 Signals, Notifiers, and Slots +The \l{writing-topic-commands}{topic command} for signals, notifiers, and slots +is \l{fn-command}{\\fn}. Signal documentation state when they are triggered +or emitted. + +\snippet examples/cpp.qdoc.sample signals + +Signal documentation typically begin with "This signal is triggered when...". +Here are alternate styles: +\list +\li "This signal is triggered when..." +\li "Triggered when..." +\li "Emitted when..." +\endlist + +For slots or notifiers, the condition when they are executed or triggered by +a signal should be documented. +\list +\li "Executed when..." +\li "This slot is executed when..." +\endlist + +For properties that have overloaded signals, QDoc groups the overloaded +notifiers together. To refer to a specific version of a notifier or signal, +simply refer to the property and mention that there are different versions of +the notifier. + +\snippet examples/cpp.qdoc.sample overloaded notifier + +\section1 Enums, Namespaces, and Other Types + +Enums, namespaces, and macros have a \l{writing-topic-commands}{topic command} for their documentation: +\list +\li \l{enum-command}{\\enum} +\li \l{typedef-command}{\\typedef} +\li \l{macro-command}{\\macro} +\endlist + +The language style for these types mention that they are an enum or a macro and +continues with the type description. + +For enumerations, the \l{value-command}{\\value} command is for listing the +values. QDoc creates a table of values for the enum. + +\snippet examples/cpp.qdoc.sample enums + +*/ + diff --git a/src/qdoc/qdoc/doc/qdoc-guide/qtwritingstyle-qml.qdoc b/src/qdoc/qdoc/doc/qdoc-guide/qtwritingstyle-qml.qdoc new file mode 100644 index 000000000..91d2094cb --- /dev/null +++ b/src/qdoc/qdoc/doc/qdoc-guide/qtwritingstyle-qml.qdoc @@ -0,0 +1,142 @@ +// Copyright (C) 2016 The Qt Company Ltd. +// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only + +/*! +\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{qmlvaluetype-command}{\\qmlvaluetype} +\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{nativetype-command}{\\nativetype} +\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{nativetype-command}{\\nativetype} command 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 QML 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, 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. Use the \l{value-command}{\\value} command to document +the enum values. Add the type name as a prefix to each value, separated by +a period (.), as QDoc does not do this automatically. + +\snippet examples/qml.qdoc.sample enums + +The QDoc comment lists the values of the enumeration. If the enumeration is +implemented in C++, the documentation may link to the corresponding C++ +enumeration. However, the QDoc comment should advise that the enumeration +is a C++ enumeration. + +*/ + diff --git a/src/qdoc/qdoc/doc/qdoc-manual-cmdindex.qdoc b/src/qdoc/qdoc/doc/qdoc-manual-cmdindex.qdoc new file mode 100644 index 000000000..773ec1cfb --- /dev/null +++ b/src/qdoc/qdoc/doc/qdoc-manual-cmdindex.qdoc @@ -0,0 +1,143 @@ +// Copyright (C) 2016 The Qt Company Ltd. +// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only + +/*! + \page 27-qdoc-commands-alphabetical.html + \previouspage Introduction to QDoc + \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 {attribution-command} {\\attribution} + \li \l {b-command} {\\b} + \li \l {badcode-command} {\\badcode} + \li \l {b-command} {\\bold} (deprecated, use \\b) + \li \l {br-command} {\\br} + \li \l {brief-command} {\\brief} + \li \l {c-command} {\\c} + \li \l {caption-command} {\\caption} + \li \l {class-command} {\\class} + \li \l {code-command} {\\code} + \li \l {codeline-command} {\\codeline} + \li \l {compares-command} {\\compares} + \li \l {compareswith-command} {\\compareswith} + \li \l {deprecated-command} {\\deprecated} + \li \l {default-command} {\\default} + \li \l {details-command} {\\details} + \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} (deprecated, use \\e) + \li \l {if-command} {\\if} + \li \l {image-command} {\\image} + \li \l {include-command} {\\include} + \li \l {ingroup-command} {\\ingroup} + \li \l {inheaderfile-command}{\\inheaderfile} + \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} (deprecated, use \\nativetype) + \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 {modulestate-command} {\\modulestate} + \li \l {namespace-command} {\\namespace} + \li \l {nativetype-command} {\\nativetype} + \li \l {nextpage-command} {\\nextpage} + \li \l {noautolist-command} {\\noautolist} + \li \l {nonreentrant-command} {\\nonreentrant} + \li \l {note-command} {\\note} + \li \l {li-command} {\\o} (deprecated, use \\li) + \li \l {omit-command} {\\omit} + \li \l {omitvalue-command} {\\omitvalue} + \li \l {overload-command} {\\overload} + \li \l {page-command} {\\page} + \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 {qml-command} {\\qml} + \li \l {qmlabstract-command} {\\qmlabstract} + \li \l {qmlattachedproperty-command} {\\qmlattachedproperty} + \li \l {qmlattachedsignal-command} {\\qmlattachedsignal} + \li \l {qmlvaluetype-command} {\\qmlvaluetype} + \li \l {qmlclass-command} {\\qmlclass} (deprecated, use \\qmltype) + \li \l {qmldefault-command} {\\qmldefault} + \li \qdoccmd qmlenumeratorsfrom + \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 {qtcmakepackage-command} {\\qtcmakepackage} + \li \l {qtcmaketargetitem-command} {\\qtcmaketargetitem} + \li \l {quotation-command} {\\quotation} + \li \l {quotefile-command} {\\quotefile} + \li \l {quotefromfile-command} {\\quotefromfile} + \li \l {raw-command} {\\raw} + \li \l {readonly-command} {\\readonly} + \li \l {reentrant-command} {\\reentrant} + \li \l {reimp-command} {\\reimp} + \li \l {relates-command} {\\relates} + \li \l {required-command} {\\required} + \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 {sincelist-command} {\\sincelist} + \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 \qdoccmd tm + \li \l {tt-command} {\\tt} + \li \l {typealias-command} {\\typealias} + \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} + \li \l {wrapper-command} {\\wrapper} + \endlist +*/ diff --git a/src/qdoc/qdoc/doc/qdoc-manual-contextcmds.qdoc b/src/qdoc/qdoc/doc/qdoc-manual-contextcmds.qdoc new file mode 100644 index 000000000..7c62c08bd --- /dev/null +++ b/src/qdoc/qdoc/doc/qdoc-manual-contextcmds.qdoc @@ -0,0 +1,1002 @@ +// Copyright (C) 2016 The Qt Company Ltd. +// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only + +/*! + \page 14-qdoc-commands-contextcommands.html + \previouspage Topic Commands + \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? + \li Which include statement is needed to use this class? + \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 {attribution-command} {\\attribution} + \li \l {compares-command}{\\compares} (Since QDoc 6.7) + \li \l {compareswith-command}{\\compareswith} (Since QDoc 6.7) + \li \l {default-command} {\\default} + \li \l {deprecated-command}{\\deprecated} + \li \l {ingroup-command}{\\ingroup} + \li \l {inheaderfile-command}{\\inheaderfile} + \li \l {inherits-command}{\\inherits} + \li \l {inmodule-command}{\\inmodule} + \li \l {internal-command}{\\internal} + \li \l {modulestate-command} {\\modulestate} (Since QDoc 6.5) + \li \l {nextpage-command}{\\nextpage} + \li \l {nonreentrant-command}{\\nonreentrant} + \li \l {overload-command}{\\overload} + \li \l {preliminary-command}{\\preliminary} + \li \l {previouspage-command}{\\previouspage} + \li \l {qmlabstract-command} {\\qmlabstract} + \li \l {qmldefault-command} {\\qmldefault} + \li \qdoccmd qmlenumeratorsfrom (Since QDoc 6.8) + \li \l {qtcmakepackage-command} {\\qtcmakepackage} + \li \l {qtcmaketargetitem-command} {\\qtcmaketargetitem} + \li \l {readonly-command} {\\readonly} + \li \l {reentrant-command}{\\reentrant} + \li \l {reimp-command}{\\reimp} + \li \l {relates-command}{\\relates} + \li \l {required-command} {\\required} + \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} + \li \l {wrapper-command}{\\wrapper} + \endlist + +*/ + +/*! + \page 15-qdoc-commands-navigation.html + \previouspage Context Commands + \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 + + The \l {startpage-command} {\\startpage} command creates a link to + the page the author wants as the first page of a multipage document. + + The link is included in the generated HTML source code but has no + visual effect on the documentation: + + \code + <head> + ... + <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. 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. +*/ + +/*! + \page 16-qdoc-commands-status.html + \previouspage Document Navigation + \nextpage Thread Support + + \title Status + + These commands are for indicating that a documented element has + some special status. The element could be marked \e deprecated, + that is, it's about to be made obsolete and no longer 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 attribution-command + \section1 \\attribution + + The \\attribution command marks a documented \qdoccmd page as license + attribution documentation. + + The \l {annotatedattributions} {\\generatelist annotatedattributions} + command generates an annotated list of all license attribution pages + in the documentation project. + + \target default-command + \section1 \\default + + The \\default command is used for documenting a default value for + a QML property. The command takes a single argument, which is + displayed in the documentation as the default value. + + \badcode * + /\1! + \qmlproperty real Item::x + \default 0.0 + \1/ + \endcode + + If the default value is a non-empty string, use quotes: + + \badcode * + /\1! + \qmlproperty string Item::state + \default "invalid" + \1/ + \endcode + + \target compares-command + \section2 \\compares + + Use the \c {\compares} command to describe the comparison results for the + documented C++ type when compared to itself. You must use this command in + conjunction with the \l {class-command}{\\class} command. + + \c {\compares} takes one of the following arguments: + + //! [comparison-categories] + \list + \li \c strong + \li \c partial + \li \c weak + \li \c equality + \endlist + + \c {strong}, \c {partial}, and \c {weak} relate to the ordering. + \c {equality} means that the type is only compared for equality. + //! [comparison-categories] + + This command was introduced to QDoc with Qt 6.7. + + See also \l {compareswith-command}{\\compareswith}. + + \target compareswith-command + \section1 \\compareswith + + Use the \c {\compareswith .. \endcompareswith} pair of commands to + describe the comparison results for the documented C++ type when + compared to other types. \c {\compareswith} takes two or more + arguments: a comparison category, followed by a type name, or a + space-separated list of type names. Any text lines between + \c {\compareswith} and \c {\endcompareswith} commands are + considered further details that apply to all types subject + to the comparison category argument. + + Types that have one or more space in their name, such as + \c{unsigned long}, should be enclosed in braces. + + For example: + + \badcode * + /\1! + ... + \compareswith strong int long {unsigned long} {unsigned int} char + ... + \endcompareswith + ... + \1/ + \endcode + + Argument enclosed in braces have their leading and trailing whitespaces + removed. + For example, \c{unsigned long} and \c{ unsigned long } are equivalent. + + The comparison category argument must be one of the following: + \include qdoc-manual-contextcmds.qdoc comparison-categories + + This command was introduced to QDoc with Qt 6.7. + + See also \l {compares-command}{\\compares}. + + \target qmldefault-command + \section1 \\qmldefault + + The \\qmldefault command is for marking a QML property as the + \l {default-properties} + {default property}. The word \c default is displayed in + the documentation of the property. + + \badcode * + /\1! + \qmlproperty list<Change> State::changes + This property holds the changes to apply for this state. + \qmldefault + + 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. + \1/ + \endcode + + See how QDoc renders this property on the reference page for the + \l {QtQuick::State::changes}{State} type. + + \target qmlenumeratorsfrom-command + \section1 \\qmlenenumeratorsfrom + + Use the \\qmlenumeratorsfrom command in a \qdoccmd qmlproperty topic + with a property type \e enumeration, to automatically replicate the + documentation for enumerators from a C++ \qdoccmd enum topic. + + The command takes a fully qualified C++ enum as an argument, + and generates a list of enumerators and their descriptions. + + \note The C++ enum must be documented in the same project; QDoc + cannot access its documentation if it's part of an external + documentation set that the current project \qdocvar depends + on. + + By default, each enumerator is prefixed with the type name the + property belongs to, with \c{.} as the separator. + + For example: + + \badcode * + /\1! + \qmlproperty enumeration QtMultimedia::Camera::error + \qmlenumeratorsfrom QCamera::Error + + //! Outputs documentation for 'Camera.NoError', 'Camera.CameraError' + \1/ + \endcode + + If the enumerators are registered to QML under a different type + name, this name (prefix) can be specified using the optional + argument in square brackets: + + \badcode + \qmlenumeratorsfrom [Errors] QCamera::Error + + //! Outputs documentation for 'Errors.NoError', 'Errors.CameraError' + \1/ + \endcode + + This command was introduced in QDoc 6.8. + + See also \qdoccmd {qmlproperty}, \qdoccmd {enum}, and \qdoccmd {value}. + + \target dontdocument-command + \section1 \\dontdocument + + The \\dontdocument command is only used in a dontdocument.qdoc file + for a particular module. This file specifies publically declared + classes or structs that are not meant to be documented. QDoc will + not print warnings about missing \\class comments for these classes + and structs. + + Below you will find the \\dontdocument command in the + dontdocument.qdoc for widgets: + + \badcode * + /\1! + \dontdocument (QTypeInfo QMetaTypeId) + \1/ + \endcode + + \target inheaderfile-command + \section1 \\inheaderfile + + The \\inheaderfile meta-command is used for overriding the include statement + generated for a C++ class, namespace, or header file reference documentation. + + By default, QDoc documents a \c {\class SomeClass} to be available with + a following include statement: + + \code + #include <SomeClass> + \endcode + + If the actual include statement differs from the default, this can be + documented as + + \badcode + \class SomeClass + \inheaderfile Tools/SomeClass + ... + \endcode + + See also \l {class-command}{\\class} and + \l {headerfile-command}{\\headerfile}. + + + \target obsolete-command + \section1 \\obsolete + The \\obsolete command is superceded by the \\deprecated command. + + This command is kept for backwards compatibility reasons only. + It may be removed in a future version of QDoc. Use the \\deprecated + command instead. + + See also \l {deprecated-command}{\\deprecated}. + + \target deprecated-command + \section1 \\deprecated + + The \\deprecated command is for indicating that a function is being + deprecated, and that it should no longer be used in new code. There + is no guarantee for how long it will remain in the library. + + The \\deprecated command takes two optional arguments: + \list + \li A version in square brackets (e.g. [6.2]). + \li A string with more information, for example a suggested + replacement. + \endlist + + When generating the reference documentation for a class, QDoc will + create and link to a separate page documenting its deprecated + functions. It is good practice to suggest an equivalent function + as an alternative. + + \badcode * + /\1! + \fn MyClass::MyDeprecatedFunction + \deprecated [6.2] Use MyNewFunction() instead. + \1/ + \endcode + + \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. + + \badcode * + /\1! + \internal + + Tries to find the decimal separator. If it can't find + it and the thousand delimiter is != '.' it will try to + find a '.'; + \1/ + 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, unless QDoc + is called with the \c{-showinternal} command line option or the + \c{QDOC_SHOW_INTERNAL} environment variable is set. + + \target modulestate-command + \section1 \\modulestate + + The \\modulestate command can be used within a \\module or \\qmlmodule + topic to provide a module state description other than \e preliminary or + \e deprecated. + + Rest of the line is taken as an argument that describes the module's + state. For example: + + \badcode * + /*! + \module QtFoo + \modulestate Technical Preview + \1/ + \endcode + + QDoc will then add this information on the module page: + + \quotation + This module is in \e {Technical Preview} state. + \endquotation + + In HTML output, this state information appears also in the navigation + bar (breadcrumbs) of reference pages for the module's members. + + \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. + + \badcode * + /\1! + \preliminary + + Returns information about the joining type attributes of the + character (needed for certain languages such as Arabic or + Syriac). + + \1/ + QChar::JoiningType QChar::joiningType() const + { + return QChar::joiningType(ucs); + } + \endcode + + \target readonly-command + \section1 \\readonly + + The \\readonly command is used in conjunction with a \l {qmlproperty-command} + {\\qmlproperty} command to mark the QML property as read-only. + + \target required-command + \section1 \\required + + The \\required command is used in conjunction with a \l {qmlproperty-command} + {\\qmlproperty} command to mark the QML property as required. + + \b {See also} \l {The Property System}. + + \target since-command + \section1 \\since + + The \\since command tells in which minor release + the associated functionality was added. + + If the argument passed to \\since contains no spaces, it is assumed to be + a version number string for the Qt project, and QDoc will prefix it with + 'Qt' in the generated output. The argument can also contain the project + name explicitly: + + \badcode + \since MyFramework 2.0 + \endcode + + In this case, the arguments (project and version) are used as is. + + \section2 Inheritance of Since Information + + Since QDoc version 6.5, C++ classes and QML types inherit the \\since statement + from their respective \l {module-command}{module} or \l {qmlmodule-command} + {QML module}, unless \\since is explicitly used in the type documentation. + + \section2 Since Clause + + The \\value command allows an optional \e {since} clause, enclosed in square + brackets, to immediately follow the command string. This is used for + marking specific C++ enum values with since information. + + See also \l {value-command}{\\value} and \l {ignoresince}. + + \target wrapper-command + \section1 \\wrapper + + The \\wrapper command, when used in a C++ class documentation, marks the + class as a \e wrapper that provides access to a non-Qt API. This command + is used for suppressing warnings that might otherwise be generated for + members of such a class. +*/ + + +/*! + \page 17-qdoc-commands-thread.html + \previouspage Status + \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 + \badcode * + /\1! + \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() + \1/ + void QLocale::setDefault(const QLocale &locale) + { + default_d = locale.d; + } + \endcode + + 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 + \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. + + \badcode * + /\1! + \qmltype PauseAnimation + \nativetype 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} + \1/ + \endcode + + QDoc includes this line on the reference page for the + \l [QML] PauseAnimation + element: + + \quotation + Inherits \l [QML] 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. + + 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. + + \badcode * + /\1! + \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() + \1/ + QAction *QMenu::addAction(const QIcon &icon, const QString &text) + { + QAction *ret = new QAction(icon, text, this); + addAction(ret); + return ret; + } + \endcode + + 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. + + \badcode * + /\1! + \reimp + \1/ + 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. For template types, use the type name only. + + \badcode * + /\1! + \relates QChar + + Reads a char from the stream \a in into char \a chr. + + \sa {Format of the QDataStream operators} + \1/ + 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 + \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 + class, page, or other entity belongs to a certain group of + related documentation. + + An entity may belong to multiple 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. + + \badcode * + /\1! + \class QDir + \brief The QDir class provides access to directory + structures and their contents. + + \ingroup io + ... + \1/ + \endcode + + This adds the QDir class to the \c io group. An entry for QDir + will then appear on the list created with, for example, + the \l {annotatedlist-command} {\\annotatedlist} command with + an argument \c io. + + QDoc automatically generates links to associated groups on a + C++ class, namespace, or header reference page. For example, + given the above documentation for class \QDir and the following + \l {group-command}{\\group} page: + + \badcode * + /\1 + \group io + \title Input/Output and Networking + ... + \1/ + \endcode + + QDoc then outputs a statement on the QDir reference page: + + \quotation + \list + \li \QDir is part of \l {Input/Output and Networking}. + \endlist + \endquotation + + For HTML output, QDoc also generates a link to the group + page as part of the navigation bar (breadcrumbs). If multiple + \\ingroup commands are used, the first one that references + a documented \\group is selected. + + 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 \QD, 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 \QD 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 + \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. + + \badcode * + /\1! + \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. + + ... + \1/ + \endcode + + See also \l {subtitle-command} {\\subtitle}. + + \target subtitle-command + \section2 \\subtitle + + The \\subtitle command sets a subtitle for a documentation page. + + \badcode * + /\1! + \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. + ... + \1/ + \endcode + + See also \l {title-command} {\\title}. + +*/ diff --git a/src/qdoc/qdoc/doc/qdoc-manual-intro.qdoc b/src/qdoc/qdoc/doc/qdoc-manual-intro.qdoc new file mode 100644 index 000000000..0aeb715c9 --- /dev/null +++ b/src/qdoc/qdoc/doc/qdoc-manual-intro.qdoc @@ -0,0 +1,299 @@ +// Copyright (C) 2016 The Qt Company Ltd. +// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only + +/*! + \page 01-qdoc-manual.html + \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 DocBook 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: + + \badcode * + /\1! + \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. + + .... + \1/ + \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, DocBook 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/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 links. + + 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 memory. + 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 {DocBook} to get DocBook output instead. + + Next, QDoc uses the values of the + \l {headerdirs-variable} + {headerdirs} variable and/or the \l + {22-qdoc-configuration-generalvariables.html#headers-variable} + {headers} variable to find and parse all the header files for your + project. QDoc does \e not scan header files for QDoc comments. It + parses the header files to build a master tree of all the items + that should be documented, in other words, the items that QDoc should find + QDoc comments for. + + After parsing all the header files and building the master tree of + items to be documented, QDoc uses the value of the \l + {22-qdoc-configuration-generalvariables.html#sourcedirs-variable} + {sourcedirs} variable and/or the value of the \l + {22-qdoc-configuration-generalvariables.html#sources-variable} + {sources} variable to find and parse all the \c {.cpp} and \c + {.qdoc} files for your project. These are the files QDoc scans for + \e {QDoc comments}. Remember that a QDoc comment begins with + an exclamation mark: \b {/*!} . + + For each QDoc comment it finds, it searches the master tree for + the item where the documentation belongs. Then it interprets the + QDoc commands in the comment and stores the interpreted commands + and the comment text in the tree node for the item. + + Finally, QDoc traverses the master tree. For each node, if the + node has stored documentation, QDoc calls the output generator + specified by the \c {outputformats} variable to format and write + the documentation in the directory specified in the configuration + file in the \l + {22-qdoc-configuration-generalvariables.html#outputdir-variable} + {outputdir} variable. + + \section1 Command Types + + QDoc interprets three types of commands: + + \list + \li \l {Topic Commands} + \li \l {Context Commands} + \li \l {Markup Commands} + \endlist + + Topic commands identify the element you are documenting, for example + a C++ class, function, type, or an extra page of text + that doesn't map to an underlying C++ element. + + Context commands tell QDoc how the element being documented + relates to other documented elements, for example, next and previous page + links, inclusion in page groups, or library modules. Context + commands can also provide information about the documented element + that QDoc can't get from the source files, for example, whether the + element is thread-safe, whether it is an overloaded or reimplemented function, + or whether it has been deprecated. + + Markup commands tell QDoc how text and image elements in the + document should be rendered, or about the document's outline + structure. +*/ + diff --git a/src/qdoc/qdoc/doc/qdoc-manual-macros.qdoc b/src/qdoc/qdoc/doc/qdoc-manual-macros.qdoc new file mode 100644 index 000000000..2d65b540b --- /dev/null +++ b/src/qdoc/qdoc/doc/qdoc-manual-macros.qdoc @@ -0,0 +1,497 @@ +// Copyright (C) 2023 The Qt Company Ltd. +// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only + +/*! + \page qdoc-macros.html + \previouspage 12-0-qdoc-commands-miscellaneous.html + \nextpage qdoc-macros-cmake-text-snippets.html + \title Macros + + Use the \l {macro-variable}{macro} variable to create your own simple QDoc + commands. + + Macros are useful for: + + \list + \li Including recurring text, such as formatted text snippets, + into documentation. + \li Pulling in information, such as version strings, from the build + system into .documentation. + \li Maintaining a single location for strings that are likely to change + in the future, such as product names. + \li Making sure that a term or product name is used consistently. + \li Styling the generated documentation by using HTML and DocBook + elements, such as forced line breaks and special characters. + \li Using tabs to show examples of content for different programming + languages, operating systems, or tools, for example. + \endlist + + \section1 Global Macros + + For a set of predefined global macros that you can use in all documentation + projects and their current values, see + \l{https://github.com/qt/qtbase/blob/e4315204b1412d74842b3167c3eb9a49dc233355/doc/global/macros.qdocconf} + {/qtbase/doc/global/macros.qdocconf} and + \l{https://github.com/qt/qtbase/blob/e4315204b1412d74842b3167c3eb9a49dc233355/doc/global/htmltabs.qdocconf} + {/qtbase/doc/global/htmltabs.qdocconf}. They have macros that include: + + \list + \li \l {CMake Text Snippets} + \li \l {HTML and DocBook Formatting} + \li \l {Product Names} + \li \l {Product Versions} + \li \l {Tabbed Content} + \li \l {youtube-macro}{Links to YouTube content} + \li \l {Miscellaneous Macros} + \endlist + + \QOI copies the macros files to your Qt installation folder, so you can use + the macros even if you build the documentation using QDoc from an installed + Qt (as opposed to building QDoc yourself from sources). + + \note The values of the global macros might change between Qt versions, + so the macros might be extended differently depending on the Qt version that + you use to build the documentation. + + \section1 Adding Macros + + You can add macros for a particular documentation project in the + .qdocconf file of the project or any .qdocconf file that you include into it. + If the macro could be useful in more than one documentation project, add it + to the global macros file. + + For more information about the macro syntax and options, see + \l {macro-variable}{macro}. + + \section1 Using Macros + + You can use macros in the same way as the built-in QDoc commands in: + + \list + \li Code source files, in documentation comments (.cpp, .qml) + \li Documentation source files (.qdoc, .qdocinc) + \endlist + + For example: + + \badcode + \QOI copies the macros files to your Qt installation folder. + \endcode + + \section1 Obsolete Macros + + The global macros file contains the following obsolete macros for + compatibility with older documentation sets. + + \table + \header + \li Don't Use + \li Use + \row + \li \\gui + \li \l{uicontrol-command}{\\uicontrol} + \row + \li \\menu + \li \l{uicontrol-command}{\\uicontrol} + \row + \li \\param + \li \l{a-command}{\\a} + \row + \li \\return + \li Write \e Returns or \e returns. + \endtable + + \sa {macro-variable}{macro}, {Unknown macro} +*/ + +/*! + \page qdoc-macros-cmake-text-snippets.html + \previouspage qdoc-macros.html + \nextpage qdoc-macros-formatting.html + + \title CMake Text Snippets + + See \l{https://github.com/qt/qtbase/blob/e4315204b1412d74842b3167c3eb9a49dc233355/doc/global/macros.qdocconf} + {/qtbase/doc/global/macros.qdocconf} for standard text snippets that you + should use when writing \l {Building with CMake} + {Qt-specific CMake documentation}: + + \table + \header + \li Macro + \li Use + \row + \li \\cmakecommandandroidonly + \li For Android targets + \row + \li \\cmakecommandsince + \li To indicate which Qt version introduced the command + \row + \li \\cmakepropertyandroidonly + \li For Android targets + \row + \li \\cmakepropertyiosonly + \li For iOS targets + \row + \li \\cmakepropertysince + \li To indicate which Qt version introduced the property + \row + \li \\cmakepropertywebassemblyonly + \li For WebAssembly targets + \row + \li \\cmakevariableandroidonly + \li For Android targets + \row + \li \\cmakevariableiosonly + \li For iOS targets + \row + \li \\cmakevariablesince + \li To indicate which Qt version introduced the variable + \row + \li \\preliminarycmakecommand + \li To indicate that the command may change in future versions + \row + \li \\preliminarycmakeproperty + \li To indicate that the property may change in future versions + \row + \li \\preliminarycmakevariable + \li To indicate that the variable may change in future versions + \row + \li \\versionlessCMakeCommandsNote + \li For all commands, to tell users how to use versioned commands + \endtable + + \sa {macro-variable}{macro}, {Macros} +*/ + +/*! + \page qdoc-macros-formatting.html + \previouspage qdoc-macros.html + \nextpage qdoc-macros-product-names.html + + \title HTML and DocBook Formatting + + See \l{https://github.com/qt/qtbase/blob/e4315204b1412d74842b3167c3eb9a49dc233355/doc/global/macros.qdocconf} + {/qtbase/doc/global/macros.qdocconf} for HTML and DocBook elements and + special characters that you can use in documentation source files. + + \sa {Macros and Other Configurations}, {macro-variable}{macro}, {Macros} + +*/ + +/*! + \page qdoc-macros-product-names.html + \previouspage qdoc-macros-formatting.html + \nextpage qdoc-macros-tabbed-content.html + + \title Product Names + + Use the following macros to refer to products: + + \table + \header + \li Macro + \li Expands To + \row + \li \\B2Q + \li Boot to Qt + \row + \li \\B2QSS + \li Boot to Qt Software Stack + \row + \li \\B2QST + \li Boot to Qt Startup Screen + \row + \li \\IFW + \li Qt Installer Framework + \row + \li \\macos + \li macOS + \row + \li \\QA + \li Qt Assistant + \row + \li \\QB + \li Qt Bridge + \row + \li \\QBF + \li Qt Bridge for Figma + \row + \li \\QBPS + \li Qt Bridge for Adobe Photoshop + \row + \li \\QBSK + \li Qt Bridge for Sketch + \row + \li \\QBXD + \li Qt Bridge for Adobe XD + \row + \li \\QC + \li Qt Creator + \row + \li \\QD + \li Qt Widgets Designer + \row + \li \\QDS + \li Qt Design Studio + \row + \li \\QDV + \li Qt Design Viewer + \row + \li \\QfP + \li Qt for Python + \row + \li \\QL + \li Qt Linguist + \row + \li \\QMCU + \li Qt for MCUs + \row + \li \\QMLLS + \li QML Language Server + \row + \li \\QMLP + \li QML Profiler + \row + \li \\QMT + \li Qt Maintenance Tool + \row + \li \\QOI + \li Qt Online Installer + \row + \li \\QQEM + \li Qt Quick Effect Maker + \row + \li \\QQV + \li Qt QML Viewer + \row + \li \\QtAA + \li Qt for Android Automotive + \row + \li \\QtTAS + \li Qt Tools for Android Studio + \row + \li \\QUL + \li Qt Quick Ultralite + \endtable + + \sa {macro-variable}{macro}, {Macros} +*/ + +/*! + \page qdoc-macros-product-versions.html + \previouspage qdoc-macros-product-names.html + \nextpage qdoc-macros-tabbed-content.html + + \title Product Versions + + Use the following macros to display version and status information about a + topic: + + \table + \header + \li Macro + \li Expands To + \row + \li \\QtMajorVersion + \li The major version number based on the $QT_VER environment variable + \row + \li \\QtMinorVersion + \li The minor version number based on the $QT_VER environment variable + \row + \li \\QtVersion + \li The value of the $QT_VERSION environment variable + \row + \li \\QtVer + \li The value of the $QT_VER environment variable + \row + \li \\techpreview + \li The statement that a module or class is preliminary and might change + \endtable + + \section1 \\techpreview + + Appends the tech preview link to the brief sentence and adds the topic to + the \c tech_preview group. + + Must be placed directly under a \brief command. + + \sa {macro-variable}{macro}, {Macros} +*/ + +/*! + \page qdoc-macros-tabbed-content.html + \previouspage qdoc-macros-formatting.html + \nextpage qdoc-macros-youtube-videos.html + + \title Tabbed Content + + Use the following macros to create \e {tab groups} of labeled HTML tabs that + have comparable or alternative content. For example, you can show code + snippets for different programming languages. + + \list + \li \l{tab-macro}{\\tab} + \li \l{tabcontent-macro}{\\tabcontent} + \li \l{endtabcontent-macro}{\\endtabcontent} + \endlist + + \section1 Using Tab Macros + + \badcode + \tab {name}{tab-id}{title}{checked} + \tabcontent {tab-id} + content + \endtabcontent + \endcode + + \note These macros only work with the online template, so you usually + need to use conditional text to get good results also for the offline help. + + For example, to show instructions for the CMake and qmake build systems in + tabs: + + \badcode + \if defined(onlinedocs) + \tab {build-qt-app}{tab-cmake}{CMake}{checked} + \tab {build-qt-app}{tab-qmake}{qmake}{} + \tabcontent {tab-cmake} + \else + \section1 Using CMake + \endif + CMake-specific instructions go here + \if defined(onlinedocs) + \endtabcontent + \tabcontent {tab-qmake} + \else + \section1 Using qmake + \endif + qmake-specific instructions go here + \if defined(onlinedocs) + \endtabcontent + \endif + \endcode + + \target tab-macro + \section1 \\tab + + \badcode + \tab {name}{tab-id}{title}{checked} + \endcode + + Specifies a tab in a tab group with a name, ID, title, and default state. + + Use a unique \e {name} to specify which tabs belong to a tab group. That is, + all tabs in a group have the same name. To separate the tabs from each other, + give them each a unique \e {tab-id} within the group. Use this \e {tab-id} + as the value of the \\tabcontent macro to add content to the tab. + + The \e {checked} argument selects the tab by default when the HTML page is + loaded. For the initially hidden tabs, pass an empty argument {}. + + \target tabcontent-macro + \section1 \\tabcontent + + \badcode + \tabcontent {tab-id} + \endcode + + Adds content to the tab with the \e {tab-id} you specify. + + \target endtabcontent-macro + \section1 \\endtabcontent + + Marks the end of the tab content that you begin with \\tabcontent. + + \sa {Macros} +*/ + +/*! + \page qdoc-macros-youtube-videos.html + \previouspage qdoc-macros-tabbed-content.html + \nextpage qdoc-macros-misc.html + + \target youtube-macro + \title \\youtube + + When generating online documentation, embeds a YouTube video in the HTML. + When generating offline documentation (.qch), adds an external link to the + video with a thumbnail image. The HTML docs show a thumbnail of the video + with a play button. You need to save the thumbnail in + \c {\images\extraimages\} in your project folder. + + Use the following URL to open the thumbnail image in a browser: + \c {https://img.youtube.com/vi/<ID>/0.jpg}. The \c <ID> is the ID of + the video on YouTube. For example, if the URL to the video is + \c {https://www.youtube.com/watch?v=dQw4w9WgXcQ&feature=youtu.be}, + the ID is \c dQw4w9WgXcQ. Save the image file as \c dQw4w9WgXcQ.jpg. + + You must add the filename of the thumbnail file to + \c {\images\extraimages\extraimages.qdocconf}. For example: + + \badcode + {HTML.extraimages,qhp.qtdesignstudio.extraFiles} += \ + images/dQw4w9WgXcQ.jpg + \endcode + + To add a link to the video in text, write: + + \badcode + \youtube dQw4w9WgXcQ + \endcode + + \sa {Macros} +*/ + +/*! + \page qdoc-macros-misc.html + \previouspage qdoc-macros-youtube-videos.html + \nextpage 21-0-qdoc-configuration.html + + \title Miscellaneous Macros + + You can use the following macros to affect the HTML output and to use + standard terminology: + + \list + \li \l {borderedimage-macro}{\\borderedimage} + \li \l {examplecategory-macro}{\\examplecategory} + \li \l {key-macro}{\\key} + \li \l {nullptr-macro}{\\nullptr} + \li \l {summary-macro}{\\summary} + \endlist + + \target borderedimage-macro + \section1 \\borderedimage + + Like \l{image-command}{\\image}, but adds a border around the image. + + \target examplecategory-macro + \section1 \\examplecategory + + Describes the category an example is sorted to in the Qt Creator + \uicontrol Examples tab. + + \target key-macro + \section1 \\key + + Formats keyboard key names. + + \target nullptr-macro + \section1 \\nullptr + + Expands to the term to use for null pointers. + + \target summary-macro + \section1 \\summary + + Like \l{brief-command}{\\brief}, but replicates the sentence also as text. + + Wrap the entire sentence within \c {{}}. For example: + + \badcode + \summary {Creates a build target.} + \endcode + + \sa {macro-variable}{macro}, {Macros} +*/ diff --git a/src/qdoc/qdoc/doc/qdoc-manual-markupcmds.qdoc b/src/qdoc/qdoc/doc/qdoc-manual-markupcmds.qdoc new file mode 100644 index 000000000..3615d2399 --- /dev/null +++ b/src/qdoc/qdoc/doc/qdoc-manual-markupcmds.qdoc @@ -0,0 +1,3196 @@ +// Copyright (C) 2020 The Qt Company Ltd. +// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only + +/*! + \page 03-qdoc-commands-markup.html + \previouspage Naming Things + \nextpage Macros + + \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} + \li \l {badcode-command} {\\badcode} + \li \l {b-command} {\\bold} (deprecated, use \\b) + \li \l {br-command} {\\br} + \li \l {brief-command} {\\brief} + \li \l {c-command} {\\c} + \li \l {caption-command} {\\caption} + \li \l {code-command} {\\code} + \li \l {codeline-command} {\\codeline} + \li \l {details-command} {\\details} + \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 {footnote-command} {\\footnote} + \li \l {generatelist-command} {\\generatelist} + \li \l {header-command} {\\header} + \li \l {e-command} {\\i} (deprecated, use \\e) + \li \l {if-command} {\\if} + \li \l {image-command} {\\image} + \li \l {include-command} {\\include} + \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} + \li \l {list-command} {\\list} + \li \l {meta-command} {\\meta} + \li \l {noautolist-command} {\\noautolist} + \li \l {li-command} {\\o} (deprecated, use \\li) + \li \l {note-command} {\\note} + \li \l {omit-command} {\\omit} + \li \l {printline-command} {\\printline} + \li \l {printto-command} {\\printto} + \li \l {printuntil-command} {\\printuntil} + \li \l {qml-command}{\\qml} + \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 {sincelist-command} {\\sincelist} + \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 \qdoccmd tm + \li \l {tt-command} {\\tt} + \li \l {uicontrol-command} {\\uicontrol} + \li \l {underline-command} {\\underline} + \li \l {raw-command} {\\unicode} + \li \l {warning-command} {\\warning} + \li \l {backslash-sequence} {\\\\} + \li \l {endash-sequence} {\--} + \li \l {emdash-sequence} {-\--} + \endlist +*/ + + +/*! + \page 04-qdoc-commands-textmarkup.html + \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. + + 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. 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 + + 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 details-command + \section1 \\details (collapsible) + + The \\details and \\enddetails commands generates a collapsible <details> + element with a <summary> to control the hidden/visible state. + + When generating HTML output, use the \\details and \\enddetails commands to + generate a collapsible \c{<details>} HTML element. The command takes an + optional summary string enclosed in curly braces. This optional argument + specifies a visible heading for the details. + + For example, with the following input: + \badcode * + /\1! + \details {QDoc details} + \note You're looking at detailed information. + \enddetails + \1/ + \endcode + + If QDoc is generating HTML, it will translate these commands to: + + \badcode + <summary>QDoc details</summary><div class="admonition note"><p><b>Note: </b>You're looking at detailed information.</p></div> + \endcode + + QDoc renders this as: + + \details {QDoc details} + \note You're looking at detailed information. + \enddetails + + For any other output format, QDoc generates the contents as a normal paragraph, + ignoring the summary string. This command was introduced to QDoc in Qt6.6. + + \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: + + \badcode * + /\1! + \div {class="float-right"} + \inlineimage qml-column.png + \enddiv + \1/ + \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 + + \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 + + 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. + + \badcode * + /\1! + 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 + \1/ + \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 tm-command + \section1 \\tm (trademark) + + The \\tm command indicates that its argument is a trademark. QDoc appends + a trademark symbol `™` to the first occurrence of the argument when + generating a page. + + In the project's configuration, the \c navigation.trademarkspage variable + is used for defining a title of a page that contains trademark-related + documentation. + + \badcode + navigation.trademarkspage = Trademarks + \endcode + + If set, each occurrence of the trademark symbol also links to the + trademarks page. + + \note In section titles, the \\tm command is ignored and its argument + rendered as-is. + + See also \l {sectionOne-command}{\\section1} and \qdocvar {navigation}. + + \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}). + + \badcode * + /\1! + 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}().} + \1/ + \endcode + + 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 + + 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. + + \badcode * + /\1! + This is regular text; \b {this text is + rendered using the \\b command}. + \1/ + \endcode + + \target br-command + \section1 \\br + + The \\br command forces a line break. + + \target e-command + \section1 \\e (emphasis, italics) + + The \\e command renders its argument in a special font, normally italics. This + command used to be called \\i, which is now deprecated. + + If the argument contains spaces or other punctuation, enclose the + argument in curly brackets. + + \badcode * + /\1! + Here, we render \e {a few words} in italics. + \1/ + \endcode + + 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, so you + don't need braces in cases like this: + + \badcode * + /\1! + An argument can sometimes contain whitespaces, + for example: \e QPushButton(tr("A Brand New Button")) + \1/ + \endcode + + Finally, trailing punctuation is not included in an argument, + nor is "'s". + + \target sub-command + \section1 \\sub + + The \\sub command renders its argument lower than the baseline of + the regular text, using a smaller font. + + \badcode * + /\1! + 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. + \1/ + \endcode + + 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. + + \badcode * + /\1! + The series + + 1 + a + a\sup 2 + a\sup 3 + a\sup 4 + ... + + is called the \i {geometric series}. + \1/ + \endcode + + 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. + + See also \l {b-command}{\\b}. + + \target underline-command + \section1 \\underline + + The \\underline command renders its argument underlined. + + \badcode * + /\1! + 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. + \1/ + \endcode + + If the argument contains spaces or other punctuation, enclose the + argument in curly brackets. + + \target backslash-sequence + \section1 \\\\ (double backslash) + + The sequence \\\\ expands to a single backslash. + + QDoc commands always start with a single backslash. To display a + single backslash in the text, you must type two backslashes. If + you want to display two backslashes, you must type four. + + \badcode * + /\1! + The \\\\ command is useful if you want a + backslash to appear verbatim, for example, + writing C:\\windows\\home\\. + \1/ + \endcode + + 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: + + \badcode * + /\1! + 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\}. + \1/ + \endcode + + \target endash-sequence + \section1 \-- (en dash) + QDoc renders double hyphens as an en dash. QDoc markup commands + designed to make their input appear verbatim---such as the \\c + command---won't replace the double hyphens with an en dash character. + For example: + + \badcode * + /\1! + The \\c command -- useful if you want text in a monospace font -- + is well documented. + \1/ + \endcode + + However, other commands may require that the hyphens are escaped to ensure + QDoc renders the output as expected. For example; + + \badcode * + /\1! + This \l {endash-sequence}{link to the -- (endash) sequence} + isn't escaped and QDoc therefore renders an endash in the link + text. However, the escaped + \l {endash-sequence}{link to the \-- (endash) sequence} + renders both hyphens as intended. + \1/ + \endcode + + See also \l {emdash-sequence}{\-\-- (em dash)}. + + \target emdash-sequence + \section1 -\-- (em dash) + + QDoc renders triple hyphens as an en dash. QDoc markup commands + designed to make their input appear verbatim---such as the \\c + command---won't replace the triple hyphens with an en dash character. + For example: + + \badcode * + /\1! + The \\c command---useful when you want text to be rendered + verbatim---is well documented. + \1/ + \endcode + + However, other commands may require that the hyphens are escaped to ensure + QDoc renders the output as expected. For example; + + \badcode * + /\1! + This \l {emdash-sequence}{link to the --- (emdash) sequence} + isn't escaped and QDoc therefore renders an emdash in the link + text. However, the escaped + \l {emdash-sequence}{link to the -\-- (emdash) sequence} + renders both hyphens as intended. + \1/ + \endcode + + \note The escaped control sequence in this example is for the en dash. + This avoids a hyphen followed by an en dash in the output. + + See also \l {endash-sequence}{\-- (en dash)}. +*/ + + +/*! + \page 05-qdoc-commands-documentstructure.html + \previouspage Text Markup + \nextpage Including Code Inline + + \title Document Structure + + The document structuring commands are for dividing your document + into sections. QDoc supports four levels of section: \c \section1, + \c \section2, \c \section3, and \c \section4. The section commands + correspond to the traditional section, subsection, etc used in + outlining. + + \section1 Section commands + + 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 four levels for sections in QDoc: \c \section1, + \c \section2, \c \section3 and \c \section4. These correspond to the + traditional section, subsection, subsubsection and subsubsubsection. + + There is a strict ordering of the section units: + + \code + section1 + | + section2 + | + section3 + | + section4 + \endcode + + When sections are used, the first section command should be \c section1. + + \badcode * + /\1! + \section1 Basic Qt + + This is the first section. + + + \section2 Getting Started + + This is the first subsection. + + + \section3 Hello Qt + + This is the first subsubsection. + + + \section3 Making Connections + + This is the second subsubsection. + + + \section3 Using the Reference Documentation + + This is the third subsubsection. + + + \section2 Creating Dialogs + + This is the second subsection. + + + \section3 Subclassing QDialog + + This is the first subsubsection. + + ... + + + \section1 Intermediate Qt + + This is the second section. + + + \section2 Layout Management + + This is the second section's first subsection. + + + \section3 Basic Layouts + + This is the first subsubsection. + + ... + \1/ + \endcode + + 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 sectionOne-command + \section1 \\section1 + + The \\section1 command starts a new section. + + See \l{section-commands} {Section commands} 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{section-commands} {Section commands} 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{section-commands} {Section commands} 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{section-commands} {Section commands} for an explanation of the various + section units, command argument, and rendering. + +*/ + + +/*! + \page 06-qdoc-commands-includecodeinline.html + \previouspage Document Structure + \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. + + \note Although most of 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 + a html <pre> element, and parses the enclosed snippet, creating links + to any known types in the code. + + For documenting command-line instructions, shell scripts, or any + content that is not in a Qt language recognized by QDoc, use + \l {badcode-command}{\\badcode} instead. + + When processing the \\code command, 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. + + \note This doesn't apply to externally quoted code using the \l + {quotefromfile-command} {\\quotefromfile} or \l + {quotefile-command} {\\quotefile} command. + + \code \\endcode * + /*! + \code + #include <QApplication> + #include <QPushButton> + + int main(int argc, char *argv[]) + { + ... + } + \1 + \2/ + \endcode + + Other QDoc commands are disabled within \\code... \\endcode, and + the special character '\\' is accepted and rendered like the rest + of the code, unless it is followed by a digit and parameters were + passed to \\code. + + \section2 Highlighting and autolinking + + The \\code commands attempts to parse its contents as code of a + specific language, as defined in the \l {language-variable}{language} + configuration variable. This provides highlighting and automatic + linking to types detected in the code. + + As an exception since QDoc version 6.4, when the \\code command + is used within a QML-specific \l {Topic Commands}{topic}, QDoc + first attempts to recognize the code as QML; for other topics, + the language configuration variable takes precedence. To + explicitly mark the code snippet as QML, use the \l {qml-command} + {\\qml} command instead. + + \section2 Code snippet parameters + + Since QDoc version 5.12, \\code command accepts also optional + parameters. Parameters are useful for injecting simple + strings into the code snippet. To inject a string to a specific + location in the snippet, add a backslash followed by a digit (1..8). + The digits correspond with the order of the argument list, where + arguments are separated by spaces. + + For example: + + \badcode 1 2 * endcode + /\3! + \code * hello + /\\1 \\2 \\1/ + \\4 + \3/ + \endcode + + For the above snippet, QDoc renders the word \e hello enclosed in + a C-style comment. + + \section2 Including code from external files + + To include code snippets from an external file, use the + \l{snippet-command}{\\snippet} and \l{codeline-command} + {\\codeline} commands. + + See also \l {c-command}{\\c}, \l {qml-command}{\\qml}, + \l {badcode-command}{\\badcode}, \l {quotefromfile-command} + {\\quotefromfile}, and \l {language-variable}{language}. + + \target badcode-command + \section1 \\badcode + + Similar to \l {code-command}{\\code}, \\badcode and \\endcode commands + enclose content that is rendered verbatim in a separate paragraph, but no + parsing or automatic link creation is performed. Instead, the content is + treated as plain text. + + Substitute \\code with this command when documenting command-line + instructions, shell scripts or any other content that is not in a Qt + language, but should still be styled similarly to a \\code paragraph. + + Like \\code, \\badcode accepts also optional parameters. + + \target qml-command + \section1 \\qml + + The \\qml and \\endqml commands enclose a snippet of QML source + code. Use these for proper syntax highlighting of QML code snippets. + The enclosed snippet must be complete as if it was a valid .qml file. + If the snippet is incomplete, QDoc will issue a warning and ignore the + snippet. + + \badcode * + /\1! + \qml + import QtQuick 2.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 + \1/ + \endcode + + Like the \l{code-command}{\\code} command, \\qml accepts optional + parameters. +*/ + + +/*! + \page 07-0-qdoc-commands-includingexternalcode.html + \previouspage Including Code Inline + \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. + + \note Although all these commands can be used 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. + + \badcode * + /\1! + 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. + \1/ + \endcode + + 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. + + \badcode * + /\1! + 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. + + ... + \1/ + \endcode + + 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. + + \badcode * + /\1! + 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... + \1/ + \endcode + + \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 {QRegularExpression}{regular expression}. + + \badcode * + /\1! + \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. + \1/ + \endcode + + (\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. + + \badcode * + /\1! + 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... + \1/ + \endcode + + 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. + + If \\printuntil is used without an argument, it expands to all the + lines from the current position to the end of the quoted file. + + 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. + + \badcode * + /\1! + 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. + \1/ + \endcode + + 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. + + \badcode * + /\1! + 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. + \1/ + \endcode + + + 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. + + \badcode * + /\1! + 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 ... + \1/ + \endcode + + 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. + + \badcode * + /\1! + 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... + \1/ + \endcode + + 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. + + \badcode * + /\1! + \quotefromfile examples/main.cpp + \skipto main + \printuntil { + \dots + \skipuntil exec + \printline } + \1/ + \endcode + + The default indentation is 4 spaces, but this can be adjusted + using the command's optional argument. + + \badcode * + /\1! + \dots 0 + \dots + \dots 8 + \dots 12 + \dots 16 + \1/ + \endcode + + 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: + + \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 + + By default, QDoc looks for \c{//!} as a code snippet marker. + For \c{.pro}, \c{.py}, \c{.cmake}, and \c{CMakeLists.txt} + files, \c {#!} is detected. Finally, \c{<!--} is accepted in + \c{.html}, \c{.qrc}, \c{.ui}, \c{.xml}, and \c{.xq} files. + + \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 + \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: + + \badcode * + /\1! + Read the \l {http://doc.qt.io/qt-6/} + {Qt 6 Documentation} carefully. + \1/ + \endcode + + If the link target is equivalent to the link text, the second + argument can be omitted. + + For example, if you have documentation like: + + \badcode * + /\1! + \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}. + \1/ + \endcode + + You can simplify this as follows: + + \badcode * + /\1! + \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. + \1/ + \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{section-commands} {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 + + \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 target 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 the link 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. + + \badcode * + /\1! + Appends the actions \a actions to this widget's + list of actions. + + \sa removeAction(), QMenu, addAction() + \1/ + void QWidget::addActions(QList<QAction *> actions) + { + ... + } + \endcode + + 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. + + \e{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. + + \badcode * + /\1! + \target capturing parentheses + \section1 Capturing Text + + Parentheses allow us to group elements together so that + we can quantify and capture them. + + ... + \1/ + \endcode + + The target name \e{capturing parentheses} can be linked to + in the following way: + + \list + \li \c {\l {capturing parentheses}} + \endlist + + \note The brackets in the link example are required because the + target name contains spaces. + + \section2 \\target in a \\table + When you use the \\target command in a table, make sure that the + \\target command follows a \l {li-command}{\\li}-command (table + cell), and that it's either on a separate line, or the last content + that occurs in the line it's in. This is due to how the \\target + command works; it consumes anything up to the next line break as + its parameter. In other words, if you have a table and need a + \\target within it, make sure that it follows the following + structure: + + \badcode + \table + \row + \li \target my-target + My text goes here. + \li This is my next table cell. + \endtable + \endcode + + 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. + + + \badcode * + /\1! + \class QRegularExpression + \reentrant + \brief The QRegularExpression 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. + + ... + \1/ + \endcode + + The location marked with the keyword can be linked to with: + + \badcode * + /\1! + When a string is surrounded by slashes, it is + interpreted as a \l {regular expression}. + \1/ + \endcode + + 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 + \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. + + \badcode * + /\1! + Qt is a C++ toolkit for cross-platform GUI application development. + + \image happyguy.jpg "Happy guy" + + Qt provides single-source portability across Microsoft + Windows, macOS, Linux, and all major commercial Unix + variants. It is also available for embedded devices. + \1/ + \endcode + + 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 within braces {}, 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: + + \badcode * + /\1! + \list 1 + \li \inlineimage happy.gif {Oh so happy, I am a caption!} + \li \inlineimage happy.gif Oh so happy, but I'm not a caption. + \endlist + \1/ + \endcode + + Here is an example of including inline images in a table: + + \badcode * + /\1! + \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 + \1/ + \endcode + + The command can also be used to insert an image inline with the + text. + + \badcode * + /\1! + \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. + \1/ + \endcode + + 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. + + \badcode * + /\1! + \table 100% + \row + \li \image windows-pushbutton.png + \caption The QPushButton widget provides a command button. + \li \image windows-toolbutton.png + \caption The QToolButton class provides a quick-access button to commands + or options, usually used inside a QToolBar. + \endtable + \1/ + \endcode + + See also \l {image-command} {\\image} and \l {inlineimage-command} + {\\inlineimage} +*/ + + +/*! + \page 10-qdoc-commands-tablesandlists.html + \previouspage Including Images + \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: + + \badcode * + /\1! + \table 100 % + + ... + + \endtable + \1/ + \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. + + \badcode * + /\1! + \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 + \1/ + \endcode + + You can also make cells span several rows and columns. For + example: + + \badcode * + /\1! + \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 + \1/ + \endcode + + 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. + + \badcode * + /\1! + \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 + \1/ + \endcode + + 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. + + \badcode * + /\1! + \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 + \1/ + \endcode + + 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 value name. The value name may + be preceded by an optional \e since clause enclosed in square + brackets. The value description follows the value name. The description + ends at the next blank line or \\value. The arguments are rendered in a + table. + + \note To include images in the \\value description, use the + \l {inlineimage-command}{\\inlineimage} command. + + Without a \e since clause, a \\value command could look like this: + + \code + \value QtInfoMsg A message generated by the qInfo() function. + \endcode + + The same command with a \e since clause would look like this: + + \code + \value [since 5.5] QtInfoMsg A message generated by the qInfo() function. + \endcode + + 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 mandatory argument is the name of the enum item + that will be omitted. If the enum item is followed by a single-line + description, that is also omitted. + + See the \l {enum-command} {\\enum} documentation for an example. + + See also \l {enum-command} {\\enum} and \l {value-command} + {\\value} \l {since-command}{\\since} + + \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: + + \badcode * + /\1! + \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 + \1/ + \endcode + + The \\list command takes an optional argument providing + alternative appearances for the list items. + + \badcode * + /\1! + \list + \li How to Learn Qt + \li Installation + \li Tutorial and Examples + \endlist + \1/ + \endcode + + 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: + + \badcode * + /\1! + \list G + \li How to Learn Qt + \li Installation + \li Tutorial and Examples + \endlist + \1/ + \endcode + + 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. + + \badcode * + /\1! + \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 + \1/ + \endcode + + 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 + \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.: + + \badcode * + /\1! + 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 + \1/ + \endcode + + The text in the \b{\\quotation} block will appear in the generated HTML as: + + \badcode + <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 + any of the \l{Topic Commands}. + + 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 text will be displayed in the documentation + for that particular topic. + + For example the boolean QWidget::isWindow property: + + \badcode * + /\1! + \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() + \1/ + \endcode + + and the QWidget::geometry property + + \badcode * + /\1! + \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(), ... + \1/ + \endcode + + When the \\brief command is used to describe a class, we recommend + using a complete sentence like this: + + \badcode + 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. + + \badcode * + /\1! + \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 + \1/ + \endcode + + Using \\brief in a \l{namespace-command}{\\namespace}: + + \badcode * + /\1! + \namespace Qt + + \brief The Qt namespace contains miscellaneous identifiers + used throughout the Qt library. + \1/ + \endcode + + Using \\brief in a \l{headerfile-command}{\\headerfile}: + + \badcode * + /\1! + \headerfile <QtGlobal> + \title Global Qt Declarations + + \brief The <QtGlobal> header file provides basic + declarations and is included by all other Qt headers. + + \sa <QtAlgorithms> + \1/ + \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: + + \badcode * + /\1! + \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 + \1/ + \endcode + + It will appear in the generated HTML as: + + \badcode + <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} as the argument. This is useful for generating + an overview of the license agreements associated with the source + code. + + \note The output of the \c {\generatelist legalese} command includes + the \\legalese texts in the current documentation project only. If + the current documentation project depends on other modules, their + license texts will not be listed. + + \target warning-command + \section1 \\warning + + The \\warning command prepends "Warning:" to the command's + argument, in bold font. + + \badcode * + /\1! + Qt::HANDLE is a platform-specific handle type + for system objects. This is equivalent to + \c{void *} on Windows and macOS, and to + \c{unsigned long} on X11. + + \warning Using this type is not portable. + \1/ + \endcode +*/ + + +/*! + \page 12-0-qdoc-commands-miscellaneous.html + \previouspage Special Content + \nextpage The QDoc Configuration File + + \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: + + \badcode * + /\1! + ... + \section1 Drag and Drop Classes + + These classes deal with drag and drop and the necessary mime type + encoding and decoding. + + \annotatedlist draganddrop + \1/ + \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. + + The group members are sorted in ascending order, based on + user-visible name or title. Since QDoc 6.9, \\annotatedlist + and \qdoccmd generatelist support also custom sorting. + + See also \qdoccmd generatelist and \l {Sorting group members}. + + \target qtcmakepackage-command + \section1 \\qtcmakepackage + + Use the \\qtcmakepackage command to add CMake package information to classes + and namespaces. This information will then appear in a table at the top of + the class or namespace documentation page. For example: + + \badcode * + /*! + \namespace Foo + \inheaderfile Bar + \qtcmakepackage Baz + \brief A namespace. + + ... + \1/ + \endcode + + QDoc will output this as + + \quotation + \raw HTML + <h1 class="title">Foo Namespace</h1> + <p>A namespace. <a>More...</a></p> + <div class="table"><table class="alignedsummary"> + <tr><td class="memItemLeft rightAlign topAlign"> Header:</td><td class="memItemRight bottomAlign"> <span class="preprocessor">#include <Bar></span></td></tr> + <tr><td class="memItemLeft rightAlign topAlign"> CMake:</td><td class="memItemRight bottomAlign"> find_package(Qt6 REQUIRED COMPONENTS Baz)</td></tr> + </table></div> + \endraw + \endquotation + + + \target qtcmaketargetitem-command + \section1 \\qtcmaketargetitem + + Use the \\qtcmaketargetitem command to override the \e {item} part of the + CMake \c{target_link_libraries} information that's added to classes and + namespaces. The command must be used in conjunction with the + \l{module-command}{\\module} and \l{qtcmakepackage}{\\qtcmakepackage}} + commands. + + \e{See also} \l{module-command}{\\module} and + \l{qtcmakepackage}{\\qtcmakepackage}} + + + \target generatelist-command + \section1 \\generatelist + + The \\generatelist command expands to a list of links to the + documentation entities grouped with an \l {ingroup-command} + {\\ingroup} command or entities that match one of the arguments + listed below. An example from the Qt Reference Documentation: + + \badcode * + /\1! + \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 + \1/ + \endcode + + This generates the \e {All Classes} page. The command accepts the + following arguments: + + \section2 \c {<group-name>} + + With a group name as the only argument, QDoc lists all entities that + use the \c {\ingroup <group-name>} command. + + \section3 Sorting group members + + When generating a list of group members, they are sorted in ascending + order, based on user-visible name or title. Since QDoc 6.9, the default + sort order can be modified: + + \badcode + \generatelist [descending] changelogs + \endcode + + Assuming the \e changelogs group consists of pages + detailing changes in different versions, this generates the + list in descending order (newest version first). + + \section4 Sort key + + Since QDoc 6.9, a custom sort key can be assigned to one or + more group members using the \qdoccmd meta command: + + \badcode + \meta sortkey {sort key} + \endcode + + Sorting (ascending or descending) is then done based on + these key(s), rather than user-visible titles. + + \note Any group member with a sort key is listed \e before + members without a key (in the default ascending order). This + allows raising individual group member(s) to the top of the + list. + + \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. + + \section2 \c annotatedexamples + + The \c annotatedexamples argument provides a complete list of all + examples as a set of tables containing the titles of all the + examples, and a description of each example. Each title is a + link to the example's documentation. + + A separate table for each module (that has documented examples) + is generated, provided that the module has defined a + navigation.landingpage configuration variable. The \e landingpage + variable is used as a title for a header that precedes each table. + + \section2 \c annotatedattributions + + The \c annotatedattributions argument provides a complete list of all + attributions as a set of tables containing the titles of all the + attributions, and a description of each attribution. Each title is a + link to the attribution's page. + + A separate table for each module (that has attributions) + is generated, provided that the module has defined a + navigation.landingpage configuration variable. The \e landingpage + variable is used as a title for a header that precedes each table. + + \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: + + \badcode * + /\1! + \page classes.html + \title All Classes + \ingroup classlists + + \brief Alphabetical list of classes. + + This is a list of all Qt classes. For classes that + have been deprecated, see the \l{Obsolete Classes} + list. + + \generatelist classes Q + \1/ + \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: + + \badcode * + /\1! + \page phonon-module.html + \module Phonon + \title Phonon Module + \ingroup modules + + \brief Contains namespaces and classes for multimedia functionality. + + \generatelist{classesbymodule Phonon} + + ... + \1/ + \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 (excluding QML value types) from the QML module specified + with the second argument. + + \note Support for this argument was introduced in QDoc 5.6. + + \section2 \c qmlvaluetypesbymodule + + Similar to \c qmltypesbymodule argument, but lists QML value + types instead. + + \note Support for this argument was introduced in QDoc 6.7. + + \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: + + \badcode * + /\1! + \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 + \1/ + \endcode + + \section2 \c legalese + + The \c legalese argument tells QDoc to generate a list of licenses in + the current documentation project. Each license is identified using + the \l {legalese-command} {\\legalese} command. + + \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: + + \badcode * + /\1! + \page overviews.html + + \title All Overviews and HOWTOs + + \generatelist overviews + \1/ + \endcode + + \section2 \c attributions + + The \c attributions argument is used to tell QDoc to generate a list + of attributions in the documentation. + + \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: + + \badcode * + /\1! + \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} + \1/ + \endcode + + Each page listed on this group page contains the command: + + \code + \ingroup qt-basic-concepts + \endcode + + See also \qdoccmd {annotatedlist}. + + \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. + + \badcode * + /\1! + \if defined(opensourceedition) + + \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 + \1/ + \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: + + \badcode + 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. + + \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. + + The command is useful when some snippet of commands or text is to + be used in multiple places in the documentation. Use the \\include + command wherever you want to insert a snippet into the documentation. + The file containing the snippet to include, must be located under the + path(s) listed in the \l{sourcedirs-variable}{sourcedirs} or + \l{exampledirs-variable}{exampledirs} QDoc configuration variable. + It can be either any source file parsed by QDoc (or even the same one + where \\include command is used), or any other text file. To store + snippets in a separate file that is not meant to be parsed by QDoc, + use a file extension that is not listed in + \l{sources.fileextensions-variable}{sources.fileextensions}; + for example, \c .qdocinc. + + The command can have one or more 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, leave the second argument + empty. 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: + + \badcode * + /\1! + \page corefeatures.html + \title Core Features + + \include examples/signalandslots.qdocinc + \include examples/objectmodel.qdocinc + \include examples/layoutmanagement.qdocinc + \1/ + \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. If you + have multiple snippets to be included, you can put them all in a + single file and surround each one with: + + \badcode + //! [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: + + \badcode + \include examples/signalandslots.qdocinc snippet-id2 + \include examples/objectmodel.qdocinc another-snippet-id + \endcode + + 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 have nested snippets. + + \note Snippet identifiers work also within documentation comment + (\beginqdoc .. \endqdoc) blocks, so it's not necessary to use a + separate \c .qdocinc file. When processing a comment block, QDoc + removes any \c {//!} comment lines from the generated output. + + \section2 Extra arguments + + Since QDoc 6.3, any further arguments passed to the \\include command + are used for injecting strings into the included content. To inject a + string to a specific location in the content, add a backslash followed + by a digit (1..9). The digits correspond with the order of the argument + list. Enclose arguments in curly braces to ensure that QDoc renders the + entire argument, including possible whitespace characters, as you expect. + + \important Each additional argument (including the snippet ID) must be + enclosed in braces. If you want to include the entire file, + use an empty snippet ID: \c {{}}. + + For example, given the following snippet in a file \c includes.qdocinc: + + \badcode + //! [usage] + To enable \e{\1}, select \uicontrol {\2} > \uicontrol Enable. + //! [usage] + \endcode + + Then, the following \\include line: + + \badcode + \include includes.qdocinc {usage} {detailed output} {Verbose} + \endcode + + Renders + \quotation + To enable \e {detailed output}, select \uicontrol {Verbose} > + \uicontrol Enable. + \endquotation + + \target meta-command + \section1 \\meta + + The \\meta command is used for adding metadata to documentation. + 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: + + \badcode * + /\1! + \example demos/coffee + \title Coffee Machine + \brief A Qt Quick application with a state-based custom user interface. + + \meta {tags} {quick,embedded,states,touch} + \meta {category} {Application Examples} + \1/ + \endcode + + A number of metadata attributes have a specific purpose: + + \b {Example Metadata} + + Another use for \\meta command is to include metadata (tags) in + \l {example-command}{\\example} documentation. By default, QDoc + generates example tags based on the example's \l {title-command}{\\title} + and module name. These tags are displayed in Qt Creator's Welcome mode, + helping users navigate the list of examples. + + Additional tags can be created with \c {\meta {tag} {tag1}} + or \c {\meta {tags} {tag1,[tag2,...]}}. + For example: + + \badcode * + /\1! + \example helloworld + \title Hello World Example + \meta {tags} {tutorial,basic} + \1/ + \endcode + + This would result in the following tags: \e {tutorial,basic,hello,world}. + Common words such as \e example are ignored. + + \b {Excluding Examples} + + Marking an example \e broken will exclude it from the generated manifest + file, effectively removing it from Qt Creator's Welcome mode. + + \badcode + \meta {tag} {broken} + \endcode + + \b {Example Install Paths} + + The \\meta command combined with an argument \c installpath specifies the + location of an installed example. This value overrides the one that is set + using the \c examplesinstallpath configuration variable. + + \badcode * + /\1! + \example helloworld + \title Hello World Example + \meta {installpath} {tutorials} + \1/ + \endcode + + See also \l {examplesinstallpath}. + + \b {Status} + + A \c status argument for the \\meta command adds a custom status description + for a \l {class-command}{\\class} or a \l {qmltype-command}{\\qmltype}. This + description will then appear in a table at the top of the type reference page. + + \badcode * + /\1! + \class QNativeInterface::QAndroidApplication + \meta {status} {Android-specific} + \1/ + \endcode + + See also \l {Status}{status-related commands}. + + \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 Quick Controls QML Types} + for an example. The page is generated from \c {qtquickcontrols2-qmlmodule.qdoc}. + There you will find a QDoc comment containing the \c{\qmlmodule} command for + the QtQuick.Controls module. The same comment contains a \c {\noautolist} + command to disable automatic list generation, and a \l {generatelist-command} + {\\generatelist} to list the QML types in a specific section of the document. + + This command was introduced in QDoc 5.6. + + Since Qt 5.10, this command can be applied also to \l{example-command} + {\\example} documentation, where it causes the automatically generated + list of files and images belonging to an example project to be omitted. + + \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: + + \badcode * + /\1! + \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 + \1/ + \endcode + + \target raw-command + \section1 \\raw (avoid!) + + The \\raw command and the corresponding + \\endraw command delimit a block of raw mark-up language code. + + \warning Avoid using this command if possible. 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. + + QDoc generates the given code only when generating the format that + was specified by the user. + + For example, "\\raw HTML" will only generate code when QDoc + generates HTML documentation. + + \note You can often achieve the intended purpose by using QDoc commands, + while reducing the chance of mistakes or content becoming unmaintained. + + \target sincelist-command + \section1 \\sincelist + + The \\sincelist command expands to a detailed breakdown of new + inclusions to the documented API in a specified version. Example + usage: + + \badcode * \QtMajorVersion \QtMinorVersion \QtVer + /\1! + \page newclasses\2\3.html + \title New Classes and Functions in \4 + \brief A comprehensive list of new classes and functions in \4. + + \sincelist \4 + \1/ + \endcode + + \\sincelist takes a single argument, a version string. The generated + output includes all functionality that is marked with a + \l {since-command}{\\since} command or a \l {since clause} matching + the version string. + + \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). +*/ + diff --git a/src/qdoc/qdoc/doc/qdoc-manual-qdocconf.qdoc b/src/qdoc/qdoc/doc/qdoc-manual-qdocconf.qdoc new file mode 100644 index 000000000..d6fc3305e --- /dev/null +++ b/src/qdoc/qdoc/doc/qdoc-manual-qdocconf.qdoc @@ -0,0 +1,1992 @@ +// Copyright (C) 2021 The Qt Company Ltd. +// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only + +/*! + \page 21-0-qdoc-configuration.html + \previouspage Miscellaneous Macros + \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 minimum.qdocconf. + + 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. + + A valid configuration variable name can include upper and lower case + letters, numbers, and an underscore, '_'. + + 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. + + Values of some configuration variables are interpreted as a list of + strings, for example: + \l {sourcedirs-variable} + {\c{sourcedirs}}, while others are treated as 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 + + This can be written as: + \badcode + sourcedirs = kernel \ + tools \ + widgets + \endcode + + If a value spans multiple lines but is interpreted as a single string, + the lines are joined with spaces. + + \section1 Expansion of Configuration Values + + QDoc supports expanding environment variables within configuration files. + For example, Qt modules rely on the environment variable QT_INSTALL_DOCS + to include definitions related to all Qt module documentation projects: + + \badcode + include($QT_INSTALL_DOCS/global/qt-module-defaults.qdocconf) + \endcode + + A variable to expand is prefixed with '$'. To use the literal character + '$' within a value string, escape it with a backslash: '\\$'. + + Since QDoc 6.0, values can be expanded also from other configuration + variables. In addition to the \c {$variable} syntax, also \c {${variable}} + is valid. The latter eliminates the need to separate the variable + name with whitespace or non-variable characters. For example: + + \badcode + baseurl = https://doc.qt.io/ + ... + url = ${baseurl}qtcreator + \endcode + + If the target variable refers to a list of strings, they will be + joined using spaces in the expanded value: + + \badcode + vars = foo \ + bar \ + baz + + items = "Items: $vars" # Expands to "Items: foo bar baz" + \endcode + + Controlling which character is used for joining the string list is also + possible: + + \badcode + items = "Items: ${vars,|}" # Expands to "Items: foo|bar|baz" + items = "Items: ${vars,,}" # Expands to "Items: foo,bar,baz" + items = "Items: ${vars,}" # Expands to "Items: foobarbaz" + \endcode + + As the expansion is performed after reading in all variables, the order + in which they are defined does not matter. + + \note Nested variable expansion is not supported. + + \section2 Expanding Environment Variables + + When expanding environment variables, the \c {${variable}} syntax has + different behavior compared to \c {$variable}. The former expands the + content of the variable in place to be parsed as part of the + configuration file, while the latter simply assigns the content as a + value for the current configuration variable. This has implications if + the environment variable contains a list of elements separated by + whitespace, or other formatting recognized by QDoc. + + For example, if the value of an environment variable \c SRCDIRS is + \c {"../src/a ../src/b"}, then + + \badcode + sourcedirs = $SRCDIRS # Fail - value is interpreted as a single path. + sourcedirs = ${SRCDIRS} # Ok - whitespace is used as a delimiter. + \endcode + + \section1 Configuration Variables + + \section1 Variable List + + \list + \li \l {defines-variable} {defines} + \li \l {depends-variable} {depends} + \li \l {exampledirs-variable} {exampledirs} + \li \l {examples-variable} {examples} + \li \l {examplesinstallpath-variable} {examplesinstallpath} + \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 {includepaths-variable} {includepaths} + \li \l {ignorewords-variable} {ignorewords} + \li \l {ignoresince-variable} {ignoresince} + \li \l {imagedirs-variable} {imagedirs} + \li \l {indexes-variable} {indexes} + \li \l {language-variable} {language} + \li \l {locationinfo-variable} {locationinfo} + \li \l {macro-variable} {macro} + \li \l {manifestmeta-variable} {manifestmeta} + \li \l {moduleheader-variable} {moduleheader} + \li \l {navigation-variable} {navigation} + \li \l {outputdir-variable} {outputdir} + \li \l {outputformats-variable} {outputformats} + \li \l {outputprefixes-variable} {outputprefixes} + \li \l {outputsuffixes-variable} {outputsuffixes} + \li \l {project-variable} {project} + \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 {url-variable} {url} + \li \l {url.examples-variable} {url.examples} + \li \l {version-variable} {version} + \li \l {versionsym-variable} {versionsym} + \li \l {warninglimit-variable} {warninglimit} + \endlist + + \section1 Categories + + \list + \li \l {Generic Configuration Variables} + \li \l {Format-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 + \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 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. + + \badcode + defines = QT_GUI_LIB + \endcode + + This ensures that QDoc will process the code that requires these + symbols to be defined. For example: + + \code + #ifdef Q_GUI_LIB + void keyClick(QWidget *widget, Qt::Key key, Qt::KeyboardModifiers modifier = Qt::NoModifier, int delay = -1) + #endif + \endcode + + + You can also define preprocessor symbols manually on the command + line using the -D option. For example: + + \badcode + currentdirectory$ qdoc -Dqtforpython qtgui.qdocconf + \endcode + + In this case the -D option ensures that the \c qtforpython + 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 depends-variable + \section1 depends + + The \c depends variable defines a list of other documentation projects + that this project depends on for resolving link targets for type + inheritance and anything else the documentation needs to link to. + + Like Qt itself, documentation for Qt is distributed across multiple + modules. In a multi-module documentation project, the minimum set + of dependencies for a single module consists of actual build + dependencies. In addition, if there is a documentation project + (module) that acts as a top-level entry point for the entire + documentation set and provides \l {navigation-variable}{navigation} + links, each module documentation should include it as a dependency. + + When QDoc generates documentation for a project, it will also generate + an \c .index file containing URLs to each linkable entity in the project. + Each dependency is a (lowercase) name of a project. This name must + match with the base name of the index file generated for that + project. + + \badcode + depends = \ + qtdoc \ + qtcore \ + qtquick + \endcode + + When invoking QDoc on a project that has dependencies and uses the + \c depends variable, one or more \c -indexdir path(s) must be passed + as command line option(s). QDoc uses these paths to search for + the dependencies' index files. + + \badcode + qdoc mydoc.qdocconf -outputdir $PWD/html -indexdir $QT_INSTALL_DOCS + \endcode + + With above, QDoc will search for a file + \c {$QT_INSTALL_DOCS/qtdoc/qtdoc.index} for a dependency to \c qtdoc. + If an index file for a dependency is not found, QDoc will output a + warning. + + The \c depends command accepts also a special value of '*'. This + instructs QDoc to load all index files found in specified index + directories; that is, "depends on everything". + + \badcode + depends = * + \endcode + + See also \l indexes, \l project, and \l url. + + \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 examplesinstallpath-variable + \section1 examplesinstallpath + + The \c examplesinstallpath variable sets the root path for this + project's examples under the \e installed example directory. + + Assuming a root install path of \c QT_INSTALL_EXAMPLES for all + examples, then the path + + \badcode + <QT_INSTALL_EXAMPLES>/<examplesinstallpath>/<example_path> + \endcode + + will be used to refer to a path of a single example within this + documentation project. These paths are recorded in the + \l {Example Manifest Files} {example manifest file}, read by Qt + Creator. + + To ensure correct paths, \c examplesinstallpath must match with + one of the directories listed in \l {exampledirs-variable} + {exampledirs}. The path passed as an argument for each + \l {example-command} {\\example} command is relative to + the path in \e exampledirs. + + For example: + + \badcode + exampledirs = ./snippets \ + ../../../examples/mymodule + + examplesinstallpath = mymodule + \endcode + + And given a following \\example command: + + \badcode * + /*! + \example basic/hello + ... + \1/ + \endcode + + Then, the path \c {mymodule/basic/hello} is recorded in the manifest file + for this example. + + \note It is possible to override \c examplesinstallpath for an individual + \l {example-command}{\\example} using the \l {meta-command}{\\meta} + command. + + \b {See also}: \l {exampledirs}, \l {example-command} {\\example}, and + \l {meta-command}{\\meta}. + + \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 class documentation generated for QWidget. + + Since Qt 5.6, also simple wildcards ('*' and '?') are recognized by + \c excludefiles. For example, to exclude all private Qt header files + from being parsed, define the following: + + \badcode + excludefiles += "*_p.h" + \endcode + + 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 automatically copies an image file from \l imagedirs to the output + directory if it's referenced by the \l {image-command} {\c{\image}} or + \l {inlineimage-command} {\c{\inlineimage}} command. If you want to copy + additional images, you must specify them using the \c extraimages variable. + + The general syntax is \tt {\e{format}.extraimages = \e image}. + + For a contextualized example, refer to the description of the + \l {HTML.postheader-variable}{HTML.postheader} variable. + + Example: + \badcode + HTML.extraimages = images/qt-logo.png + \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. + + The values of the variable are regular expressions (see QRegularExpression + for details). If this variable is not set for a preprocessor + symbol, QDoc assumes its truth value is true. The exception is + '0', which is always 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 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 includepaths-variable + \section1 includepaths + + The \c includepaths variable is used for passing additional + include paths to the Clang parser that QDoc uses for parsing C++ + code for documentation comments. + + The variable accepts a list of paths, prefixed with \c{-I} (include + path), \c {-F} (\macos framework include path), or \c{-isystem} + (system include path). If a prefix is omitted, \c{-I} is used by + default. + + Paths relative to the current .qdocconf file are resolved into + absolute paths. Paths that do not exist in the file system are + ignored. + + \note For Qt documentation projects, the build system typically + provides the required include paths as command line + arguments when invoking QDoc. + + See also \l moduleheader. + + \target ignorewords-variable + \section1 ignorewords + + The \c ignorewords variable is used for specifying a list of strings + that QDoc will ignore when resolving hyperlink targets. + + QDoc has an auto-linking feature, where linking is attempted for words + that resemble C++ or QML entities. Specifically, a string + qualifies for auto-linking if it is at least three characters in + length, has no whitespace, and it + + \list + \li is a \e camelCase word, that is, it contains at least one + uppercase character at index greater than zero, or + \li contains the substring \c {()} or \c {::}, or + \li contains at least one special character, \c {@} or \c {_}. + \endlist + + Adding a qualified word to \c ignorewords stops QDoc from linking + that word automatically. For example, if the word \e OpenGL is a + valid link target (a section, \l{page-command}{\\page}, or + \l {externalpage-command}{\\externalpage} title), a hyperlink for + each occurrence can be avoided with + + \badcode + ignorewords += OpenGL + \endcode + + Linking explicitly with \l {l-command}{\\l} continues to work for + ignored words. + + The \c ignorewords variable was introduced in QDoc 5.14. + + \target ignoresince-variable + \section1 ignoresince + + The \c ignoresince variable is used for setting a cutoff value for + versions passed to the \l {since-command}{\\since} command. All + \\since commands that define a version lower than the cutoff are + ignored and do not generate output. + + The cutoff values are project-specific. The project name can be + defined as a subvariable. The default project name is \e Qt. For + example: + + \badcode + ignoresince = 5.0 + ignoresince.QDoc = 5.0 + \endcode + + These will ignore \\since commands where the major version is 4 + or lower and the project is either \c QDoc or undefined. + + \badcode + \since 3.2 # Ignored + \since 5.2 # Documented (as 'Qt 5.2') + \since QDoc 4.6 # Ignored + \since QtQuick 2.5 # Documented + \endcode + + The \c ignoresince variable was introduced in QDoc 5.15. + + See also \l {since-command}{\\since}. + + \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 + + \target language-variable + \section1 language + + The \c language variable specifies the language of the source code + that is used in the documentation. Specifically, it defines the + default language for parsing source code within \\code .. \\endcode + blocks. + + \badcode + language = Cpp + \endcode + + The default language is C++ (Cpp), and doesn't need to be explicitly + specified. If the code snippets in the documentation consist mainly + of QML code, set QML as the default: + + \badcode + language = QML + \endcode + + See also \l {code-command}[\\code}. + + \target locationinfo-variable + \section1 locationinfo + + The \c locationinfo boolean variable determines whether detailed + location information about each entity is written to + \c {.index}-files and \c {.webxml}-files (when using the WebXML + output format). + + Location information consists of the full path and line + number of either the declaration or documentation comment block + in the source code. + + Setting this to \c false turns off location info: + + \badcode + locationinfo = false + \endcode + + The default value is \c true. + + The \c locationinfo variable was introduced in QDoc 5.15. + + \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. + + \badcode + macro.key = "\\b" + macro.raisedaster.HTML = "<sup>*</sup>" + \endcode + + The first macro defines the \\key 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 + + When using more than one parameter, or when an argument + contains whitespace, enclose each argument in braces: + + \badcode + macro.verinfo = "\1 (version \2)" + \endcode + + \badcode + \verinfo {QFooBar} {1.0 beta} + \endcode + + A special macro option, \e match, can be added for additional + regular expression pattern matching for expanded macros. + + For example, + + \badcode + macro.qtminorversion = "$QT_VER" + macro.qtminorversion.match = "\\d+\\.(\\d+)" + \endcode + + This creates a macro \\qtminorversion that expands to the minor + version based on the QT_VER environment variable. + + A macro that defines a match pattern outputs all capture groups + (parentheses) concatenated together, or the exact matched string + if the pattern does not contain any capture groups. + + For more information about pre-defined macros, see \l {Macros}. + + \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 moduleheader-variable + \section1 moduleheader + + The \c moduleheader variable defines the name of the module + header of a documented C++ module. + + Projects that document C++ APIs require a module-level header + that includes all public classes, namespaces and header files + for the module. The Clang parser in QDoc uses this file to + build a pre-compiled header (PCH) for the module to increase + the speed of parsing source files. + + By default, the \l{project-variable}{project} name is used + also as the module header name. + + \badcode + project = QtCore + \endcode + + With the above project name, QDoc searches a module header + \e QtCore in all known include paths; first using the paths + passed as command line arguments, then the paths listed in + the \l includepaths variable. + + QDoc will issue a warning if the module header is not found. + It will then attempt to build an artificial module header + based on the headers listed in the \l {headerdirs-variable} + {headerdirs} variable. + + For Qt documentation projects, the build system typically + provides QDoc with correct include paths to locate the + module header, provided that the \c project variable is set + correctly. The \c moduleheader variable provides an + alternative file name for QDoc to search for. + + If the project contains no C++ documentation, QDoc should be + instructed to skip generating a PCH by setting \c moduleheader + to an empty string: + + \badcode + # No C++ code to document in this project + moduleheader = + \endcode + + See also \l includepaths and \l project. + + \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 navigation-variable + \section1 navigation + + The \c navigation sub-variables, if defined, set the home page, landing + page, C++ classes page, and QML types page that are visible in the + generated navigation bar for each page. + + In a project with multiple sub-projects (for example, Qt modules), each + sub-project typically defines its own landing page while the same home + page is used across all sub-projects. + + \b Sub-variables + + \table + \row \li \c navigation.homepage + \li Project home page. + \row \li \c navigation.hometitle + \li (Optional) User-visible title for the home page. + Default value is taken from \c homepage. + \row \li \c navigation.landingpage + \li Sub-project landing page. + \row \li \c navigation.landingtitle + \li (Optional) User-visible title for the landing page. + Defaults value is taken from \c landingpage. + \row \li \c navigation.cppclassespage + \li Top-level page that lists all C++ classes for this (sub-)project. + Typically, the title of a \l {module-command}{\\module} page. + \row \li \c navigation.cppclassestitle + \li (Optional) User-visible title for the C++ classes page. + Default is "C++ Classes". + \row \li \c navigation.qmltypespage + \li Top-level page that lists all QML types for this (sub-)project. + Typically, the title of a \l {qmlmodule-command}{\\qmlmodule} page. + \row \li \c navigation.qmltypestitle + \li (Optional) User-visible title for the QML types page. + Default is "QML Types". + \row \li \c navigation.toctitles (Since QDoc 6.0) + \li Page title(s) containing a \l {list-command}{\\list} structure that + acts as a table of contents (TOC). QDoc generates navigation links + for pages listed in the TOC, without the need for + \l {nextpage-command}{\\nextpage} and \l {previouspage-command} + {\\previouspage} commands, as well as a navigation hierarchy that's + visible in the navigation bar (breadcrumbs) for HTML output. + \row \li \c navigation.toctitles.inclusive (Since QDoc 6.3) + \li If set to \c true, page(s) listed in \c navigation.toctitles + will also appear in the navigation bar as a root item. + \row \li \c navigation.trademarkspage (Since QDoc 6.8) + \li Title of a page that documents trademarks mentioned in the + documentation. See also \qdoccmd tm command. + \endtable + + For example: + + \badcode + # Common configuration + navigation.homepage = index.html + navigation.hometitle = "Qt $QT_VER" + + # qtquick.qdocconf + navigation.landingpage = "Qt Quick" + navigation.cppclassespage = "Qt Quick C++ Classes" + navigation.qmltypespage = "Qt Quick QML Types" + \endcode + + The above configuration produces the following navigation bar for \c Item QML type: + + \badcode + Qt 5.10 > Qt Quick > QML Types > Item QML Type + \endcode + + \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(s) of + the generated documentation. + + Since Qt 5.11, QDoc supports the HTML and WebXML formats; since + Qt 5.15, it can also generate the documentation in DocBook. If no + \c outputformats are specified, QDoc generates the documentation + in HTML (the default format). All output formats can be specified, + with dedicated output directories and other settings. For example: + + \badcode + outputformats = WebXML HTML + WebXML.nosubdirs = true + WebXML.outputsubdir = webxml + WebXML.quotinginformation = true + \endcode + + This generates HTML documentation using the default settings, as well + as WebXML documentation into output subdirectory \e webxml. + + \target outputprefixes-variable + \section1 outputprefixes + + The \c outputprefixes variable specifies a mapping between types of files + and the prefixes to prepend to the output file names in the generated + documentation. + + QDoc supports adding an output prefix to the file names of QML type, C++ + class, namespace, and header file reference pages. + + \badcode + outputprefixes = QML CPP + outputprefixes.QML = uicomponents- + outputprefixes.CPP = components- + \endcode + + By default, files containing the API documentation for QML types + are prefixed with \c {qml-}. In the above example, the prefix \c + {uicomponents-} is used instead. + + Likewise, C++ type documentation pages are prefixed with \c {components-} + in the above example. By default, C++ type pages have no prefix. + + \target outputsuffixes-variable + \section1 outputsuffixes + + The \c outputsuffixes variable specifies a mapping between types of + files and suffixes to apply to the module or type name as they appear + in the output file names. + + QDoc supports adding an output suffix to the file names of module pages, + QML type, C++ class, namespace, and header file reference pages. + + By default, no suffix is used. The QML output suffix, if defined, is + applied as a suffix to the module name as it appears in the file names + of QML type and QML module pages. + + File names for C++ types do not include the module name. The CPP + output suffix, if defined, is applied as a suffix for the type name. + + \badcode + outputsuffixes = QML CPP + {outputsuffixes.QML,outputsuffixes.CPP} = -tp + \endcode + + With the definitions above, given a QML module name \e FooBar and the default + \l {outputprefixes-variable}{output prefix} (\c {qml-}), the name of + the generated file for a QML type \e FooWidget is + \c qml-foobar-tp-foowidget.html. + + Likewise, for a C++ class \e QFoobar, QDoc generates \c qfoobar-tp.html. + + The \c outputsuffixes variable was introduced in QDoc 5.6. + + \target qhp-variable + \section1 qhp + + The \c qhp sub-variables are 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. + + Since QDoc 6.6, setting the base \c qhp variable to \c true means + that a valid help project configuration is expected: + + \badcode + qhp = true + \endcode + + Then, if a project configuration did not define \c {qhp.projects}, + QDoc issues a warning. This is useful for ensuring that all + documentation projects with a shared top-level \e .qdocconf file + (as in Qt) are configured correctly. + + To turn off the warning, set the variable to \c false. + + \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 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, *.cxx, *.mm, *.qml + and *.qdoc. + + 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 "5.14.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}. + + \target warninglimit-variable + \section1 warninglimit + + The \c warninglimit variable sets the maximum number of documentation + warnings allowed. If this limit is exceeded, QDoc continues as normal + but exits with the warning count as the error code. If the limit was + not exceeded or \c warninglimit was not defined, QDoc process exits + with 0, assuming there were no other critical errors. + + Setting the \c warninglimit to \c 0 means failure on any warning. + + \note By default, QDoc does not enforce the warning limit. Enable it + with \c {warninglimit.enabled = true} or by defining + the \c QDOC_ENABLE_WARNINGLIMIT environment variable. + + For example, + + \badcode + # Fail the documentation build if we have more than 100 warnings + warninglimit = 100 + warninglimit.enabled = true + \endcode + + The \c warninglimit variable was introduced in Qt 5.11. +*/ + +/*! + \page 22-creating-help-project-files.html + \previouspage Generic Configuration Variables + \nextpage Format-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. + + 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.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[:name] \li C++ modules or members of the module + with a specified name. + \row \li \c qmlmodule[:name] \li QML modules or members of the module + with a specified name. + \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 24-qdoc-configuration-htmlvariables.html + \previouspage Creating Help Project Files + \nextpage Supporting Derived Projects + + \keyword HTML Specific Configuration Variables + \title Format-specific Configuration Variables + + The format-specific configuration variables define the generated + documentation's style, or define the contents of the + documentation's footer or postheader. + + Some of the configuration values are relevant only for the HTML + output format and their values contain 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 FORMAT.nosubdirs + \section1 <FORMAT>.nosubdirs + + A boolean value which, when \c true, enables single-directory output + mode; all generated files go to \l {FORMAT.outputsubdir} directory, + instead of a subdirectory based on the documentation project name. + + \target FORMAT.outputsubdir + \section1 <FORMAT>.outputsubdir + + Defines the subdirectory under \l outputdir where documentation is + generated. + + \badcode + HTML.nosubdirs = true + HTML.outputsubdir = html + \endcode + + With above, the output goes to \c {<outputdir>/html}. + + \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 FORMAT.quotinginformation + \section1 <FORMAT>.quotinginformation + + A boolean value which, when \c true, generates references to + quoted content (for example, \l {quotefromfile-command}{\\quotefromfile} + and \l {snippet-command}{\\snippet} commands) instead of including + the content directly. + + Used currently for the \c WebXML output format. + + \badcode + WebXML.quotinginformation = true + \endcode + + \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 = path/to/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 <FORMAT>.tocdepth + + The \c {<FORMAT>.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 leaving it undefined prints all document + sections. + + Currently only has an effect for the HTML format: + + \badcode + HTML.tocdepth = 3 + \endcode +*/ + +/*! + \page 25-qdoc-configuration-derivedprojects.html + \previouspage Format-specific Configuration Variables + \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 defines a set of paths to index files to load. + + \badcode + indexes = \ + $QT_INSTALL_DOCS/qtcore/qtcore.index \ + $SOME_OTHER_PROJECT/doc/foo.index + \endcode + + The \c indexes variable provides an alternative to \l depends for + defining project's dependencies. As direct paths are provided, no + \c -indexdir command line option(s) are required when invoking QDoc. + + It is possible to define dependencies using either variable. Qt + documentation only uses the \c depends variable. + + See also \l depends, \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. This is a mandatory variable that all + projects must set. + + 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. + + If the project name contains whitespace or special characters, + these are replaced with dashes ('-') in the generated index file + name. + + See also \l depends, \l indexes, and \l description. + + \target url-variable + \section1 url + + The \c url variable holds the base URL for the + 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 = QtCore + description = Qt Core Reference Documentation + url = https://doc.qt.io/qt/ + + ... + \endcode + + This ensures that whenever QDoc generates + references to entities in the Qt Core module, the base URL is + \c https://doc.qt.io/qt/. + + See also \l depends, \l indexes and \l {url.examples}. + + \target url.examples-variable + \section1 url.examples + + The \c url.examples variable holds the base URL for the examples + associated with the current project. + + If defined, a link to the example project directory is generated + at the end of each example documentation page. The \c url.examples + variable refers to the root directory of the examples related to + this project; it can be a link to an online repository (starting + with \e http:// or \e https://), or to the local file system + (\c file://). + + If \c url.examples is not defined, QDoc will output a list of + example's files and images instead. + + For example, given these definitions: + + \badcode + url.examples = "https://code.qt.io/cgit/qt/qtbase.git/tree/examples/" + examplesinstallpath = corelib + \endcode + + Then, for the following \l {example-command}{\\example} command: + + \badcode * + /\1! + \example threads/semaphores + ... + \1/ + \endcode + + QDoc generates a link to + \c https://code.qt.io/cgit/qt/qtbase.git/tree/examples/corelib/threads/semaphores. + + If the URL contains more components (for example, a query string) + after the example path, \\1 can be used as a placeholder for the + path: + + \badcode + url.examples = "https://code.qt.io/cgit/qt/qtbase.git/tree/examples/\1?h=$QT_VER" + examplesinstallpath = corelib + \endcode + + Given the same \\example command as above and assuming that + \c $QT_VER expands to \c {5.13}, the generated URL is + \c https://code.qt.io/cgit/qt/qtbase.git/tree/examples/corelib/threads/semaphores?h=5.13. + + \c {url.examples} variable was introduced in QDoc version 5.13. + + See also \l url, \l examplesinstallpath, and \l {example-command}{\\example}. + + \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 GUI) + contains the following variable definitions: + + \badcode + project = QtGui + description = Qt GUI Reference Documentation + url = http://doc.qt.io/qt/ + + ... + \endcode + + The \l project variable name is used to form a file name for the + index file; in this case the \c qtgui.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. + + See also \l depends, \l indexes, \l project, and \l url. +*/ + +/*! + \page 26-qdoc-configuration-example-manifest-files.html + \previouspage Supporting Derived Projects + + \title Example Manifest Files + + QDoc generates example-manifest.xml files that contain information about + all documented examples. These files 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" + 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.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" \ + "QtWidgets/Analog Clock" + 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 = qt6 + \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-1-minimum-qdocconf.html + \previouspage qtgui.qdocconf + \nextpage The QDoc Configuration File + + \title minimum.qdocconf + + \quotefile examples/minimum.qdocconf +*/ + +/*! + \page 21-2-qtgui-qdocconf.html + \previouspage Supporting Derived Projects + \nextpage minimum.qdocconf + + \title qtgui.qdocconf + + \quotefile files/qtgui.qdocconf +*/ diff --git a/src/qdoc/qdoc/doc/qdoc-manual-topiccmds.qdoc b/src/qdoc/qdoc/doc/qdoc-manual-topiccmds.qdoc new file mode 100644 index 000000000..c1e6c2e5c --- /dev/null +++ b/src/qdoc/qdoc/doc/qdoc-manual-topiccmds.qdoc @@ -0,0 +1,1049 @@ +// Copyright (C) 2016 The Qt Company Ltd. +// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only + +/*! + \page 13-qdoc-commands-topics.html + \previouspage Command Index + \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. + + \badcode * + /\1! + \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. + \1/ + \endcode + + The \c PreviewWindow::setWindowFlags() and \c + ControllerWindow::setWindowFlags() functions will get the same + documentation. + + \section2 Nomenclature for files generated by topic commands + + For many topic commands, such as \l {page-command}{\\page}, QDoc + generates a file when processing the documentation. + + QDoc normalizes the name of each file before writing it to disk. + The following operations are performed: + + \list + \li All sequences of non alphanumeric characters are replaced with a hyphen, '-'. + \li All uppercase letters are replaced with their lowercase equivalent. + \li All trailing hyphens are removed. + \endlist + + For example, the following command generates a file named + \c{this-generates-a-file-and-writes-it-to-disk.html}: + + \badcode + \page this_generates_a_file_(and_writes_it_to_DISK)-.html + \endcode + + As the example shows, the name that is given to the file in the + command might differ from the name of the actual file that is + written to disk. + + \section3 Prefixes and Suffixes for generated files + + When QDoc generates a file, it may add a prefix, a suffix, or both, + depending on the element that the file will document. + + The table below shows what those prefixes and suffixes are for + various elements. + + \table + \header + \li Element + \li Prefix + \li Suffix + \li Command + \row + \li QML Modules + \li None + \li "-qmlmodule" + \li \l {qmlmodule-command}{\\qmlmodule} + \row + \li Modules + \li None + \li "-module" + \li \l {module-command}{\\module} + \row + \li Examples + \li The project name, as given by the \l + {project-variable}{project configuration variable}, + followed by a hyphen. + \li "-example" + \li \l {example-command}{\\example} + \row + \li QML Types + \li The output prefix for QML, as given by the \l + {outputprefixes-variable}{outputprefixes configuration + variable}. + + If the module that contains this type is known to QDoc, + the module name is added as a prefix, followed by the QML + output suffix, as defined by the \l + {outputsuffixes-variable}{outputsuffixes configuration + variable} and a hyphen. + \li None + \li \l {qmltype-command}{\\qmltype} + \endtable + + \target class-command + \section1 \\class + + The \\class command is for documenting a C++ \e class, a C/C++ + \e struct, or a \e union. The argument is the complete, qualified + name of the class. The command tells QDoc that a class is part of + the public API, and lets you enter a detailed description. + + \badcode * + /\1! + \class QMap::iterator + \inmodule QtCore + + \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 ... + \1/ + \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 qualifiers replaced with '-'. For example, the + documentation for the \c QMap::iterator class is written to \c + qmap-iterator.html. + + 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 an \l {inmodule-command} {\\inmodule} + command, as well as a \l {brief-command} {\\brief} description. + Here is a very simple example: + + \badcode * + /\1! + \class PreviewWindow + \inmodule CustomWidgets + \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 + \1/ + \endcode + + The way QDoc renders this \\class depends on your \c {style.css} + file. + + \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: + + \badcode * + /\1! + \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 + Bottom-right (omitted; not documented). + \1/ + \endcode + + Note the inclusion of the namespace qualifier. + + 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 one of the paths listed in the + \l {exampledirs-variable} {exampledirs} variable in the QDoc + configuration file. + + The documentation page will be output to \c {modulename-path-to-example}.html. + QDoc will add a list of all the example's source and images files at the end + of the page, unless \l {noautolist-command}{\\noautolist} command is used or + the configuration variable \l {url.examples-variable}{url.examples} is defined + for the project. + + For example, if \l {exampledirs-variable} {exampledirs} contains + \c $QTDIR/examples/widgets/imageviewer, then + + \badcode * + /\1! + \example widgets/imageviewer + \title ImageViewer Example + \subtitle + + The example shows how to combine QLabel and QScrollArea + to display an image. + + ... + \1/ + \endcode + + \b {See also:} \l {noautolist-command}{\\noautolist}, + \l {url.examples-variable}{url.examples}, + \l {meta-command}{\\meta} + + \target externalpage-command + \section1 \\externalpage + + The \\externalpage command assigns a title to an external URL. + + \badcode * + /\1! + \externalpage http://doc.qt.io/ + \title Qt Documentation Site + \1/ + \endcode + + This allows you to include a link to the external page in your + documentation this way: + + \badcode * + /\1! + At the \l {Qt Documentation Site} you can find the latest + documentation for Qt, Qt Creator, the Qt SDK and much more. + \1/ + \endcode + + To achieve the same result without using the \\externalpage + command, you would have to hard-code the address into your + documentation: + + \badcode * + /\1! + 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. + \1/ + \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 template parameters (if + any), return type, const-ness, and list of formal arguments with + types. If the named function doesn't exist, QDoc emits a warning. + + Since QDoc version 6.0, the \\fn command can be used for documenting + class members that are not explicitly declared in the header, + but are implicitly generated by the compiler; default constructor + and destructor, copy constructor and move-copy constructor, + assignment operator, and move-assignment operator. + + When documenting an hidden friend, it is required to prepend the + enclosing class name to the function name. + For example, for: + + \code + class Foo { + ... + friend bool operator==(const Foo&, const Foo&) { ... } + ... + } + \endcode + + The command should be written as \c{"\fn Foo::operator==(const + Foo&, const Foo&)"} and not as the free function \c{"\fn + operator==(const Foo&, const Foo&)"}. + + Failure to do so will have QDoc complaining about being unable to + resolve the function. + + \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. + + \badcode * + /\1! + \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. + \1/ + \endcode + + \note Running in debug mode (pass the \c {-debug} command line option + or set the \c QDOC_DEBUG environment variable before invoking QDoc) + can help troubleshoot \\fn commands that QDoc fails to parse. In + debug mode, additional diagnostic information is available. + + See also \l {overload-command} {\\overload}. + + \target group-command + \section1 \\group + + The \\group command creates a separate page that lists the classes, + pages, or other entities belonging to a named 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 an \c {.html} file named + <lower-case-group-name>.html. + + Each entity in the group is listed as a link (using page title + or class name), followed by a decription from the \l {brief-command} + {\\brief} command in the entity's documentation. + + \badcode * + /\1! + \group io + \title Input/Output and Networking + \1/ + \endcode + + QDoc generates a group page \c{io.html}. + + Note that overview pages related to the group must be listed + explicitly using the \l {generatelist-command} {\\generatelist} + command with the \c related argument. + + \badcode * + /\1! + \group architecture + + \title Architecture + + These documents describe aspects of Qt's architecture + and design, including overviews of core Qt features and + technologies. + + \generatelist{related} + \1/ + \endcode + + See also \l {ingroup-command} {\\ingroup}, \l {annotatedlist-command} + {\\annotatedlist}, \l {generatelist-command} {\\generatelist}, and + \l {noautolist-command}{\\noautolist}. + + \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. + + \badcode * + /\1! + \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. + \1/ + \endcode + + QDoc generates a header file page, \c{qtalgorithms.html}. + + See also \l {inheaderfile-command}{\\inheaderfile}. + + \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. + + \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: + + \badcode * + /\1! + \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. + \1/ + \endcode + + 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 reference page QDoc generates + for a namespace is similar to the reference page it generates for a + C++ class. + + \badcode * + /\1! + \namespace Qt + + \brief Contains miscellaneous identifiers used throughout the Qt library. + \1/ + \endcode + + Note that in C++, a particular namespace can be used in more + than one module, but when C++ elements from different modules + are declared in the same namespace, the namespace itself must + be documented in one module only. For example, namespace Qt in + the example above contains types and functions from both QtCore + and QtGui, but it is documented with the \\namespace command + only in QtCore. + + \target page-command + \section1 \\page + + The \\page command is for creating a stand-alone documentation + page. + + The \\page command expects a single argument that represents the + name of the file where QDoc should store the page. + + The page title is set using the \l {title-command} {\\title} + command. + + \badcode * + /\1! + \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, macOS, 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. + + ... + \1/ + \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. + + \badcode + 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 + description as the \l {variable-command} {\\variable} command. + + \badcode * + /\1! + \property QPushButton::flat + \brief Whether the border is disabled. + + This property's default is false. + \1/ + \endcode + + \target qmlattachedproperty-command + \section1 \\qmlattachedproperty + + The \\qmlattachedproperty command is for documenting a QML + property that will be attached to some QML type. See + \l{Attached Properties and Attached Signal Handlers} + {Attached Properties}. The argument is the rest of the line. + It must start with the property type, followed by the QML + type name where the property is declared, the \c{::} + qualifier, and finally the property name. + + For example, to document a boolean QML attached property named + \c isCurrentItem for the \c ListView type: + + \badcode * + /\1! + \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 + \1/ + \endcode + + QDoc includes this attached property on the QML reference page for the + \l [QML] {ListView} type. + + \note Like \l{qmlproperty-command}{\\qmlproperty}, \\qmlattachedproperty + accepts a QML module identifier as part of its argument. + + \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: + + \badcode * + /\1! + \qmlattachedsignal GridView::add() + This attached signal is emitted immediately after an item is added to the view. + \1/ + \endcode + + QDoc includes this documentation on the QML reference page for the + \l GridView element. + + \note Like \l{qmlproperty-command}{\\qmlproperty}, \\qmlattachedsignal accepts + a QML module identifier as part of its argument. + + \target qmlvaluetype-command + \section1 \\qmlvaluetype + + The \\qmlvaluetype command is for documenting a \l [QtQml] + {QML Value Types}{value type} for QML. The command takes + a type name as its only argument. + + \\qmlvaluetype is functionally identical to the + \l {qmltype-command}{\\qmltype} command. The only difference + is that the type will be titled (and grouped) as a + \e {QML value type}. + + \target qmlclass-command + \section1 \\qmlclass + + This command is deprecated. Use \l{qmltype-command} {\\qmltype} + instead. + + \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. + + \badcode * + /\1! + \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 + \1/ + \endcode + + QDoc includes this documentation on the element reference page for the + \l{http://doc.qt.io/qt-5/qml-qtquick-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 has an equivalent C++ class, you can specify that class + with the \qdoccmd nativetype context command. + + The \l {inqmlmodule-command}{\\inqmlmodule} command documents the + QML module the type belongs to. The argument passed to this command + must match with a documented \l {qmlmodule-command}{\\qmlmodule} + page. + + \badcode * + /\1! + \qmltype Transform + \nativetype QGraphicsTransform + \inqmlmodule QtQuick + + \brief Provides a way to build advanced transformations on Items. + + The Transform element is a base type which cannot be + instantiated directly. + \1/ + \endcode + + Here, the \e{\\qmltype} comment includes \qdoccmd nativetype + to specify that a Transform is the QML counterpart to 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: + + \badcode * + /\1! + \qmlproperty real Translate::x + + The translation along the X axis. + \1/ + \endcode + + QDoc includes this QML property on the QML reference page for the + \l [QML] {Translate} type. + + 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. + + QDoc accepts also a fully qualified property name, including the + QML module identifier: + + \badcode + \qmlproperty bool QtQuick.Controls::Button::highlighted + \endcode + + If specified, the module identifier (above, \c {QtQuick.Controls}) + must match with value passed to \l {inqmlmodule-command}{\\inqmlmodule} + command in the associated \\qmltype documentation. If the name of + the QML type the property belongs to is unique across all types in + the documentation project, the module identifier can be omitted. + + \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: + + \badcode * + /\1! + \qmlsignal MouseArea::clicked(MouseEvent mouse) + + This signal is emitted when there is a click. A click is defined as a + press followed by a release, both inside the MouseArea. + \1/ + \endcode + + QDoc includes this documentation on the QML reference page for the + \l [QML] {MouseArea} type. + + \note Like \l{qmlproperty-command}{\\qmlproperty}, \\qmlsignal + accepts a QML module identifier as part of its argument. + + \target qmlmodule-command + \section1 \\qmlmodule + + Use the \c{\qmlmodule} command to create a \c QML module page. A QML + module page is a collection of QML types or any related material. The + command takes an optional \c <VERSION> number argument, and is similar + to the \l{group-command}. + + A QML type is associated with a module by adding the + \l{inqmlmodule-command}{\\inqmlmodule} command to the comment-block that + documents the type. You can link to any member of a QML module using the + module name and two colons (\c{::}) prefix. + + \badcode * + /\1! + A link to the TabWidget of the UI Component is \l {UIComponent::TabWidget}. + \1/ + \endcode + + QDoc generates a page for the module that lists all the members of the + module. + + \badcode * + /\1! + \qmlmodule ClickableComponents + + This is a list of the Clickable Components set. A Clickable component + responds to a \c clicked() event. + \1/ + \endcode + + \target inqmlmodule-command + \section1 \\inqmlmodule + + A QML type is marked as being available under a specific QML module + import by inserting the \\inqmlmodule command in a + \l {qmltype-command}{\\qmltype} topic. The command takes the module + (import) name, without a version number, as the only argument. + + The QML module name must match with a QML module documented with + the (\l{qmlmodule-command}{\\qmlmodule} command). + + \badcode * + /\1! + \qmltype ClickableButton + \inqmlmodule ClickableComponents + + A clickable button that responds to the \c click() event. + \1/ + \endcode + + QDoc outputs a row \e {Import statement: import <qmlmodule>} + in a table at the top of the QML type reference page. + + When linking to QML types, the QML module identifier may appear in + the link target. For example: + + \badcode + \l {ClickableComponents::}{ClickableButton} + \endcode + + Links to the type reference page, with \e ClickableButton as the + link text. + + \target instantiates-command + \section1 \\instantiates + + The \\instantiates command is deprecated since Qt 6.8. + Use \qdoccmd nativetype instead. + + + \target nativetype-command + \section1 \\nativetype + + The \\nativetype-command must be used in conjunction with the + \qdoccmd qmltype topic command. The command takes a C++ class as its + argument. If QDoc cannot find the C++ class, it issues a warning. This + command was introduced with Qt 6.8. + + Use the \\nativetype-command to specify what the type is called in C++. + This ensures that the requisites block generated in the documentation for + the QML type contains an "In C++" entry. The C++ class will have a + corresponding "In QML" entry. + + Any one QML type can only have one native type. QDoc issues a warning if + redefinition occurs. However, multiple QML types can have the same C++ + class as their native type. The C++ class documentation will contain a list + of all corresponding types in QML. + + \badcode * + /\1! + \qmltype Transform + \nativetype QGraphicsTransform + \inqmlmodule QtQuick + + \brief Provides a way to build advanced transformations on Items. + + The Transform element is a base type which cannot be + instantiated directly. + \1/ + \endcode + + Here, the \e{\\qmltype} topic includes \e{\\nativetype} to specify that a + Transform is called QGraphicsTransform in C++. + + + \target typealias-command + \section1 \\typealias + + The \\typealias command is similar to \l {typedef-command}{\\typedef}, + but specific to documenting a C++ type alias: + + \code + class Foo + { + public: + using ptr = void*; + // ... + } + \endcode + + This can be documented as + + \badcode * + /\1! + \typealias Foo::ptr + \1/ + \endcode + + The \\typealias command was introduced in QDoc 5.15. + + See also \l {typedef-command}{\\typedef}. + + \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. + + \badcode * + /\1! + \typedef QObjectList + \relates QObject + + Synonym for QList<QObject>. + \1/ + \endcode + + Other typedefs are located on the reference page for the class + that defines them. + + \badcode * + /\1! + \typedef QList::Iterator + + Qt-style synonym for QList::iterator. + \1/ + \endcode + + See also \l {typealias-command}{\\typealias}. + + \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: + + \badcode * + /\1! + \variable QStyleOption::palette + \brief The palette that should be used when painting + the control + \1/ + \endcode + + 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: + + \badcode * + /\1! + \variable QTreeWidgetItem::Type + + The default type for tree widget items. + + \sa UserType, type() + \1/ + \endcode + + \badcode * + /\1! + \variable QTreeWidgetItem::UserType + + The minimum value for custom types. Values below + UserType are reserved by Qt. + + \sa Type, type() + \1/ + \endcode + +*/ diff --git a/src/qdoc/qdoc/doc/qdoc-manual.qdoc b/src/qdoc/qdoc/doc/qdoc-manual.qdoc new file mode 100644 index 000000000..da84fe430 --- /dev/null +++ b/src/qdoc/qdoc/doc/qdoc-manual.qdoc @@ -0,0 +1,59 @@ +// Copyright (C) 2016 The Qt Company Ltd. +// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only + +/*! + \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 {Macros} + \list + \li \l {CMake Text Snippets} + \li \l {HTML and DocBook Formatting} + \li \l {Product Names} + \li \l {Product Versions} + \li \l {Tabbed Content} + \li \l {youtube-macro}{Linking to YouTube content} + \li \l {Miscellaneous Macros} + \endlist + \li \l {The QDoc Configuration File} + \list + \li \l {Generic Configuration Variables} + \li \l {Creating Help Project Files} + \li \l {Format-specific Configuration Variables} + \li \l {Supporting Derived Projects} + \li \l {Example Manifest Files} + \li \l {qtgui.qdocconf} + \li \l {minimum.qdocconf} + \endlist + \li \l {How to Resolve QDoc Warnings} + \endlist +*/ + diff --git a/src/qdoc/qdoc/doc/qdoc-warnings.qdoc b/src/qdoc/qdoc/doc/qdoc-warnings.qdoc new file mode 100644 index 000000000..d5d399a05 --- /dev/null +++ b/src/qdoc/qdoc/doc/qdoc-warnings.qdoc @@ -0,0 +1,832 @@ +// Copyright (C) 2021 The Qt Company Ltd. +// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only + +/*! + \page qdoc-warnings.html + \previouspage Categories of Documentation + + \title How to Resolve QDoc Warnings + + QDoc may issue warnings when generating your documentation set. + This section describes what these warnings mean and how to resolve + them. This document does not describe warnings generated by Clang. + + \section1 Can't link to <target> + + QDoc issues this warning when one part of the documentation + (identified in the warning message) tries to refer to another, + but doesn't correctly specify that other, the target of the link. + This may arise because the reference to it is mistyped or because + the target has changed name (for a function or type) or title + (for another section). + + Search the source code for that particular link target. If you get no + results, gradually make the search less specific until you find a match. + + If the link target looks like the name of a type or function, + this could also be due to: + + \list + \li The name (or, for functions, where specified, signature) used + where it is documented not matching the name used in its + declaration. + \li The link target being marked as \l {internal-command}{\\internal} when the linking + text was not. + \endlist + + \section1 Found a \\target command outside table item in a table + + If QDoc encounters a \l {target-command}{\\target command} that is not + preceded by an \\li command within a \l {table-command} + {\\table ... \\endtable block}, it issues this warning. The warning is + followed by the text + \e {Move the \\target inside the \\li to resolve this warning}. + + \section1 Cannot find snippets file to quote from + + QDoc issues this warning if it is unable to find the file named + after a \l {snippet-command}{\\snippet} or \l {quotefromfile-command}{\\quotefromfile} command. + + Some useful steps for correcting this: + + \list + \li Check if the snippet file name is correct. QDoc appends the + snippet file name to each of the directories given in the + search path, to get a path-name for a candidate file to look + for. It produces this error when none of these candidates exist. + \li Check the search path for snippets, given by the \c exampledirs + configuration variable in the \c{*.qdocconf} file. You may need + to add an entry to this path, or correct an existing entry. + \li Check if the snippet file exists, or if it has been moved, renamed + or removed, which may happen when there are changes to the source + code that QDoc tries to quote from. + \endlist + + \section1 Unexpected \\snippet + + QDoc issues this warning if it is unable to locate the snippet file + quoted in a \l {snippet-command}{\\snippet} command. + + \section1 Undocumented QML <module> referred by <type> or its members + + QDoc issues this warning if it is unable to locate a QML module + based on the identifier passed to the + \l {inqmlmodule-command}{\\inqmlmodule} or \l {qmlproperty-command} + {\\qmlproperty} commands associated with a QML \e type. + + This means that either documentation for the \l {qmlmodule-command} + {\\qmlmodule} is missing, or an incorrect module identifier was + used in \\qmlproperty, \\qmlmethod, or \\qmlsignal command(s). + + \section1 No such <type> in QML <module> + + QDoc issues this warning if a \l {qmlproperty-command} {\\qmlproperty}, + \l {qmlmethod-command} {\\qmlmethod}, or \l {qmlsignal-command} + {\\qmlsignal} command argument uses a QML module identifier, but + the associated \l {qmltype-command}{\\qmltype} does not belong to + that module. + + The QML module identifier, if defined, \b must match with the + \l {inqmlmodule-command} {\\inqmlmodule} argument in the QML type + documentation. In most cases, QDoc is able to locate the QML type + without a module identifier. + + \section1 Undocumented return value + + For functions whose return-type is not void, QDoc checks if the return + value is documented. This warning is issued if the documentation for a + function or method doesn't contain a word starting with "return". + + \section1 Undocumented parameter + + QDoc requires the documentation of a function or method to describe + every parameter. It recognizes this by each parameter name (as + specified where the function or method is declared in a header file) + appearing after a \l {a-command}{\\a} command. + + This requirement is not imposed for function overload documentation, + provided that the overload is marked with the \qdoccmd overload command + and a fully-documented function with the same name exists. + + \section1 No such parameter + + QDoc issues this warning when the parameter name given after an + \l{a-command}{\\a} command does not match any of the parameters named + in the header-file's declaration of the function or method being + documented. + + \section1 Unknown macro + + QDoc issues this warning when it sees a backslash, \c{\}, followed + by a token it doesn't recognize as the name of either a built-in command + or a \l {macro-variable}{user-defined macro}. When quoting code + that contains character escape sequences, you should enclose the + code in \\c{...} to prevent this warning against the escape sequences. + + \section1 Failed to find function when parsing \\fn <signature> + + When Clang parses a function signature following an \qdoccmd fn command, + it checks this against the declaration in the header file. If Clang + discovers discrepancies, it issues this warning message. + + The signature must be fully qualified. Typical issues include missing or + incorrect template arguments, return type, or qualifiers such as + \e const. + + \note The \c{\fn} signature for a \e {hidden friend} should be + fully qualified with the scope of the class that declares + the function. + + \section1 QML type <TypeName> documented with <ClassName> as its native type. Replacing <ClassName> with <OtherClass> + If the \qdoccmd nativetype command is used with the same argument in + multiple QML type documentation comments that belong to the same + documentation project, QDoc issues this warning. To resolve this, ensure + that you use the \c {\nativetype} command only once for each C++ class. + + + \section1 Cannot tie this documentation to anything + + QDoc found a \beginqdoc ... \endqdoc comment, with no \l{Topic Commands}{topic command}, that was + not immediately followed by a class, function or property definition. + It thus does not know what the comment documents. + + \section1 This qdoc comment contains no topic command (e.g., \\module, \\page) + + If a QDoc comment doesn't contain a \l {Topic Commands}{topic command}, QDoc does + not know what the comment documents, and issues this warning. + Very similar to \l {Cannot tie this documentation to anything}, but + specific to comments that are not in C++ or QML files. + + \section1 <name> documented more than once + + QDoc issues this warning when it finds two comments that + document the same item. The location of the previously seen + comment is provided in warning details. + + For example, you see this warning when a function has a documentation + comment preceding its definition, and a separate \\fn comment + elsewhere. + + \section1 Namespace <name> documented more than once + + This warning means that a documentation set contains two comments + containing \l {namespace-command}{\\namespace} commands with the same + argument, <name>. + + \section1 <name> is documented, but namespace <namespace> is not documented in any module + + The documentation for \e {<name>} was found, but \e{<name>} is declared + under a namespace that is either undocumented or QDoc was unable to + locate the documentation for it. + + This can be resolved by either documenting \e{<namespace>}, or if it is + already documented in another module, ensure that this module has + a dependency to it. + + See also \l {depends-variable}{depends} and {indexes-variable}{indexes}. + + \section1 Has no \\inmodule command + + QDoc issues this warning if the QDoc comments do not relate + a class, namespace, or headerfile to a module with the + \l{inmodule-command}{\\inmodule} command. + + If the QDoc comment describes an entity that's not a member of + some other entity (typically a namespace or class), it should use + either \l {relates-command}{\\relates} or \l {inmodule-command}{\\inmodule} + to associate it with its broader context. This warning is raised + if it does not. + + \section1 Cannot find <name> specified with \\<command> in any header file + + This means that QDoc cannot find a declaration of <name> in any + header file, but has found a comment that claims to document it. + + An example: + \badcode + Cannot find 'Color::Red' specified with '\enum' in any header file. + \endcode + + A documentation comment claims to describe an enum, but QDoc didn't + find a definition of that enum in a header file. + + This may also be due to: + + \list + \li a typo in <name> or <command> + \li a missing namespace-or-class prefix + \li <name> having moved to another namespace or class + \endlist + + \section1 Unrecognizable QML module/component qualifier for <identifier> + + A parameter passed to \l {qmlproperty-command}{\\qmlproperty} or + \l {qmlmethod-command}{\\qmlmethod} contains a combination of + qmlModule::qmlType::identifier that is not defined anywhere. + + Example: + \badcode + Unrecognizable QML module/component qualifier for real QtQuick::DragHandler::DragAxis::minimum + \endcode + + DragHandler doesn't have a property called DragAxis. + + \section1 Missing property type for <name> + + A declaration of a \l {qmlproperty-command}{\\qmlproperty} is missing its property type. + + The \\qmlproperty command expects to be followed by the property type, then the + fully-qualified name of the property (i.e. the name ::-joined after the name of the + class it belongs to). + + Incorrect: + \badcode + \qmlproperty MyWidget::count + \endcode + + Correct: + \badcode + \qmlproperty int MyWidget::count + \endcode + + \section1 QML property documented multiple times: <identifier> + + QDoc uses this warning when it finds two QDoc comments that document + the same QML property, either by appearing just before its definition, + or using the \l {qmlproperty-command}{\\qmlproperty} command. + + \section1 Command <command> not allowed with QML property commands + + Example: + + \badcode + \qmlproperty real QtQuick.Controls::RangeSlider::first.value + \qmlproperty real QtQuick.Controls::RangeSlider::first.position + \qmlproperty real QtQuick.Controls::RangeSlider::first.visualPosition + \qmlsignal void QtQuick.Controls::RangeSlider::first.moved() + \qmlsignal void QtQuick.Controls::RangeSlider::second.moved() + \endcode + + Error message: + + \badcode + Command '\\qmlsignal' not allowed with QML property commands + \endcode + + This warning is specific to property group documentation. QDoc + allows multiple qmlproperty or qmlattachedproperty topic commands + in a single documentation comment to document a property group + where the last element in the path is <group>.<property>. Any other topic + commands triggers this warning. + + \section1 Cannot find base function for <method> in <class> + + QDoc produces this warning if \\reimp is used to document a method, + as an override of a virtual method, when no base class has a virtual + method with the given name and signature. This may happen because + the method it was written to override has changed its signature, or is + no longer virtual. + + \section1 Illegal \\reimp; no documented virtual function for <command> + + Qdoc tries to create a link to the function that this one reimplements, + but it could not find the link target, likely because that + function is not documented. This can also arise if no base class + has a virtual method with this name and signature; which might + arise due to a renaming, a change in signature or the base no + longer declaring it virtual. + + \section1 <class> tries to inherit itself + + The \l {inherits-command}{\\inherits} command is used to document that a QMl type + inherits some other QML type. This warning is issued if that other + QML type is the same as the QML type documented. + + Example: + + \badcode + \qmltype Foo + \inherits Foo + \endcode + + \section1 \\nativetype is only allowed in \\qmltype + + The \l{nativetype-command}{\\nativetype} command can only be used in a QDoc + comment that documents a QML type. + + \section1 All properties in a group must belong to the same type: <name> + + When documenting QML property groups, all properties listed in + the comment block must belong to the same QML type. + + \section1 Cannot find project file for example <name> + + In the example's source directory, QDoc expects to find a project + file named \c{CMakeLists.txt}, or a file with a \c{.pro}, \c{.qmlproject}, or + \c{.pyproject} extension where the base name matches that of the example + directory. For example, \c {examples/mymodule/helloworld/helloworld.pro}. + + \section1 Cannot open file to quote from: <filename> + + The search path for <filename> is defined by the following + variables in the \c{.qdocconf} file: \c{sources}, \c{sourcedirs}, + and \c{exampledirs}. + + QDoc failed to find a file named in a command (such as + \l {quotefromfile-command}{\\quotefromfile}, + \l {snippet-command}{\\snippet}, \l {include-command}{\\include}) + that tells it to retrieve content from the named file. It searches + each directory named in the search path. If there is no file with + this name in any of those directories, or the file is found but not + readable, QDoc issues this warning. Check that the combination of + search path and <filename> is correctly spelled, and that you have + read permissions for the file. + + \note <filename> may include a directory name prefix; the whole + <filename> is appended to each directory in the search path. + + \sa {Cannot find qdoc include file <filename>} + + \section1 Missing format name after \\raw + + The \l {raw-command}{\\raw} command and the corresponding \l {raw-command}{\\endraw} + command delimit a block of raw mark-up language code. The \\raw + command must be followed by the format name. + + \section1 Macro cannot have both format-specific and qdoc-syntax definitions + + A \l {macro-variable}{\\macro} that specifies an output format cannot also + have a generic definition. + + An example of a configuration that triggers this warning: + + \badcode + macro.gui = \b + macro.gui.HTML = "<b>\1</b>" + \endcode + + \section1 Unknown command <name> + + When a QDoc comment uses a backslash followed by a token that is not a QDoc + built-in command and has not been defined as a custom command + \l {macro-variable}{macro}, QDoc produces this warning. Check the spelling + of the command name, and check whether your QDoc configuration doesn't + include whatever would have defined it, if it's a custom command. + + This may also be produced due to code being quoted in the QDoc comment, + for example the author may have referred to the C string termination + character \c{'\0'} or one of the other C string escape sequences such + as \c{'\n'} without escaping the backslash. Escape the backslash + as \c{\} to include a literal backslash in the documentation, or + enclose the code fragment in \c{\c{...}}, which suppresses + interpretation of backslashes as introducing QDoc commands. + + \section1 Duplicate target name <target> + + This warning is issued if you define two targets with the same parameter, + using either the \l {target-command}{\\target} or the \l {keyword-command} + {\\keyword} command. The target name given as parameter to these commands + must be unique. The warning is followed by "The previous occurrence is + here: [location]", where location contains a file name and line number. + + \section1 Cannot find qdoc include file <filename> + + QDoc failed to find an include file named in a command. + QDoc searches each directory named in the search path. + If there is no file with this name in any of those directories, + or the file found in that search is not readable, QDoc issues + this warning. Check that the combination of search path and + <filename> is correctly spelled, and that you have read permissions + for the file. + + \note <filename> may include a directory name prefix; the whole + <filename> is appended to each directory in the search path. + + \sa {Cannot open file to quote from: <filename>} + + \section1 Cannot find <tag> in <file> + + This means QDoc cannot find the identifier <id> in the + \l{include-command}{\\include} <file> or {snippet-command}{\\snippet} <file>. + + \section1 Empty qdoc snippet <tag> in <file> + + The snippet <tag> was found in the \l {snippet-command}{\\snippet} <file>, but it is empty. + + \section1 Cannot nest <command> commands + + This warning concerns formatting commands: bold, italic, + index, link, span, subscript, superscript, teletype, uicontrol, + underline. A formatting command cannot be used within the text + it applies to. An example of this: + + \badcode + There is \b{no \b{super-}bold}. + \encode + + \section1 Can't use <inner> in <outer> + + This warning is issued for commands that cannot be nested. + + Example: + \badcode + \list + \li \table + \row \li Hello \li Hi + \endtable + \endlist + \endcode + + Results in the QDoc warning "Can't use '\\table' in '\\list'". + + \section1 Missing <outer> before <inner> + + Some examples: + + \list + \li The \l {li-command}{\\li} command can only be used inside a \l {list-command}{\\list} + or a \l {row-command}{\\row} of a \l {table-command}{\\table}. + \li The \l {row-command}{\\row} and \l {header-command}{\\header} commands can only be + used within a \l {table-command}{\\table}. + \endlist + + \section1 Unexpected <end_command> + + This warning is issued if, for example, you have an \l {list-command}{\\endlist} without + a preceding \l {list-command}{\\list}. It applies to all commands that come in pairs (e.g. + startFoo/endFoo). + + \section1 Missing comma in \\sa + + The titles listed for a \l {sa-command}{\\sa} command should be separated + from one another with commas. + + \section1 Macro <command> does not have a default definition + + QDoc is attempting to expand a macro, and expects that macro to + have a default definition. Some macros may only have format-specific + definitions. + + Example: + \badcode + macro.pi.HTML = "π" # encodes the pi symbol for HTML output format + \endcode + + There are however instances where macro expansion requires a + format-independent macro. For example, you can have macros in + section titles, but they must have default definitions. + + \section1 Macro <macro> invoked with too few arguments (expected <many>, got <few>) + + The given macro needs more parameters than it was given. See + the definition of the macro in the configuration for further + details. + + \section1 Unbalanced parentheses in <text> + + Points to a '(' without a corresponding ')', or vice versa. + + \section1 No documentation for <name> + + Example: + + \badcode + Warning "No documentation for QNativeInterface." + \endcode + + QDoc detects the declaration of namespace QNativeInterface in + a header file, but does not find a QDoc comment where that + namespace has been documented. + + \section1 No such enum item <name> in <class> + + Example: + + \badcode + Cannot find 'QSGMaterialRhiShader::RenderState::DirtyState' specified + with \enum in any header file. + \endcode + + QDoc issues this warning when it finds a \l{value-command}{\\value} directive in an + \l{enum-command}{\\enum} comment that names a value not found in the header file that declared + the enumerated type documented. + + \section1 Undocumented enum item <enum> in <enum list> + + <enum list>'s \l {value-command}{\\value} or \l {omitvalue-command}{\\omitvalue} entries + did not include one for \l {enum-command}{<enum>}, which is named in the + declaration of <enum list> in the header file. + + \section1 Failed to find index: <filename> + + Example: + + \badcode + Failed to find index: path/to/QtCrator/appmanplugin/manual.index + \endcode + + In this case, it clearly means the indexes variable contains a + typo in the path of the index file. + + Incorrect: + \badcode + indexes += path/to/QtCrator/appmanplugin/manual.index + \endcode + + Correct: + \badcode + indexes += path/to/QtCreator/appmanplugin/manual.index + \endcode + + \section1 \\generatelist <group> is empty + + Below a short overview of all possible arguments for \l {generatelist-command}{\\generatelist}: + \list + \li \\generatelist annotatedexamples + \li \\generatelist annotatedattributions + \li \\generatelist classes <prefix> + \li \\generatelist classesbymodule <module name> + \li \\generatelist qmltypesbymodule <module name> + \li \\generatelist functionindex + \li \\generatelist legalese + \li \\generatelist overviews + \li \\generatelist attributions + \li \\generatelist related + \endlist + + QDoc issues this warning if you specify \c{\generatelist <group>} + and the group does not contain any items, or if you specify + \c{\generatelist <group> <pattern>} and no item in the group + matches the pattern. + + \section1 \\generatelist <group> no such group + + This warning issues if the argument to \l {generatelist-command}{\\generatelist} + is a non-existing group. + + Example: + + \code + \generatelist draganddrop + \endcode + + This statement generates a list of classes or QML types in the + draganddrop group. Classes or QML types are added to the + draganddrop group by the \c{\l {ingroup-command}{\ingroup} draganddrop} command in their + \l {class-command}{\\class} or \l {qmltype-command}{\\qmltype} comment. + + QDoc issues this warning message if no entity has + this \c{\ingroup draganddrop} statement. + + \section1 Missing image: <imagefile> + + The search path to the image is wrong, or the image file does not exist. + + \section1 Can't link to <target> + + This can have a variety of causes: + + \list + \li The link target has not been defined with a QDoc topic command, + e.g. {title-command}{\\title} <target>. + \li The <target> contains a typo. + \li The document that contains that link target did not get compiled. + \li The document that contains that link target is in a module that is + not in the compilation path. + \li The link target is in another module, and a dependency to that + module was not set in the configuration or QDoc failed to locate + the index file for the dependency. + \endlist + + \section1 Could not resolve QML import statement for type <name> + + QDoc issues this warning if you document a QML type, but omit + the \l{inqmlmodule-command}{\\inqmlmodule} command. + Example: + + \badcode + Could not resolve QML import statement for type 'ItemSelectionModel' + \encode + + Incorrect: + \badcode + \qmltype ItemSelectionModel + \nativetype QItemSelectionModel + \since 5.5 + \ingroup qtquick-models + \endcode + Correct: + \badcode + \qmltype ItemSelectionModel + \nativetype QItemSelectionModel + \inqmlmodule QtQml.Models + \since 5.5 + \ingroup qtquick-models + \endcode + + \section1 \\brief statement does not end with a full stop + + The argument to the \\brief command is a sentence, summarizing + the topic documented, so should end in a full stop. It should + also be brief. + + \section1 QtDeclarative not installed; cannot parse QML + + QDoc issues this warning if it has been compiled without support + for QML parsing. This should not happen unless you have a + custom build of QDoc. + + \section1 Invalid regular expression <regex> + + Some QDoc commands take regular expressions as parameters. QDoc + gives this warning when the text given as such a parameter is not + a valid regular expression, usually due to it containing characters + with special meanings in regular expressions, that should have been + escaped. + + Example: + + \badcode + notifications.qdoc:56: (qdoc) warning: Invalid regular expression '^})$' + \endcode + + \badcode + \quotefromfile webenginewidgets/notifications/data/index.html + \skipuntil resetPermission + \endcode + + Invalid regular expression: + \badcode + \printuntil /^})$/ + \endcode + + Valid regular expression: + \badcode + \printuntil /^\}\)$/ + \endcode + + + The \l {printuntil-command}{\\printuntil} command prints until it + meets a line consisting of only a right curly brace followed by a + right parenthesis. In this case, the curly brace and the parenthesis + need to be escaped because they have special meanings in regular + expressions. + + \section1 Multiple index files found for dependency <indexfile>:<depend> + Using <indexfile> as index file for dependency <depend> + + Multiple \c{-indexdir} paths were passed to QDoc as command line options, + and more than one contained an \c{.index} file that matches a dependency. + QDoc picks the one with the latest timestamp automatically. + + Typically, this warning indicates that there are build artifacts left + from a previous documentation build. + + \section1 Cannot locate index file for dependency <depend> + + Example: + + \badcode + "QMake" Cannot locate index file for dependency "activeqt" + \endcode + + The documentation project QMake could not locate activeqt.index + in any of the specified index directories. In this case, the + specified index directories are specified in qmake.qdocconf. + + \section1 Dependent modules specified, but no index directories were set. + + QDoc expected to see one or more -indexdir arguments on the command line. + Without them, QDoc cannot locate the index files of any dependencies + defined with the 'depends' configuration variable. + + \section1 Overrides a previous doc + + QDoc issues this warning when it finds two comments that appear to + describe the same entity. The location of the previously seen + comment is provided in warning details. + + \section1 Unrecognized list style <name> + + \\list can take an optional argument: a single number or character + that modifies the list style. Refer to the {list-command}{\\list} + documentation for more details. If you use an argument that is + not recognized, QDoc issues this warning. + + \section1 Unable to parse QML snippet: <code> at line <y>, column <x> + + QDoc comments can contain QML code. This code can be found in a snippet, + or in the QDoc comments delimited by \l {qml-command}{\\qml} and {endqml-command}{\\endqml}. + + Example: + + If there is a syntax error in the QML code, QDoc issues the warning + \badcode + Unable to parse QML snippet: Syntax error at line 97, column 42 + \endcode + + Snippets can also contain QML and also there the code is checked. If there is + for example a missing curly brace in the code, QDoc issues the warning + \badcode + Unable to parse QML snippet: Expected token '{' at line 63, column 52 + \endcode + + QDoc often fails to parse incomplete QML snippets; in these cases, + it's often OK to replace the \\qml ... \\endqml commands with + \\code ... \\endcode to suppress this warning. + + \section1 Command <command> failed at end of file <filename> + + Example: + + \badcode + Command "\snippet (//! [2]) failed at end of file qmlbars/qml/qmlbars/main.qml". + \endcode + + In this case the warning means that the \l {snippet-command}{\\snippet} command did not find a second + label "\/\/! [2]" to mark the end of the snippet. It could also mean that it didn't + find any occurrence of that snippet tag in this snippet file. + + Another example: + + \badcode + Command '\skipto' failed at end of file 'styling/CMakeLists.txt". + \endcode + + The \l {skipto-command}{\\skipto} + <pattern> moves the cursor to the next line containing + that pattern. If \\skipto doesn't find it, QDoc issues this warning. + + \section1 Failed to open <file> for writing + + This warning clearly means it cannot open a file for writing, probably because + of a wrong path, or permission to write in a certain directory. + + \section1 This page title exists in more than one file + + The \l {title-command}{\\title} command sets the title for a page. + + \code + \page activeqt-server.html + \title Building ActiveX servers in Qt + \endcode + + QDoc issues this warning if a certain title is used in more than one page. + + + \section1 The content is too long + + QDoc uses a fixed-size buffer when tokenizing source files. If any single + token in the file has more characters than the maximum limit, QDoc issues + this warning. + + While QDoc continues parsing the file, only the part of the token that + fits into the buffer is considered, meaning that the output might be + mangled. + + To resolve this warning, the relevant content must be reduced in size, + either by splitting it, if possible, or by removing some of its parts. + + The maximum amount of characters for a single token is shown alongside + the warning, for example: + + \badcode + file.qdoc:71154: (qdoc) warning: The content is too long. + + [The maximum amount of characters for this content is 524288. + Consider splitting it or reducing its size.] + \endcode + + \note Since content that is too long is not parsed in full, QDoc may + issue warnings that are false positives. Resolve all warnings of this type + before fixing other warnings. + + \section1 No documentation generated for function <name> in global scope + + QDoc was able to match the documentation for a function \e {<name>} to its + declaration, but no output was generated because the function is declared + in the global namespace. + + Use the \l {relates-command}{\\relates} command to associate the function + with a documented type, namespace, or a header file. The function is then + listed as a \e {related non-member} on the associated reference page. + + \section1 Documentation configuration for <project> doesn't define a help project (qhp) + + A valid Qt help configuration was expected but not provided in the project's + .qdocconf file. + + See also \l{Creating Help Project Files} and \l {qhp-variable}{qhp}. + + \section1 Already generated FILE for this project + + While generating the documentation for a project, QDoc keeps track of the + file names of the files it has generated. QDoc will issue a warning when it + opens a file for writing if that file is known to have been generated + previously, in the current execution. This can happen if a \qdoccmd page + command uses the same name as \qdoccmd group, for example. + + You can set the environment variable \c QDOC_ALL_OVERWRITES_ARE_WARNINGS to + unconditionally warn about all such events. This may be useful when tracking + down the offending definitions. + +*/ diff --git a/src/qdoc/qdoc/doc/qtgui-qdocconf.qdoc b/src/qdoc/qdoc/doc/qtgui-qdocconf.qdoc new file mode 100644 index 000000000..b72f97271 --- /dev/null +++ b/src/qdoc/qdoc/doc/qtgui-qdocconf.qdoc @@ -0,0 +1,260 @@ +// Copyright (C) 2016 The Qt Company Ltd. +// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only + +/*! + +\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 + 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.subprojects = classes + qhp.QtGui.subprojects.classes.title = C++ Classes + qhp.QtGui.subprojects.classes.indexTitle = Qt GUI C++ Classes + qhp.QtGui.subprojects.classes.selectors = class headerfile + qhp.QtGui.subprojects.classes.sortPages = true + + tagfile = 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. + +\badcode + examplesinstallpath = gui +\endcode + +The \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. + +\note It is possible to override \c examplesinstallpath for a specific + \l {example-command}{\\example} using the \l {meta-command}{\\meta} + command. + +\b {See also}: \l {examplesinstallpath}, \l {exampledirs}, and +\l {meta-command}{\\meta}. + +\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.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. +*/ |
