summaryrefslogtreecommitdiffstats
diff options
context:
space:
mode:
-rw-r--r--doc/global/macros.qdocconf2
-rw-r--r--examples/widgets/dialogs/standarddialogs/dialog.cpp4
-rw-r--r--examples/widgets/doc/src/echoplugin.qdoc2
-rw-r--r--qmake/option.cpp3
-rw-r--r--src/corelib/doc/snippets/code/src_corelib_tools_qbytearray.cpp2
-rw-r--r--src/corelib/doc/src/objectmodel/signalsandslots.qdoc4
-rw-r--r--src/corelib/io/qdir.cpp2
-rw-r--r--src/corelib/itemmodels/qabstractitemmodel.cpp6
-rw-r--r--src/gui/image/qjpeghandler.cpp29
-rw-r--r--src/gui/kernel/qwindow.cpp5
-rw-r--r--src/gui/text/qdistancefield_p.h6
-rw-r--r--src/platformsupport/fontdatabases/fontconfig/qfontconfigdatabase.cpp8
-rw-r--r--src/plugins/platforms/cocoa/qnsview.h1
-rw-r--r--src/plugins/platforms/cocoa/qnsview.mm9
-rw-r--r--src/plugins/platforms/qnx/qqnxnativeinterface.cpp8
-rw-r--r--src/plugins/platforms/qnx/qqnxnativeinterface.h1
-rw-r--r--src/plugins/platforms/qnx/qqnxscreen.cpp5
-rw-r--r--src/plugins/platforms/qnx/qqnxscreen.h4
-rw-r--r--src/plugins/platforms/windows/qwindowsbackingstore.cpp4
-rw-r--r--src/plugins/platforms/windows/qwindowswindow.cpp3
-rw-r--r--src/tools/qdoc/doc/config/qdoc.qdocconf12
-rw-r--r--src/tools/qdoc/doc/examples/componentset/uicomponents.qdoc.sample (renamed from src/tools/qdoc/doc/examples/componentset/uicomponents.qdoc)0
-rw-r--r--src/tools/qdoc/doc/examples/cpp.qdoc.sample2
-rw-r--r--src/tools/qdoc/doc/examples/examples.qdoc16
-rw-r--r--src/tools/qdoc/doc/files/basicqt.qdoc.sample67
-rw-r--r--src/tools/qdoc/doc/qdoc-guide/qdoc-guide.qdoc89
-rw-r--r--src/tools/qdoc/doc/qdoc-guide/qtwritingstyle-cpp.qdoc6
-rw-r--r--src/tools/qdoc/doc/qdoc-manual-DITA.qdoc164
-rw-r--r--src/tools/qdoc/doc/qdoc-manual-cmdindex.qdoc159
-rw-r--r--src/tools/qdoc/doc/qdoc-manual-contextcmds.qdoc1076
-rw-r--r--src/tools/qdoc/doc/qdoc-manual-intro.qdoc181
-rw-r--r--src/tools/qdoc/doc/qdoc-manual-markupcmds.qdoc3967
-rw-r--r--src/tools/qdoc/doc/qdoc-manual-qdocconf-minimal.qdoc78
-rw-r--r--src/tools/qdoc/doc/qdoc-manual-qdocconf.qdoc1603
-rw-r--r--src/tools/qdoc/doc/qdoc-manual-topiccmds.qdoc1608
-rw-r--r--src/tools/qdoc/doc/qdoc-manual.qdoc8719
-rw-r--r--src/tools/qdoc/doc/qdoc-minimum-qdocconf.qdoc3
-rw-r--r--src/tools/qdoc/doc/qtgui-qdocconf.qdoc2
-rw-r--r--src/widgets/dialogs/qmessagebox.cpp11
-rw-r--r--src/widgets/doc/src/model-view-programming.qdoc4
-rw-r--r--src/widgets/kernel/qwidget_qpa.cpp5
-rw-r--r--src/widgets/styles/qcommonstyle.cpp5
-rw-r--r--src/widgets/styles/qwindowsstyle.cpp6
-rw-r--r--tools/configure/configureapp.cpp2
-rw-r--r--tools/configure/tools.cpp12
-rw-r--r--tools/configure/tools.h2
46 files changed, 8953 insertions, 8954 deletions
diff --git a/doc/global/macros.qdocconf b/doc/global/macros.qdocconf
index fd3707a27c..58d9a71c8c 100644
--- a/doc/global/macros.qdocconf
+++ b/doc/global/macros.qdocconf
@@ -29,6 +29,8 @@ macro.endcomment = "\\c{*/}"
macro.uuml.HTML = "ü"
macro.mdash.HTML = "—"
macro.pi.HTML = "Π"
+macro.beginqdoc.HTML = "/*!"
+macro.endqdoc.HTML = "*/"
macro.beginfloatleft.HTML = "<div style=\"float: left; margin-right: 2em\">"
macro.beginfloatright.HTML = "<div style=\"float: right; margin-left: 2em\">"
diff --git a/examples/widgets/dialogs/standarddialogs/dialog.cpp b/examples/widgets/dialogs/standarddialogs/dialog.cpp
index fdd3633950..3630f48ef3 100644
--- a/examples/widgets/dialogs/standarddialogs/dialog.cpp
+++ b/examples/widgets/dialogs/standarddialogs/dialog.cpp
@@ -47,6 +47,9 @@
"and any number of buttons, each with standard or custom texts." \
"<p>Click a button to close the message box. Pressing the Esc button " \
"will activate the detected escape button (if any).")
+#define MESSAGE_DETAILS \
+ Dialog::tr("If a message box has detailed text, the user can reveal it " \
+ "by pressing the Show Details... button.")
class DialogOptionsWidget : public QGroupBox
@@ -466,6 +469,7 @@ void Dialog::warningMessage()
{
QMessageBox msgBox(QMessageBox::Warning, tr("QMessageBox::warning()"),
MESSAGE, 0, this);
+ msgBox.setDetailedText(MESSAGE_DETAILS);
msgBox.addButton(tr("Save &Again"), QMessageBox::AcceptRole);
msgBox.addButton(tr("&Continue"), QMessageBox::RejectRole);
if (msgBox.exec() == QMessageBox::AcceptRole)
diff --git a/examples/widgets/doc/src/echoplugin.qdoc b/examples/widgets/doc/src/echoplugin.qdoc
index 2c56a2f53b..9e2b0c35de 100644
--- a/examples/widgets/doc/src/echoplugin.qdoc
+++ b/examples/widgets/doc/src/echoplugin.qdoc
@@ -145,7 +145,7 @@
plugin. The Q_INTERFACES macro tells Qt which interfaces the class
implements. In our case we only implement the \c EchoInterface.
If a class implements more than one interface, they are given as
- a comma separated list. The Q_PLUGIN_METADATA macro is included next
+ a space separated list. The Q_PLUGIN_METADATA macro is included next
to the Q_OBJECT macro. It contains the plugins IID and a filename
pointing to a json file containing the metadata for the plugin.
The json file is compiled into the plugin and does not need to be installed.
diff --git a/qmake/option.cpp b/qmake/option.cpp
index 387d8ce375..da52542a7d 100644
--- a/qmake/option.cpp
+++ b/qmake/option.cpp
@@ -348,7 +348,8 @@ Option::init(int argc, char **argv)
continue;
QString candidate = currentDir.absoluteFilePath(*p + QLatin1Char('/') + argv0);
#ifdef Q_OS_WIN
- candidate += ".exe";
+ if (!candidate.endsWith(QLatin1String(".exe")))
+ candidate += QLatin1String(".exe");
#endif
if (QFile::exists(candidate)) {
globals->qmake_abslocation = candidate;
diff --git a/src/corelib/doc/snippets/code/src_corelib_tools_qbytearray.cpp b/src/corelib/doc/snippets/code/src_corelib_tools_qbytearray.cpp
index 4f8c4c095e..c2a375f498 100644
--- a/src/corelib/doc/snippets/code/src_corelib_tools_qbytearray.cpp
+++ b/src/corelib/doc/snippets/code/src_corelib_tools_qbytearray.cpp
@@ -427,7 +427,7 @@ ba2.constData(); // Returns "ca\0" with terminating \0.
QByteArray ba3("ca\0r\0t", 4);
ba3.size(); // Returns 4.
-ba2.constData(); // Returns "ca\0r" with terminating \0.
+ba3.constData(); // Returns "ca\0r" with terminating \0.
const char cart[] = {'c', 'a', '\0', 'r', '\0', 't'};
QByteArray ba4(QByteArray::fromRawData(cart, 6));
diff --git a/src/corelib/doc/src/objectmodel/signalsandslots.qdoc b/src/corelib/doc/src/objectmodel/signalsandslots.qdoc
index 4e285f2966..b86aae830f 100644
--- a/src/corelib/doc/src/objectmodel/signalsandslots.qdoc
+++ b/src/corelib/doc/src/objectmodel/signalsandslots.qdoc
@@ -79,7 +79,9 @@
signal must match the signature of the receiving slot. (In fact a
slot may have a shorter signature than the signal it receives
because it can ignore extra arguments.) Since the signatures are
- compatible, the compiler can help us detect type mismatches.
+ compatible, the compiler can help us detect type mismatches when
+ using the function pointer-based syntax. The string-based SIGNAL
+ and SLOT syntax will detect type mismatches at runtime.
Signals and slots are loosely coupled: A class which emits a
signal neither knows nor cares which slots receive the signal.
Qt's signals and slots mechanism ensures that if you connect a
diff --git a/src/corelib/io/qdir.cpp b/src/corelib/io/qdir.cpp
index 33cda4a447..cd30533ff8 100644
--- a/src/corelib/io/qdir.cpp
+++ b/src/corelib/io/qdir.cpp
@@ -284,8 +284,6 @@ bool QDirSortItemComparator::operator()(const QDirSortItem &n1, const QDirSortIt
? f1->filename_cache.localeAwareCompare(f2->filename_cache)
: f1->filename_cache.compare(f2->filename_cache);
}
- if (r == 0) // Enforce an order - the order the items appear in the array
- r = (&n1) - (&n2);
if (qt_cmp_si_sort_flags & QDir::Reversed)
return r > 0;
return r < 0;
diff --git a/src/corelib/itemmodels/qabstractitemmodel.cpp b/src/corelib/itemmodels/qabstractitemmodel.cpp
index 9791a02723..2ea560e611 100644
--- a/src/corelib/itemmodels/qabstractitemmodel.cpp
+++ b/src/corelib/itemmodels/qabstractitemmodel.cpp
@@ -1303,12 +1303,12 @@ void QAbstractItemModel::resetInternalData()
*/
/*!
- \fn bool QAbstractItemModel::moveRow(const QModelIndex &sourceParent, int sourceColumn, const QModelIndex &destinationParent, int destinationChild)
+ \fn bool QAbstractItemModel::moveRow(const QModelIndex &sourceParent, int sourceRow, const QModelIndex &destinationParent, int destinationChild)
- On models that support this, moves \a sourceColumn from \a sourceParent to \a destinationChild under
+ On models that support this, moves \a sourceRow from \a sourceParent to \a destinationChild under
\a destinationParent.
- Returns \c{true} if the columns were successfully moved; otherwise returns
+ Returns \c{true} if the rows were successfully moved; otherwise returns
\c{false}.
\sa moveRows(), moveColumn()
diff --git a/src/gui/image/qjpeghandler.cpp b/src/gui/image/qjpeghandler.cpp
index 443bb65de3..3f90bb42f0 100644
--- a/src/gui/image/qjpeghandler.cpp
+++ b/src/gui/image/qjpeghandler.cpp
@@ -160,11 +160,7 @@ static boolean qt_fill_input_buffer(j_decompress_ptr cinfo)
} else {
src->bytes_in_buffer = num_read;
}
-#if defined(Q_OS_UNIXWARE)
- return B_TRUE;
-#else
- return true;
-#endif
+ return TRUE;
}
static void qt_skip_input_data(j_decompress_ptr cinfo, long num_bytes)
@@ -363,7 +359,7 @@ static bool read_jpeg_image(QImage *outImage,
// If high quality not required, use fast decompression
if( quality < HIGH_QUALITY_THRESHOLD ) {
info->dct_method = JDCT_IFAST;
- info->do_fancy_upsampling = false;
+ info->do_fancy_upsampling = FALSE;
}
(void) jpeg_calc_output_dimensions(info);
@@ -496,11 +492,7 @@ static boolean qt_empty_output_buffer(j_compress_ptr cinfo)
dest->next_output_byte = dest->buffer;
dest->free_in_buffer = max_buf;
-#if defined(Q_OS_UNIXWARE)
- return B_TRUE;
-#else
- return true;
-#endif
+ return TRUE;
}
static void qt_term_destination(j_compress_ptr cinfo)
@@ -625,13 +617,8 @@ static bool write_jpeg_image(const QImage &image, QIODevice *device, volatile in
int quality = sourceQuality >= 0 ? qMin(int(sourceQuality),100) : 75;
-#if defined(Q_OS_UNIXWARE)
- jpeg_set_quality(&cinfo, quality, B_TRUE /* limit to baseline-JPEG values */);
- jpeg_start_compress(&cinfo, B_TRUE);
-#else
- jpeg_set_quality(&cinfo, quality, true /* limit to baseline-JPEG values */);
- jpeg_start_compress(&cinfo, true);
-#endif
+ jpeg_set_quality(&cinfo, quality, TRUE /* limit to baseline-JPEG values */);
+ jpeg_start_compress(&cinfo, TRUE);
set_text(image, &cinfo, description);
@@ -801,11 +788,7 @@ bool QJpegHandlerPrivate::readJpegHeader(QIODevice *device)
if (!setjmp(err.setjmp_buffer)) {
jpeg_save_markers(&info, JPEG_COM, 0xFFFF);
- #if defined(Q_OS_UNIXWARE)
- (void) jpeg_read_header(&info, B_TRUE);
- #else
- (void) jpeg_read_header(&info, true);
- #endif
+ (void) jpeg_read_header(&info, TRUE);
int width = 0;
int height = 0;
diff --git a/src/gui/kernel/qwindow.cpp b/src/gui/kernel/qwindow.cpp
index 490cf0c110..11a6238fa1 100644
--- a/src/gui/kernel/qwindow.cpp
+++ b/src/gui/kernel/qwindow.cpp
@@ -502,10 +502,7 @@ WId QWindow::winId() const
if(!d->platformWindow)
const_cast<QWindow *>(this)->create();
- WId id = d->platformWindow->winId();
- // See the QPlatformWindow::winId() documentation
- Q_ASSERT(id != WId(0));
- return id;
+ return d->platformWindow->winId();
}
/*!
diff --git a/src/gui/text/qdistancefield_p.h b/src/gui/text/qdistancefield_p.h
index d4c4f8f46d..5c8f5e5808 100644
--- a/src/gui/text/qdistancefield_p.h
+++ b/src/gui/text/qdistancefield_p.h
@@ -137,12 +137,6 @@ private:
friend class QDistanceFieldData;
};
-
-inline QImage Q_GUI_EXPORT qt_renderDistanceFieldGlyph(const QRawFont &f, glyph_t g, bool d)
-{ return QDistanceField(f, g, d).toImage(QImage::Format_Indexed8); }
-inline QImage Q_GUI_EXPORT qt_renderDistanceFieldGlyph(QFontEngine *fe, glyph_t g, bool d)
-{ return QDistanceField(fe, g, d).toImage(QImage::Format_Indexed8); }
-
QT_END_NAMESPACE
#endif // QDISTANCEFIELD_H
diff --git a/src/platformsupport/fontdatabases/fontconfig/qfontconfigdatabase.cpp b/src/platformsupport/fontdatabases/fontconfig/qfontconfigdatabase.cpp
index 14ae32d55a..8c3ca2d229 100644
--- a/src/platformsupport/fontdatabases/fontconfig/qfontconfigdatabase.cpp
+++ b/src/platformsupport/fontdatabases/fontconfig/qfontconfigdatabase.cpp
@@ -545,6 +545,14 @@ QFontEngine *QFontconfigDatabase::fontEngine(const QFontDef &f, QChar::Script sc
}
}
+ if (antialias) {
+ // If antialiasing is not fully disabled, fontconfig may still disable it on a font match basis.
+ FcBool fc_antialias;
+ if (FcPatternGetBool(match, FC_ANTIALIAS,0, &fc_antialias) != FcResultMatch)
+ fc_antialias = true;
+ antialias = fc_antialias;
+ }
+
if (f.hintingPreference == QFont::PreferDefaultHinting) {
const QPlatformServices *services = QGuiApplicationPrivate::platformIntegration()->services();
if (services && (services->desktopEnvironment() == "GNOME" || services->desktopEnvironment() == "UNITY")) {
diff --git a/src/plugins/platforms/cocoa/qnsview.h b/src/plugins/platforms/cocoa/qnsview.h
index ca2a15a1cc..f75b3e35ca 100644
--- a/src/plugins/platforms/cocoa/qnsview.h
+++ b/src/plugins/platforms/cocoa/qnsview.h
@@ -70,6 +70,7 @@ QT_END_NAMESPACE
Qt::KeyboardModifiers currentWheelModifiers;
bool m_subscribesForGlobalFrameNotifications;
QCocoaGLContext *m_glContext;
+ bool m_drawRectHasBeenCalled;
bool m_shouldSetGLContextinDrawRect;
}
diff --git a/src/plugins/platforms/cocoa/qnsview.mm b/src/plugins/platforms/cocoa/qnsview.mm
index b8a31329fe..ea8e1b363b 100644
--- a/src/plugins/platforms/cocoa/qnsview.mm
+++ b/src/plugins/platforms/cocoa/qnsview.mm
@@ -87,6 +87,7 @@ static QTouchDevice *touchDevice = 0;
m_sendKeyEvent = false;
m_subscribesForGlobalFrameNotifications = false;
m_glContext = 0;
+ m_drawRectHasBeenCalled = false;
m_shouldSetGLContextinDrawRect = false;
currentCustomDragTypes = 0;
m_sendUpAsRightButton = false;
@@ -153,9 +154,9 @@ static QTouchDevice *touchDevice = 0;
- (void) setQCocoaGLContext:(QCocoaGLContext *)context
{
m_glContext = context;
- [m_glContext->nsOpenGLContext() setView:self];
- if (![m_glContext->nsOpenGLContext() view]) {
- //was unable to set view
+ if (m_drawRectHasBeenCalled) {
+ [m_glContext->nsOpenGLContext() setView:self];
+ } else {
m_shouldSetGLContextinDrawRect = true;
}
@@ -392,6 +393,8 @@ static QTouchDevice *touchDevice = 0;
m_shouldSetGLContextinDrawRect = false;
}
+ m_drawRectHasBeenCalled = true;
+
if (!m_backingStore)
return;
diff --git a/src/plugins/platforms/qnx/qqnxnativeinterface.cpp b/src/plugins/platforms/qnx/qqnxnativeinterface.cpp
index e147ca72e5..4dd3444832 100644
--- a/src/plugins/platforms/qnx/qqnxnativeinterface.cpp
+++ b/src/plugins/platforms/qnx/qqnxnativeinterface.cpp
@@ -62,4 +62,12 @@ void *QQnxNativeInterface::nativeResourceForWindow(const QByteArray &resource, Q
return 0;
}
+void *QQnxNativeInterface::nativeResourceForScreen(const QByteArray &resource, QScreen *screen)
+{
+ if (resource == "QObject*" && screen)
+ return static_cast<QObject*>(static_cast<QQnxScreen*>(screen->handle()));
+
+ return 0;
+}
+
QT_END_NAMESPACE
diff --git a/src/plugins/platforms/qnx/qqnxnativeinterface.h b/src/plugins/platforms/qnx/qqnxnativeinterface.h
index d84df205e5..6692da2576 100644
--- a/src/plugins/platforms/qnx/qqnxnativeinterface.h
+++ b/src/plugins/platforms/qnx/qqnxnativeinterface.h
@@ -50,6 +50,7 @@ class QQnxNativeInterface : public QPlatformNativeInterface
{
public:
void *nativeResourceForWindow(const QByteArray &resource, QWindow *window);
+ void *nativeResourceForScreen(const QByteArray &resource, QScreen *screen);
};
QT_END_NAMESPACE
diff --git a/src/plugins/platforms/qnx/qqnxscreen.cpp b/src/plugins/platforms/qnx/qqnxscreen.cpp
index d940b35861..69e672aefc 100644
--- a/src/plugins/platforms/qnx/qqnxscreen.cpp
+++ b/src/plugins/platforms/qnx/qqnxscreen.cpp
@@ -573,8 +573,10 @@ void QQnxScreen::addUnderlayWindow(screen_window_t window)
void QQnxScreen::removeOverlayOrUnderlayWindow(screen_window_t window)
{
const int numRemoved = m_overlays.removeAll(window) + m_underlays.removeAll(window);
- if (numRemoved > 0)
+ if (numRemoved > 0) {
updateHierarchy();
+ Q_EMIT foreignWindowClosed(window);
+ }
}
void QQnxScreen::newWindowCreated(void *window)
@@ -608,6 +610,7 @@ void QQnxScreen::newWindowCreated(void *window)
addUnderlayWindow(windowHandle);
else
addOverlayWindow(windowHandle);
+ Q_EMIT foreignWindowCreated(windowHandle);
}
}
}
diff --git a/src/plugins/platforms/qnx/qqnxscreen.h b/src/plugins/platforms/qnx/qqnxscreen.h
index e498d27c14..fd97e2e58f 100644
--- a/src/plugins/platforms/qnx/qqnxscreen.h
+++ b/src/plugins/platforms/qnx/qqnxscreen.h
@@ -98,6 +98,10 @@ public:
QPlatformCursor *cursor() const;
+Q_SIGNALS:
+ void foreignWindowCreated(void *window);
+ void foreignWindowClosed(void *window);
+
public Q_SLOTS:
void setRotation(int rotation);
void newWindowCreated(void *window);
diff --git a/src/plugins/platforms/windows/qwindowsbackingstore.cpp b/src/plugins/platforms/windows/qwindowsbackingstore.cpp
index dfbbe3069c..26205eb146 100644
--- a/src/plugins/platforms/windows/qwindowsbackingstore.cpp
+++ b/src/plugins/platforms/windows/qwindowsbackingstore.cpp
@@ -88,8 +88,10 @@ void QWindowsBackingStore::flush(QWindow *window, const QRegion &region,
QWindowsWindow *rw = QWindowsWindow::baseWindowOf(window);
#ifndef Q_OS_WINCE
+ const bool hasAlpha = rw->format().hasAlpha();
const Qt::WindowFlags flags = window->flags();
- if ((flags & Qt::FramelessWindowHint) && QWindowsWindow::setWindowLayered(rw->handle(), flags, rw->format().hasAlpha(), rw->opacity())) {
+ if ((flags & Qt::FramelessWindowHint) && QWindowsWindow::setWindowLayered(rw->handle(), flags, hasAlpha, rw->opacity()) && hasAlpha) {
+ // Windows with alpha: Use blend function to update.
QRect r = window->frameGeometry();
QPoint frameOffset(window->frameMargins().left(), window->frameMargins().top());
QRect dirtyRect = br.translated(offset + frameOffset);
diff --git a/src/plugins/platforms/windows/qwindowswindow.cpp b/src/plugins/platforms/windows/qwindowswindow.cpp
index f3faccbc14..7077eaf4b0 100644
--- a/src/plugins/platforms/windows/qwindowswindow.cpp
+++ b/src/plugins/platforms/windows/qwindowswindow.cpp
@@ -314,7 +314,8 @@ static void setWindowOpacity(HWND hwnd, Qt::WindowFlags flags, bool hasAlpha, qr
Q_UNUSED(level);
#else
if (QWindowsWindow::setWindowLayered(hwnd, flags, hasAlpha, level)) {
- if (flags & Qt::FramelessWindowHint) {
+ if (hasAlpha && (flags & Qt::FramelessWindowHint)) {
+ // Windows with alpha: Use blend function to update.
BLENDFUNCTION blend = {AC_SRC_OVER, 0, (BYTE)(255.0 * level), AC_SRC_ALPHA};
QWindowsContext::user32dll.updateLayeredWindow(hwnd, NULL, NULL, NULL, NULL, NULL, 0, &blend, ULW_ALPHA);
} else {
diff --git a/src/tools/qdoc/doc/config/qdoc.qdocconf b/src/tools/qdoc/doc/config/qdoc.qdocconf
index a6ae18a675..992cec65dc 100644
--- a/src/tools/qdoc/doc/config/qdoc.qdocconf
+++ b/src/tools/qdoc/doc/config/qdoc.qdocconf
@@ -8,16 +8,16 @@ version = $QT_VERSION
sourcedirs = ..
exampledirs = .. \
- ../examples \
- ../../../../examples \
- config
+ ../examples
-imagedirs = ../../../doc/src/templates/images \
- ../images \
- ../../../../widgets/doc/images \
+imagedirs = ../images \
+ ../../../../widgets/doc/images
+# ../../../doc/src/templates/images
tagfile = ../html/qdoc.tags
+examples.fileextensions = "*.cpp *.h *.js *.xq *.svg *.xml *.ui *.qhp *.qhcp *.qml *.css *.qdoc *.qdocinc *.sample"
+
qhp.projects = QDoc
qhp.QDoc.file = qdoc.qhp
diff --git a/src/tools/qdoc/doc/examples/componentset/uicomponents.qdoc b/src/tools/qdoc/doc/examples/componentset/uicomponents.qdoc.sample
index 4b16dfa14f..4b16dfa14f 100644
--- a/src/tools/qdoc/doc/examples/componentset/uicomponents.qdoc
+++ b/src/tools/qdoc/doc/examples/componentset/uicomponents.qdoc.sample
diff --git a/src/tools/qdoc/doc/examples/cpp.qdoc.sample b/src/tools/qdoc/doc/examples/cpp.qdoc.sample
index 08286b956a..e496bbc278 100644
--- a/src/tools/qdoc/doc/examples/cpp.qdoc.sample
+++ b/src/tools/qdoc/doc/examples/cpp.qdoc.sample
@@ -123,4 +123,4 @@ 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]
+//! [overloaded notifier]
diff --git a/src/tools/qdoc/doc/examples/examples.qdoc b/src/tools/qdoc/doc/examples/examples.qdoc
index ed57d27dba..af7ff591b6 100644
--- a/src/tools/qdoc/doc/examples/examples.qdoc
+++ b/src/tools/qdoc/doc/examples/examples.qdoc
@@ -36,7 +36,7 @@
and their public interfaces. The types are grouped into a module, the
\l{UI Components} module.
- The \l{componentset/uicomponents.qdoc}{uicomponents.qdoc} file generates
+ The \l{componentset/uicomponents.qdoc.sample}{uicomponents.qdoc} file generates
the overview page for the \l{UI Components} module page.
The generated documentation is available in the \l{UI Components} module.
@@ -82,3 +82,17 @@
inside C++ classes to define the public API of the QML type.
*/
+
+
+/*!
+ \qmlmodule UIComponents 1.0
+ \title UI Components
+ \brief Basic set of UI components
+
+ This is a listing of a list of UI components implemented by QML types. These
+
+ files are available for general import and they are based off the \l{Qt
+ Quick Code Samples}.
+
+ This module is part of the \l{componentset}{UIComponents} example.
+*/
diff --git a/src/tools/qdoc/doc/files/basicqt.qdoc.sample b/src/tools/qdoc/doc/files/basicqt.qdoc.sample
new file mode 100644
index 0000000000..ce8df096fa
--- /dev/null
+++ b/src/tools/qdoc/doc/files/basicqt.qdoc.sample
@@ -0,0 +1,67 @@
+ /*!
+ \page basicqt.html
+ \contentspage {Basic Qt} {Contents}
+ \nextpage Getting Started
+
+ \indexpage Index
+ \startpage Basic Qt
+
+ \title Basic Qt
+
+ The Qt toolkit is a C++ class library and a set of tools for
+ building multiplatform GUI programs using a "write once,
+ compile anywhere approach".
+
+ Table of contents:
+
+ \list
+ \li \l {Getting Started}
+ \li \l {Creating Dialogs}
+ \li \l {Creating Main Windows}
+ \endlist
+ */
+
+ /*!
+ \page gettingstarted.html
+ \previouspage Basic Qt
+ \contentspage {Basic Qt} {Contents}
+ \nextpage Creating Dialogs
+
+ \indexpage Index
+ \startpage Basic Qt
+
+ \title Getting Started
+
+ This chapter shows how to combine basic C++ with the
+ functionality provided by Qt to create a few small graphical
+ interface (GUI) applications.
+*/
+
+/ *!
+ \page creatingdialogs.html
+ \previouspage Getting Started
+ \contentspage {Basic Qt} {Contents}
+
+ \indexpage Index
+ \startpage Basic Qt
+
+ \title Creating Dialogs
+
+ This chapter will teach you how to create dialog boxes using Qt.
+*/
+
+/*!
+ \page index.html
+
+ \indexpage Index
+ \startpage Basic Qt
+
+ \title Index
+
+ \list
+ \li \l {Basic Qt}
+ \li \l {Creating Dialogs}
+ \li \l {Getting Started}
+ \endlist
+*/
+
diff --git a/src/tools/qdoc/doc/qdoc-guide/qdoc-guide.qdoc b/src/tools/qdoc/doc/qdoc-guide/qdoc-guide.qdoc
index d2a2a66beb..3c30159895 100644
--- a/src/tools/qdoc/doc/qdoc-guide/qdoc-guide.qdoc
+++ b/src/tools/qdoc/doc/qdoc-guide/qdoc-guide.qdoc
@@ -51,7 +51,7 @@
documentation and an example of a QML type documentation.
For specific QDoc information, consult the
- \l{Table of Contents}{QDoc Manual}.
+ \l{QDoc Manual}.
\section1 Chapters
\list 1
@@ -62,7 +62,6 @@
\li \l{C++ Documentation Style}
\li \l{QML Documentation Style}
\endlist
- \li \l{Configuration File Example}
\li \l{QML Documentation Example}
\endlist
@@ -155,7 +154,7 @@
\section2 Qt Help Framework Configuration
- QDoc will also export a \l{Qt Help Project} file, in a \c qhp file.
+ 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.
@@ -268,6 +267,7 @@
\nextpage Categories of Documentation
\section1 QDoc Comments
+
Documentation is contained within qdoc \e comments, delimited by
\beginqdoc and \endqdoc comments. Note that these are valid comments
in C++, QML, and JavaScript.
@@ -402,7 +402,7 @@
\page qdoc-categories.html
\title Categories of Documentation
\previouspage Writing Documentation
- \nextpage Configuration File Example
+ \nextpage QML Documentation Example
\brief Describes the different types such as How-To's, Tutorials, Overviews,
Examples, and Class Documentation.
@@ -532,7 +532,7 @@
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 \l{QML Elements} belong
+ 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.
@@ -624,87 +624,10 @@
\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. For reference, view QDoc's generated
- page for the \l{UI Components: Tab Widget Example}{Tab Widget} example.
+ will also list all of the example code.
\note The example's project file must be the same as the
directory name.
*/
-/*!
- \example config
- \title Configuration File Example
- \previouspage Categories of Documentation
- \brief configuration files for the QDoc Manual and QDoc Guide
-
- The QDoc Manual uses these \c qdocconf files to generate the QDoc Guide and
- the \l{Table of Contents}{QDoc Manual}.
-
- \note The configuration files are similar to the Qt Reference Documentation
- and the QDoc Manual do not use all of the variables. The variables are
- included to demonstrate a full project scenario.
-
- \section1 Macros and other Definitions
- \list
- \li \l{config/compat.qdocconf}
- \li \l{config/macros.qdocconf}
- \li \l{config/qt-cpp-ignore.qdocconf}
- \li \l{config/qt-defines.qdocconf}
- \endlist
-
- QDoc allows macros to help with aliasing and for inputting special HTML
- characters within the documentation. Macros are a form of workarounds if
- QDoc is unable to resolve formatting issues such as when QDoc should
- disregard QDoc comments in documentation paragraphs.
-
- QDoc is also aware of the common C++ and Qt preprocessors and can decide
- which documentation to generate according to the definitions in the
- configuration files.
-
- \section1 Project Information
- \list
- \li \l{config/qdoc-online.qdocconf}
- \li \l{config/qdoc.qdocconf}
- \li \l{config/qdoc-project.qdocconf}
- \endlist
-
- These configuration files dictate how QDoc will generate the project.
- Depending which configuration file QDoc processes, the formatting and the
- information about the project will be different. If QDoc processes
- \c{qdoc-online.qdocconf}, QDoc will generate the HTML version of the manual
- will have the style suitable for online viewing.
-
- Additionally, the settings for creating the
- \l{The Qt Help Framework}{Qt Help File} is in the configuration.
-
- \note The project file uses variables used during Qt's
- \l{Configuration Options for Qt}{configuration} step.
-
- \section1 HTML Styles
- \list
- \li \l{config/qt-html-default-styles.qdocconf}
- \li \l{config/qt-html-online-styles.qdocconf}
- \li \l{config/qt-html-templates-online.qdocconf}
- \li \l{config/qt-html-templates.qdocconf}
- \endlist
-
- These files indicate which styles QDoc should use for the HTML formats.
- Typically, there are two templates, one for online viewing and one for
- offline. Qt Creator is able to fit more content in a page with the offline
- template. The templates store HTML information as strings and QDoc will copy
- the template to each HTML page.
-
- \section1 Project File
- \list
- \li \l{config/config.pro}
- \endlist
-
- Every example page (such as this one) needs a Qt project file. QDoc will
- use the project file to determine which files are part of the example. QDoc
- will then create a page listing all the files that are part of the example.
-
- \note the directory name of the example and the name of the project file
- must match. The example directory is found using the
- \l{qdoc-input-output-dir}{exampledirs} variable.
-*/
diff --git a/src/tools/qdoc/doc/qdoc-guide/qtwritingstyle-cpp.qdoc b/src/tools/qdoc/doc/qdoc-guide/qtwritingstyle-cpp.qdoc
index 2095c4e7cb..f8e96f0ee4 100644
--- a/src/tools/qdoc/doc/qdoc-guide/qtwritingstyle-cpp.qdoc
+++ b/src/tools/qdoc/doc/qdoc-guide/qtwritingstyle-cpp.qdoc
@@ -107,7 +107,7 @@ marked with the \l{c-command}{\\c} command in the case of boolean values.
\section1 Properties
The property documentation resides immediately above the read function's
-implementation. The \l{topic-commands}{topic command} for properties is
+implementation. The \l{writing-topic-commands}{topic command} for properties is
\l{property-command}{\\property}.
\snippet examples/cpp.qdoc.sample property
@@ -138,7 +138,7 @@ The values range from 0.0 (no blur) to maximumRadius (maximum blur). By default,
\endquotation
\section1 Signals, Notifiers, and Slots
-The \l{topic-commands}{topic command} for 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.
@@ -168,7 +168,7 @@ the notifier.
\section1 Enums, Namespaces, and other Types
-Enums, namespaces, and macros have a \l{topic-command} for their documentation:
+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}
diff --git a/src/tools/qdoc/doc/qdoc-manual-DITA.qdoc b/src/tools/qdoc/doc/qdoc-manual-DITA.qdoc
new file mode 100644
index 0000000000..070bad336f
--- /dev/null
+++ b/src/tools/qdoc/doc/qdoc-manual-DITA.qdoc
@@ -0,0 +1,164 @@
+/****************************************************************************
+**
+** Copyright (C) 2013 Digia Plc and/or its subsidiary(-ies).
+** Contact: http://www.qt-project.org/legal
+**
+** This file is part of the documentation of the Qt Toolkit.
+**
+** $QT_BEGIN_LICENSE:FDL$
+** Commercial License Usage
+** Licensees holding valid commercial Qt licenses may use this file in
+** accordance with the commercial license agreement provided with the
+** Software or, alternatively, in accordance with the terms contained in
+** a written agreement between you and Digia. For licensing terms and
+** conditions see http://qt.digia.com/licensing. For further information
+** use the contact form at http://qt.digia.com/contact-us.
+**
+** GNU Free Documentation License Usage
+** Alternatively, this file may be used under the terms of the GNU Free
+** Documentation License version 1.3 as published by the Free Software
+** Foundation and appearing in the file included in the packaging of
+** this file. Please review the following information to ensure
+** the GNU Free Documentation License version 1.3 requirements
+** will be met: http://www.gnu.org/copyleft/fdl.html.
+** $QT_END_LICENSE$
+**
+****************************************************************************/
+
+/*!
+ \page 21-0-qdoc-creating-dita-maps.html
+ \previouspage Miscellaneous
+ \contentspage QDoc Manual
+ \nextpage The QDoc Configuration File
+
+ \title Creating DITA Maps
+
+ You can create DITA map files using three new qdoc commands, the \l{ditamap-command}
+ {ditamap} command, the \l{topicref-command} {topicref} command, and the \l{mapref-command}
+ {mapref} command. How these DITA maps will be used automatically or manually by the
+ documentation build process is still under consideration. This section will be updated
+ as the decisions are made.
+
+ \section1 What is a DITA map?
+
+ A complete description of DITA can be found at the
+ \l{http://www.oasis-open.org/committees/tc_home.php?wg_abbrev=dita}
+ {OASIS Darwin Information Typing Architecture} site.
+
+ An explanation of the DITA map is found at that site
+ \l{http://docs.oasis-open.org/dita/v1.2/os/spec/langref/map.html}{here}.
+
+ \target ditamap-command
+ \section1 \\ditamap
+
+ The \\ditamap command is for creating a DITA map using qdoc commands.
+ The \\ditamap command is a kind of \\page command that produces a
+ \e{.ditamap} instead of a \e{.html} or \e{.xml} file. The file that
+ is created actually contains XML text, but the \e{.ditamap} suffix is
+ used to identify the file as containing a DITA MAP.
+
+ The argument is the name of the file to be created. In the following
+ example, the file \e{creator.ditamap} is output:
+ \code
+ \ditamap creator.ditamap
+ \endcode
+
+ \target topicref-command
+ \section1 \\topicref \\endtopicref
+
+ The \\topicref \\endtopicref commands are for creating a topicref
+ in the ditamap. The \\endtopicref command is required because
+ \\topicref commands can be nested.
+
+ \\topicref has two arguments. The first argument becomes the value
+ of the \e navtitle attribute. Normally, you use the title of the
+ topic being referenced. This title is often what will appear in a
+ table of contents constructed from the ditamap.
+
+ The second argument is the name of the page being referenced. The
+ second argument is actually optional, for example if you are using
+ a topicref as a container for other topicrefs and maprefs. It is
+ also optional if you want qdoc to find the page name for you by
+ looking up the title in its internal data structure. It is recommended
+ that you provide the second parameter if you know the page name.
+
+ \code
+ \topicref {QML Module QtQuick 2} {qtquick-2.xml}
+ \mapref {Creator Manual} {creator-manual.ditamap} \endmapref
+ \topicref {QML Mouse Events} {qtquick2-mouseevents.xml} \endtopicref
+ \topicref {Property Binding} {qtquick2-propertybinding.xml} \endtopicref
+ \endtopicref
+ \endcode
+
+ \target mapref-command
+ \section1 \\mapref
+
+ The \\mapref command is for creating a mapref in the ditamap. A
+ mapref refers to another ditamap, which you want to include in
+ your ditamap. Like the \\topicref command, the \\mapref command
+ has two arguments, but for the \\mapref command, both arguments
+ are required. The arguments are essentially the same as described
+ for \\topicref, but for \\mapref, the second command must be the
+ name of another ditamap, i.e. it must have the \e{.ditamap}
+ suffix. You must provide the file name. qdoc can't look up the
+ file name for you.
+
+ \code
+ \mapref {Creator Manual} {creator-manual.ditamap} \endmapref
+ \endcode
+
+ \section1 An example ditamap page
+
+ The following example uses the three qdoc ditamap commands described above.
+
+ \code
+ \ditamap creator.ditamap
+ \title The DITA Map for Creator
+
+ \topicref {QML Module QtQuick 1}
+ \topicref {QML Mouse Events} \endtopicref
+ \topicref {Property Binding} \endtopicref
+ \endtopicref
+
+ \topicref {QML Module QtQuick 2} {qtquick-2.xml}
+ \mapref {Creator Manual} {creator-manual.ditamap} \endmapref
+ \topicref {QML Mouse Events} {qtquick2-mouseevents.xml} \endtopicref
+ \topicref {Property Binding} {qtquick2-propertybinding.xml} \endtopicref
+ \endtopicref
+
+ \topicref {QML Module QtQuick.Particles 2} {qtquick-particles-2.xml}
+ \topicref {Age} {qml-qtquick-particles2-age.xml} \endtopicref
+ \endtopicref
+ \endcode
+
+ \section1 The resulting ditamap file
+
+ This is the \e{.ditamap} file you get when you input the qdoc
+ ditamap page shown above. Note that you can write ditamap files
+ directly in XML just as easily as you can write them using the
+ qdoc commands. The choice is yours.
+
+ \code
+ <?xml version="1.0" encoding="UTF-8"?>
+ <!DOCTYPE map PUBLIC "-//OASIS//DTD DITA Map//EN" "map.dtd">
+ <map>
+ <topicmeta>
+ <shortdesc>The DITA Map for Creator</shortdesc>
+ </topicmeta>
+ <topicref navtitle="QML Module QtQuick 1" href="qtquick-1.xml">
+ <topicref navtitle="QML Mouse Events" href="qtquick2-mouseevents.xml"/>
+ <topicref navtitle="Property Binding" href="qtquick2-propertybinding.xml"/>
+ </topicref>
+ <topicref navtitle="QML Module QtQuick 2" href="qtquick-2.xml">
+ <mapref navtitle="Creator Manual" href="creator-manual.ditamap"/>
+ <topicref navtitle="QML Mouse Events" href="qtquick2-mouseevents.xml"/>
+ <topicref navtitle="Property Binding" href="qtquick2-propertybinding.xml"/>
+ </topicref>
+ <topicref navtitle="QML Module QtQuick.Particles 2" href="qtquick-particles-2.xml">
+ <topicref navtitle="Age" href="qml-qtquick-particles2-age.xml"/>
+ </topicref>
+ </map>
+ \endcode
+
+*/
+
diff --git a/src/tools/qdoc/doc/qdoc-manual-cmdindex.qdoc b/src/tools/qdoc/doc/qdoc-manual-cmdindex.qdoc
new file mode 100644
index 0000000000..97d9151e40
--- /dev/null
+++ b/src/tools/qdoc/doc/qdoc-manual-cmdindex.qdoc
@@ -0,0 +1,159 @@
+/****************************************************************************
+**
+** Copyright (C) 2013 Digia Plc and/or its subsidiary(-ies).
+** Contact: http://www.qt-project.org/legal
+**
+** This file is part of the documentation of the Qt Toolkit.
+**
+** $QT_BEGIN_LICENSE:FDL$
+** Commercial License Usage
+** Licensees holding valid commercial Qt licenses may use this file in
+** accordance with the commercial license agreement provided with the
+** Software or, alternatively, in accordance with the terms contained in
+** a written agreement between you and Digia. For licensing terms and
+** conditions see http://qt.digia.com/licensing. For further information
+** use the contact form at http://qt.digia.com/contact-us.
+**
+** GNU Free Documentation License Usage
+** Alternatively, this file may be used under the terms of the GNU Free
+** Documentation License version 1.3 as published by the Free Software
+** Foundation and appearing in the file included in the packaging of
+** this file. Please review the following information to ensure
+** the GNU Free Documentation License version 1.3 requirements
+** will be met: http://www.gnu.org/copyleft/fdl.html.
+** $QT_END_LICENSE$
+**
+****************************************************************************/
+
+/*!
+ \page 27-qdoc-commands-alphabetical.html
+ \previouspage Introduction to QDoc
+ \contentspage QDoc Manual
+ \nextpage Topic Commands
+
+ \title Command Index
+
+ This is a complete, alphabetized list of the QDoc commands.
+
+ \list
+
+ \li \l {04-qdoc-commands-textmarkup.html#a-command} {\\a}
+ \li \l {11-qdoc-commands-specialcontent.html#abstract-command} {\\abstract}
+ \li \l {12-0-qdoc-commands-miscellaneous.html#annotatedlist-command} {\\annotatedlist}
+ \li \l {04-qdoc-commands-textmarkup.html#b-command} {\\b} \span {class="newStuff"} {(new 5/3/2012)}
+ \li \l {04-qdoc-commands-textmarkup.html#b-command} {\\bold} \span {class="newStuff"} {(deprecated, use \\b)}
+ \li \l {11-qdoc-commands-specialcontent.html#brief-command} {\\brief}
+ \li \l {04-qdoc-commands-textmarkup.html#c-command} {\\c}
+ \li \l {09-qdoc-commands-includingimages.html#caption-command} {\\caption}
+ \li \l {05-qdoc-commands-documentstructure.html#chapter-command} {\\chapter}
+ \li \l {13-qdoc-commands-topics.html#class-command} {\\class}
+ \li \l {06-qdoc-commands-includecodeinline.html#code-command} {\\code}
+ \li \l {07-0-qdoc-commands-includingexternalcode.html#codeline-command} {\\codeline},
+ \li \l {16-qdoc-commands-status.html#compat-command} {\\compat}
+ \li \l {15-qdoc-commands-navigation.html#contentspage-command} {\\contentspage}
+ \li \l {16-qdoc-commands-status.html#default-command} {\\default}
+ \li \l {21-0-qdoc-creating-dita-maps.html#ditamap-command} {\\ditamap} \span {class="newStuff"} {(new 05/03/12)}
+ \li \l {04-qdoc-commands-textmarkup.html#div-command} {\\div}
+ \li \l {07-0-qdoc-commands-includingexternalcode.html#dots-command} {\\dots}
+ \li \l {04-qdoc-commands-textmarkup.html#e-command} {\\e} \span {class="newStuff"} {(new 5/3/2012)}
+ \li \l {12-0-qdoc-commands-miscellaneous.html#else-command} {\\else}
+ \li \l {12-0-qdoc-commands-miscellaneous.html#endif-command} {\\endif}
+ \li \l {13-qdoc-commands-topics.html#enum-command} {\\enum}
+ \li \l {13-qdoc-commands-topics.html#example-command} {\\example}
+ \li \l {13-qdoc-commands-topics.html#externalpage-command} {\\externalpage}
+ \li \l {13-qdoc-commands-topics.html#fn-command} {\\fn}
+ \li \l {11-qdoc-commands-specialcontent.html#footnote-command} {\\footnote}
+ \li \l {12-0-qdoc-commands-miscellaneous.html#generatelist-command} {\\generatelist}
+ \li \l {13-qdoc-commands-topics.html#group-command} {\\group}
+ \li \l {10-qdoc-commands-tablesandlists.html#header-command} {\\header}
+ \li \l {13-qdoc-commands-topics.html#headerfile-command} {\\headerfile}
+ \li \l {04-qdoc-commands-textmarkup.html#e-command} {\\i} \span {class="newStuff"} {(deprecated, use \\e)}
+ \li \l {12-0-qdoc-commands-miscellaneous.html#if-command} {\\if}
+ \li \l {09-qdoc-commands-includingimages.html#image-command} {\\image}
+ \li \l {12-0-qdoc-commands-miscellaneous.html#include-command} {\\include}
+ \li \l {15-qdoc-commands-navigation.html#indexpage-command} {\\indexpage}
+ \li \l {19-qdoc-commands-grouping.html#ingroup-command} {\\ingroup}
+ \li \l {18-qdoc-commands-relating.html#inherits-command}{\\inherits}
+ \li \l {09-qdoc-commands-includingimages.html#inlineimage-command} {\\inlineimage}
+ \li \l {19-qdoc-commands-grouping.html#inmodule-command} {\\inmodule}
+ \li \l {13-qdoc-commands-topics.html#inqmlmodule-command} {\\inqmlmodule}
+ \li \l {13-qdoc-commands-topics.html#instantiates-command} {\\instantiates} \span {class="newStuff"} {(new 27/7/2012)}
+ \li \l {16-qdoc-commands-status.html#internal-command} {\\internal}
+ \li \l {08-qdoc-commands-creatinglinks.html#keyword-command} {\\keyword}
+ \li \l {08-qdoc-commands-creatinglinks.html#l-command} {\\l}
+ \li \l {11-qdoc-commands-specialcontent.html#legalese-command} {\\legalese}
+ \li \l {10-qdoc-commands-tablesandlists.html#li-command} {\\li} \span {class="newStuff"} {(new 5/3/2012)}
+ \li \l {10-qdoc-commands-tablesandlists.html#list-command} {\\list}
+ \li \l {13-qdoc-commands-topics.html#macro-command} {\\macro}
+ \li \l {19-qdoc-commands-grouping.html#mainclass-command} {\\mainclass}
+ \li \l {21-0-qdoc-creating-dita-maps.html#mapref-command} {\\mapref} \span {class="newStuff"} {(new 05/03/12)}
+ \li \l {12-0-qdoc-commands-miscellaneous.html#meta-command} {\\meta}
+ \li \l {13-qdoc-commands-topics.html#module-command} {\\module}
+ \li \l {13-qdoc-commands-topics.html#namespace-command} {\\namespace}
+ \li \l {15-qdoc-commands-navigation.html#nextpage-command} {\\nextpage}
+ \li \l {06-qdoc-commands-includecodeinline.html#newcode-command} {\\newcode}
+ \li \l {17-qdoc-commands-thread.html#nonreentrant-command} {\\nonreentrant}
+ \li \l {11-qdoc-commands-specialcontent.html#note-command} {\\note}
+ \li \l {10-qdoc-commands-tablesandlists.html#li-command} {\\o} \span {class="newStuff"} {(deprecated, use \\li)}
+
+ \li \l {16-qdoc-commands-status.html#obsolete-command} {\\obsolete}
+ \li \l {06-qdoc-commands-includecodeinline.html#oldcode-command} {\\oldcode}
+ \li \l {12-0-qdoc-commands-miscellaneous.html#omit-command} {\\omit}
+ \li \l {10-qdoc-commands-tablesandlists.html#omitvalue-command} {\\omitvalue}
+ \li \l {18-qdoc-commands-relating.html#overload-command} {\\overload}
+ \li \l {13-qdoc-commands-topics.html#page-command} {\\page}
+ \li \l {05-qdoc-commands-documentstructure.html#part-command} {\\part}
+ \li \l {16-qdoc-commands-status.html#preliminary-command} {\\preliminary}
+ \li \l {15-qdoc-commands-navigation.html#previouspage-command} {\\previouspage}
+ \li \l {07-0-qdoc-commands-includingexternalcode.html#printline-command} {\\printline}
+ \li \l {07-0-qdoc-commands-includingexternalcode.html#printto-command} {\\printto}
+ \li \l {07-0-qdoc-commands-includingexternalcode.html#printuntil-command} {\\printuntil}
+ \li \l {13-qdoc-commands-topics.html#property-command} {\\property}
+ \li \l {13-qdoc-commands-topics.html#qmlattachedproperty-command} {\\qmlattachedproperty}
+ \li \l {13-qdoc-commands-topics.html#qmlattachedsignal-command} {\\qmlattachedsignal}
+ \li \l {13-qdoc-commands-topics.html#qmlbasictype-command} {\\qmlbasictype}
+ \li \l {13-qdoc-commands-topics.html#qmlclass-command} {\\qmlclass} \span {class="newStuff"} {(deprecated, use \\qmltype)}
+ \li \l {13-qdoc-commands-topics.html#qmltype-command} {\\qmltype} \span {class="newStuff"} {(new 27/7/2012)}
+ \li \l {13-qdoc-commands-topics.html#qmlmethod-command} {\\qmlmethod}
+ \li \l {13-qdoc-commands-topics.html#qmlproperty-command} {\\qmlproperty}
+ \li \l {13-qdoc-commands-topics.html#qmlsignal-command} {\\qmlsignal}
+ \li \l {13-qdoc-commands-topics.html#qmlmodule-command} {\\qmlmodule}
+ \li \l {11-qdoc-commands-specialcontent.html#quotation-command} {\\quotation}
+ \li \l {07-0-qdoc-commands-includingexternalcode.html#quotefile-command} {\\quotefile}
+ \li \l {07-0-qdoc-commands-includingexternalcode.html#quotefromfile-command} {\\quotefromfile}
+ \li \l {12-0-qdoc-commands-miscellaneous.html#raw-command} {\\raw} \span {class="newStuff"} {(avoid)}
+ \li \l {17-qdoc-commands-thread.html#reentrant-command} {\\reentrant}
+ \li \l {18-qdoc-commands-relating.html#reimp-command} {\\reimp}
+ \li \l {18-qdoc-commands-relating.html#relates-command} {\\relates}
+ \li \l {10-qdoc-commands-tablesandlists.html#row-command} {\\row}
+ \li \l {08-qdoc-commands-creatinglinks.html#sa-command} {\\sa}
+ \li \l {05-qdoc-commands-documentstructure.html#sectionOne-command} {\\section1}
+ \li \l {05-qdoc-commands-documentstructure.html#sectionTwo-command} {\\section2}
+ \li \l {05-qdoc-commands-documentstructure.html#sectionThree-command} {\\section3}
+ \li \l {05-qdoc-commands-documentstructure.html#sectionFour-command} {\\section4}
+ \li \l {13-qdoc-commands-topics.html#service-command} {\\service}
+ \li \l {16-qdoc-commands-status.html#since-command} {\\since}
+ \li \l {07-0-qdoc-commands-includingexternalcode.html#skipline-command} {\\skipline}
+ \li \l {07-0-qdoc-commands-includingexternalcode.html#skipto-command} {\\skipto}
+ \li \l {07-0-qdoc-commands-includingexternalcode.html#skipuntil-command} {\\skipuntil}
+ \li \l {07-0-qdoc-commands-includingexternalcode.html#snippet-command} {\\snippet},
+ \li \l {04-qdoc-commands-textmarkup.html#span-command} {\\span}
+ \li \l {15-qdoc-commands-navigation.html#startpage-command} {\\startpage}
+ \li \l {04-qdoc-commands-textmarkup.html#sub-command} {\\sub}
+ \li \l {20-qdoc-commands-namingthings.html#subtitle-command} {\\subtitle}
+ \li \l {04-qdoc-commands-textmarkup.html#sup-command} {\\sup}
+ \li \l {10-qdoc-commands-tablesandlists.html#table-command} {\\table}
+ \li \l {11-qdoc-commands-specialcontent.html#tableofcontents-command} {\\tableofcontents}
+ \li \l {08-qdoc-commands-creatinglinks.html#target-command} {\\target}
+ \li \l {17-qdoc-commands-thread.html#threadsafe-command} {\\threadsafe}
+ \li \l {20-qdoc-commands-namingthings.html#title-command} {\\title}
+ \li \l {21-0-qdoc-creating-dita-maps.html#topicref-command} {\\topicref} \span {class="newStuff"} {(new 05/03/12)}
+ \li \l {04-qdoc-commands-textmarkup.html#tt-command} {\\tt}
+ \li \l {13-qdoc-commands-topics.html#typedef-command} {\\typedef}
+ \li \l {04-qdoc-commands-textmarkup.html#uicontrol-command} {\\uicontrol} {(new 25/3/2012)}
+ \li \l {04-qdoc-commands-textmarkup.html#underline-command} {\\underline}
+ \li \l {13-qdoc-commands-topics.html#variable-command} {\\variable}
+ \li \l {10-qdoc-commands-tablesandlists.html#value-command} {\\value}
+ \li \l {11-qdoc-commands-specialcontent.html#warning-command} {\\warning}
+ \endlist
+*/
diff --git a/src/tools/qdoc/doc/qdoc-manual-contextcmds.qdoc b/src/tools/qdoc/doc/qdoc-manual-contextcmds.qdoc
new file mode 100644
index 0000000000..8faf4a7f0d
--- /dev/null
+++ b/src/tools/qdoc/doc/qdoc-manual-contextcmds.qdoc
@@ -0,0 +1,1076 @@
+/****************************************************************************
+**
+** Copyright (C) 2013 Digia Plc and/or its subsidiary(-ies).
+** Contact: http://www.qt-project.org/legal
+**
+** This file is part of the documentation of the Qt Toolkit.
+**
+** $QT_BEGIN_LICENSE:FDL$
+** Commercial License Usage
+** Licensees holding valid commercial Qt licenses may use this file in
+** accordance with the commercial license agreement provided with the
+** Software or, alternatively, in accordance with the terms contained in
+** a written agreement between you and Digia. For licensing terms and
+** conditions see http://qt.digia.com/licensing. For further information
+** use the contact form at http://qt.digia.com/contact-us.
+**
+** GNU Free Documentation License Usage
+** Alternatively, this file may be used under the terms of the GNU Free
+** Documentation License version 1.3 as published by the Free Software
+** Foundation and appearing in the file included in the packaging of
+** this file. Please review the following information to ensure
+** the GNU Free Documentation License version 1.3 requirements
+** will be met: http://www.gnu.org/copyleft/fdl.html.
+** $QT_END_LICENSE$
+**
+****************************************************************************/
+
+/*!
+ \page 14-qdoc-commands-contextcommands.html
+ \previouspage Topic Commands
+ \contentspage QDoc Manual
+ \nextpage Document Navigation
+
+ \title Context Commands
+
+ The context commands provide information about the element being
+ documented that QDoc can't deduce on its own. For example:
+ \list
+ \li Is this class thread-safe?
+ \li Is this function reentrant?
+ \li Of which module is this class a member ?
+ \endlist
+
+ Context commands can appear anywhere in a QDoc comment,
+ but they are normally placed near the top of the comment, just
+ below the \l {Topic Commands} {topic} command.
+
+ \list
+ \li \l {16-qdoc-commands-status.html#compat-command}{\\compat},
+ \li \l {15-qdoc-commands-navigation.html#contentspage-command}{\\contentspage},
+ \li \l {15-qdoc-commands-navigation.html#indexpage-command}{\\indexpage},
+ \li \l {19-qdoc-commands-grouping.html#ingroup-command}{\\ingroup},
+ \li \l {18-qdoc-commands-relating.html#inherits-command}{\\inherits},
+ \li \l {19-qdoc-commands-grouping.html#inmodule-command}{\\inmodule},
+ \li \l {16-qdoc-commands-status.html#internal-command}{\\internal},
+ \li \l {19-qdoc-commands-grouping.html#mainclass-command}{\\mainclass},
+ \li \l {15-qdoc-commands-navigation.html#nextpage-command}{\\nextpage},
+ \li \l {17-qdoc-commands-thread.html#nonreentrant-command}{\\nonreentrant},
+ \li \l {16-qdoc-commands-status.html#obsolete-command}{\\obsolete},
+ \li \l {18-qdoc-commands-relating.html#overload-command}{\\overload},
+ \li \l {16-qdoc-commands-status.html#preliminary-command}{\\preliminary},
+ \li \l {15-qdoc-commands-navigation.html#previouspage-command}{\\previouspage},
+ \li \l {17-qdoc-commands-thread.html#reentrant-command}{\\reentrant},
+ \li \l {18-qdoc-commands-relating.html#reimp-command}{\\reimp},
+ \li \l {18-qdoc-commands-relating.html#relates-command}{\\relates},
+ \li \l {16-qdoc-commands-status.html#since-command}{\\since},
+ \li \l {15-qdoc-commands-navigation.html#startpage-command}{\\startpage},
+ \li \l {20-qdoc-commands-namingthings.html#subtitle-command}{\\subtitle}
+ \li \l {17-qdoc-commands-thread.html#threadsafe-command}{\\threadsafe},
+ \li \l {20-qdoc-commands-namingthings.html#title-command}{\\title}
+ \endlist
+
+*/
+
+/*!
+ \page 15-qdoc-commands-navigation.html
+ \previouspage Context Commands
+ \contentspage QDoc Manual
+ \nextpage Reporting Status
+
+ \title Document Navigation
+
+ The navigation commands are for linking the pages of a document in
+ a meaningful sequence. Below is a sequence of QDoc comments that
+ shows a typical use of the navigation commands.
+
+ \section1 Example
+ \quotefile files/basicqt.qdoc.sample
+
+ QDoc renders the "Getting Started" page in \c{creatingdialogs.html}:
+
+ \quotation
+ \raw HTML
+ <table border="0" cellpadding="0" cellspacing="5" width="100%">
+
+ <tr>
+ <p>
+ [Previous: <a href="15-qdoc-commands-navigation.html#deadlink">
+ Basic Qt</a>]
+ [<a href="15-qdoc-commands-navigation.html#deadlink">Contents</a>]
+ [Next: <a href="15-qdoc-commands-navigation.html#deadlink">
+ Creating Dialogs</a>]
+ </p>
+
+ <h1 align="center">Getting Started<br /></h1>
+
+ <p>
+ This chapter shows how to combine basic C++ with the
+ functionality provided by Qt to create a few small graphical
+ interface (GUI) applications.
+ </p>
+
+ <p>
+ [Previous: <a href="15-qdoc-commands-navigation.html#deadlink">
+ Basic Qt</a>]
+ [<a href="15-qdoc-commands-navigation.html#deadlink">Contents</a>]
+ [Next: <a href="15-qdoc-commands-navigation.html#deadlink">
+ Creating Dialogs</a>]
+ </p>
+
+ </table>
+ \endraw
+ \endquotation
+
+ The \l {indexpage-command} {\\indexpage} and \l
+ {startpage-command} {\\startpage} commands create links to the
+ page's index page and start page. These links can be used by
+ browsers and search engines.
+
+ The index page is typically an alphabetical list of the document's
+ titles and topics, while the start page is the page considered by
+ the author to be the starting point of a multipage document.
+
+ The links are included in the generated HTML source code, but have
+ no visual effect on the documentation:
+
+ \code
+ <head>
+ ...
+ <link rel="index" href="index.html" />
+ <link rel="start" href="basicqt.html" />
+ ...
+ </head>
+ \endcode
+
+ \section1 Commands
+
+ \target previouspage-command
+ \section2 \\previouspage
+
+ The \\previouspage command links the current page to the previous
+ page in a sequence.a The command has two arguments, each enclosed
+ by curly braces: the first is the link target (the title of
+ the previous page), the second is the link text. If the page's
+ title is equivalent to the link text, the second argument can be
+ omitted.
+
+ The command must stand alone on its own line.
+
+ \target nextpage-command
+ \section2 \\nextpage
+
+ The \\nextpage command links the current page to the next page in
+ a sequence. The command follows the same syntax and argument
+ convention as the \l {previouspage-command} {\\previouspage}
+ command.
+
+ \target startpage-command
+ \section2 \\startpage
+
+ The \\startpage command specifies the first page of a sequence of
+ pages. The command must stand alone on its own line, and its
+ unique argument is the title of the first document.
+
+ QDoc will generate a link to the start page and include it in the
+ generated HTML file, but this has no visual effect on the
+ documentation. The generated link type tells browsers and search
+ engines which document is considered by the author to be the
+ starting point of the collection.
+
+ \target contentspage-command
+ \section2 \\contentspage
+
+ The \\contentspage command links the current page to a table of
+ contents page. The command follows the same syntax and argument
+ convention as the \l {previouspage-command} {\\previouspage}
+ command.
+
+ \target indexpage-command
+ \section2 \\indexpage
+
+ The \\indexpage command specifies an index page for the current
+ document. The command must stand alone on its own line, and its
+ unique argument is the title of the index document.
+
+ QDoc will generate a link to the index page and include it in the
+ generated HTML file, but this has no visual effect on the
+ documentation. The generated link type tells browsers and search
+ engines which document is considered by the author to be the
+ index page of the collection.
+*/
+
+
+/*!
+ \page 16-qdoc-commands-status.html
+ \previouspage Document Navigation
+ \contentspage QDoc Manual
+ \nextpage Thread Support
+
+ \title Reporting Status
+
+ These commands are for indicating that a documented element is
+ still under development, is becoming obsolete, is provided for
+ compatibility reasons, or is simply not to be included in the
+ public interface. The \l {since-command}{\\since} command is for
+ including information about the version when a function or class
+ first appeared.
+
+ \target compat-command
+ \section1 \\compat
+
+ The \\compat command is for indicating that a class or function is
+ part of the support library provided to keep old source code
+ working.
+
+ The command must stand on its own line.
+
+ Usually an equivalent function or class is provided as an
+ alternative.
+
+ If the command is used in the documentation of a class, the
+ command expands to a warning that the referenced class is part of
+ the support library. The warning is located at the top of the
+ documentation page.
+
+ \code
+ \beginqdoc
+ \class MyQt3SupportClass
+ \compat
+ \endqdoc
+ \endcode
+
+ QDoc renders this at the top of the MyQt3SupportClass class
+ reference page.
+
+ \quotation
+ \b {This class is part of the Qt 3 support
+ library.} It is provided to keep old source code
+ working. We strongly advise against using it in new
+ code. See the \l
+ {http://doc.qt.digia.com/4.0/porting4.html} {Porting
+ Guide} for more information.
+ \endquotation
+
+ If the command is used when documenting a function, QDoc will
+ create and link to a separate page documenting Qt 3 support
+ members when generating the reference documentation for the
+ associated class.
+
+ \code
+ \beginqdoc
+ \fn MyClass::MyQt3SupportMemberFunction
+ \compat
+
+ Use MyNewFunction() instead.
+ \endqdoc
+ \endcode
+
+ QDoc renders this in \c{myclass-qt3.html} as:
+
+ \quotation
+ \raw HTML
+ <h1>Qt 3 Support Members for MyClass</h1>
+ \endraw
+
+ \b {The following class members are part of the Qt 3
+ support layer.} They are provided to help you port old code to
+ Qt 4. We advise against using them in new code.
+
+ ...
+
+ \list
+ \li void MyQt3SupportMemberFunction()
+ \li ...
+ \endlist
+
+ \raw HTML
+ <hr />
+ <h2>Member Function Documentation</h2>
+ <h3>void MyQt3SupportMemberFunction ()</h3>
+ <p>Use MyNewFunction() instead.</p>
+ \endraw
+ ...
+ \endquotation
+
+ \target default-command
+ \section1 \\default
+
+ The \\default command is for marking a QML property as the
+ \l {http://qt-project.org/doc/qt-4.7/qdeclarativeintroduction.html#default-properties}
+ {default property}. The word \span {class="newStuff"} {default} is shown in red in
+ the documentation of the property.
+
+ \code
+ / *!
+ \qmlproperty list<Change> State::changes
+ This property holds the changes to apply for this state.
+ \default
+
+ By default these changes are applied against the default state. If the state
+ extends another state, then the changes are applied against the state being
+ extended.
+ * /
+ \endcode
+
+ See how QDoc renders this property on the reference page for the
+ \l {http://qt-project.org/doc/qt-4.7/qml-state.html#changes-prop} {State}
+ type.
+
+ \target obsolete-command
+ \section1 \\obsolete
+
+ The \\obsolete command is for indicating that a function is being
+ deprecated, and it should no longer be used in new code. There is
+ no guarantee for how long it will remain in the library.
+
+ The command must stand on its own line.
+
+ When generating the reference documentation for a class, QDoc will
+ create and link to a separate page documenting its obsolete
+ functions. Usually an equivalent function is provided as an
+ alternative.
+
+ \code
+ / *!
+ \fn MyClass::MyObsoleteFunction
+ \obsolete
+
+ Use MyNewFunction() instead.
+ * /
+ \endcode
+
+ QDoc renders this in \c{myclass-obsolete.html} as:
+
+ \quotation
+ \raw HTML
+ <h1>Obsolete Members for MyClass</h1>
+ \endraw
+
+ \b {The following class members are obsolete.} They are
+ provided to keep old source code working. We strongly advise
+ against using them in new code.
+
+ ...
+
+ \list
+ \li void MyObsoleteFunction() \c (obsolete)
+ \li ...
+ \endlist
+
+ \raw HTML
+ <hr />
+ <h2>Member Function Documentation</h2>
+ <h3>void MyObsoleteFunction ()</h3>
+ <p>Use MyNewFunction() instead.</p>
+ \endraw
+ ...
+ \endquotation
+
+ \target internal-command
+ \section1 \\internal
+
+ The \\internal command indicates that the referenced
+ function is not part of the public interface.
+
+ The command must stand on its own line.
+
+ QDoc ignores the documentation as well as the documented item,
+ when generating the associated class reference documentation.
+
+ \code
+ / *!
+ \internal
+
+ Tries to find the decimal separator. If it can't find
+ it and the thousand delimiter is != '.' it will try to
+ find a '.';
+ * /
+ int QDoubleSpinBoxPrivate::findDelimiter
+ (const QString &str, int index) const
+ {
+ int dotindex = str.indexOf(delimiter, index);
+ if (dotindex == -1 && thousand != dot && delimiter != dot)
+ dotindex = str.indexOf(dot, index);
+ return dotindex;
+ }
+ \endcode
+
+ This function will not be included in the documentation.
+
+ \target preliminary-command
+ \section1 \\preliminary
+
+ The \\preliminary command is for indicating that a referenced
+ function is still under development.
+
+ The command must stand on its own line.
+
+ The \\preliminary command expands to a notification in the
+ function documentation, and marks the function as preliminary when
+ it appears in lists.
+
+ \code
+ / *!
+ \preliminary
+
+ Returns information about the joining properties of the
+ character (needed for certain languages such as
+ Arabic).
+ * /
+ QChar::Joining QChar::joining() const
+ {
+ return ::joining(*this);
+ }
+ \endcode
+
+ QDoc renders this as:
+
+ \quotation
+ \raw HTML
+ <h3>
+ <a href="http://qt-project.org/doc/qt-5.0/qtcore/qchar.html#Joining-enum">Joining</a>
+ QChar::joining () const</h3>
+ \endraw
+
+ \b {This function is under development and
+ subject to change.}
+
+ Returns information about the joining properties of the
+ character (needed for certain languages such as
+ Arabic).
+ \endquotation
+
+ And the function's entry in QChar's list of functions will be
+ rendered as:
+
+ \quotation
+ \list
+ \li ...
+ \li Joining
+ \l {http://qt-project.org/doc/qt-5.0/qtcore/qchar.html#Joining-enum}
+ {joining}()
+ const \c (preliminary)
+ \li ...
+ \endlist
+ \endquotation
+
+ \target since-command
+ \section1 \\since
+
+ The \\since command tells in which minor release
+ the associated functionality was added.
+
+ \code
+ / *!
+ \since 4.1
+
+ Returns an icon for \a standardIcon.
+
+ ...
+
+ \sa standardPixmap()
+ * /
+ QIcon QStyle::standardIcon(StandardPixmap standardIcon, const QStyleOption *option, const QWidget *widget) const
+ {
+ }
+ \endcode
+
+ QDoc renders this as:
+
+ \quotation
+ \raw HTML
+ <h3>QIcon QStyle::standardIcon(StandardPixmap standardIcon, const QStyleOption *option, const QWidget *widget) const</h3>
+ \endraw
+
+ This function was introduced in Qt version 4.1
+
+ Returns an icon for \a standardIcon.
+
+ ...
+
+ See also \l {QStyle::standardPixmap()} {standardPixmap()}.
+ \endquotation
+
+ QDoc generates the "Qt" reference from the \l
+ {25-qdoc-configuration-derivedprojects.html#project} {\c project}
+ configuration variable. For that reason this reference will change
+ according to the current documentation project.
+
+ See also \l {25-qdoc-configuration-derivedprojects.html#project}
+ {\c project}.
+*/
+
+
+/*!
+ \page 17-qdoc-commands-thread.html
+ \previouspage Reporting Status
+ \contentspage QDoc Manual
+ \nextpage Relating Things
+
+ \title Thread Support
+
+ The thread support commands are for specifying the level of
+ support for multithreaded programming in a class or function.
+ There are three levels of support: \c threadsafe, \c reentrant and
+ \c nonreentrant.
+
+ The default is \c nonreentrant which means that the associated
+ class or function cannot be called by multiple threads. \c
+ Reentrant and \c threadsafe are levels primarily used for classes.
+
+ \c Reentrant means that all the functions in the referenced class
+ can be called simultaneously by multiple threads, provided that
+ each invocation of the functions reference unique data. While \c
+ threadsafe means that all the functions in the referenced class
+ can be called simultaneously by multiple threads even when each
+ invocation references shared data.
+
+ When a class is marked \l {reentrant-command} {\\reentrant} or \l
+ {threadsafe-command} {\\threadsafe}, functions in that class can
+ be marked \c nonreentrant using the \l {nonreentrant-command}
+ {\\nonreentrant} command.
+
+ \section1 Example
+
+ \target reentrant-example
+ \code
+ \beginqdoc
+ \class QLocale
+ \brief The QLocale class converts between numbers and their
+ string representations in various languages.
+
+ \reentrant
+ \ingroup i18n
+ \ingroup text
+ \mainclass
+
+ QLocale is initialized with a language/country pair in its
+ constructor and offers number-to-string and string-to-number
+ conversion functions similar to those in QString.
+
+ ...
+
+ \nonreentrant
+
+ Sets the global default locale to \a locale. These values are
+ used when a QLocale object is constructed with no
+ arguments. If this function is not called, the system's locale
+ is used.
+
+ \warning In a multithreaded application, the default locale
+ should be set at application startup, before any non-GUI
+ threads are created.
+
+ \sa system(), c()
+ \endqdoc
+ void QLocale::setDefault(const QLocale &locale)
+ {
+ default_d = locale.d;
+ }
+ \endcode
+
+ QDoc renders this as:
+
+ \quotation
+ \raw HTML
+ <h1><center>QLocale Class Reference</center></h1>
+ \endraw
+
+ The QLocale class converts between numbers and their string
+ representations in various languages. More...
+
+ \code
+ #include <QLocale>
+ \endcode
+
+ \b {Note:} All the functions in this class are \l
+ {17-qdoc-commands-thread.html#reentrant} {reentrant}, except \l
+ {QLocale::setDefault()} {setDefault()}.
+
+ ...
+
+ \raw HTML
+ <hr />
+ <h2>Member Type Documentation</h2>
+ \endraw
+
+ ...
+
+ \raw HTML
+ <h3>void QLocale::setDefault ( const QLocale & locale ) </h3>
+ \endraw
+
+ Sets the global default locale to locale. These values are
+ used when a QLocale object is constructed with no
+ arguments. If this function is not called, the system's locale
+ is used.
+
+ \warning In a multithreaded application, the default locale
+ should be set at application startup, before any non-GUI
+ threads are created.
+
+ \warning This function is not reentrant.
+
+ See also \l {QLocale::system()} {system()} and \l
+ {QLocale::c()} {c()}.
+
+ ...
+ \endquotation
+
+ As shown above, QDoc generates a notification when a class is
+ declared reentrant, and lists the exceptions (the declared
+ nonreentrant functions). A link to the general documentation on \l
+ {17-qdoc-commands-thread.html#reentrant} {reentrancy and thread-safety} is
+ included. In addition a warning, "\b Warning: This function is
+ not reentrant.", is generated in the nonreentrant functions'
+ documentation.
+
+ QDoc will generate the same notification and warnings when a class
+ is declared threadsafe.
+
+ For more information see the general documentation on \l
+ {17-qdoc-commands-thread.html#reentrant} {reentrancy and thread-safety}.
+
+ \section1 Commands
+
+ \target threadsafe-command
+ \section2 \\threadsafe
+
+ The \\threadsafe command includes a line in the documentation to
+ indicate that the associated class or function is \e threadsafe
+ and can be called simultaneously by multiple threads, even when
+ separate invocations reference shared data.
+
+ The command must stand on its own line.
+
+ The documentation generated from this command will be similar to
+ the what is generated for the \l {reentrant-command} {\\reentrant}
+ command. See the example above in the \l {reentrant-example}
+ {introduction}.
+
+ See also \l{reentrant-command} {\\reentrant} and
+ \l{nonreentrant-command} {\\nonreentrant}.
+
+ \target reentrant-command
+ \section2 \\reentrant
+
+ The \\reentrant command indicates that the associated class or
+ function can be called simultaneously by multiple threads,
+ provided that each invocation references its own data. See the \l
+ {reentrant-example} {example} above.
+
+ The command must stand on its own line.
+
+ See also \l{nonreentrant-command} {\\nonreentrant} and
+ \l{threadsafe-command} {\\threadsafe}.
+
+ \target nonreentrant-command
+ \section2 \\nonreentrant
+
+ The \\nonreentrant command indicates that the associated class or
+ function cannot be called by multiple threads. Nonreentrant is the
+ default case.
+
+ The command must stand on its own line.
+
+ When a class is marked \l {reentrant-command} {\\reentrant} or \l
+ {threadsafe-command} {\\threadsafe}, functions in that class can
+ be marked \c nonreentrant using this command in the \l{fn-command}
+ {\\fn} comment of the functions to be excluded.
+
+ See also \l{reentrant-command} {\\reentrant} and
+ \l{threadsafe-command} {\\threadsafe}.
+*/
+
+ / *!
+
+/*!
+ \page 18-qdoc-commands-relating.html
+ \previouspage Thread Support
+ \contentspage QDoc Manual
+ \nextpage Grouping Things
+
+ \title Relating Things
+
+ The relating commands are for specifying how one documented
+ element relates to another documented element. Some examples:
+ \list
+ \li This function is an overload of another function.
+ \li This function is a reimplementation of another function.
+ \li This typedef is \e related to some class or header file.
+ \endlist
+
+ There is also a command for documenting that a QML type inherits
+ some other QML type.
+
+ \section1 Commands
+
+ \target inherits-command
+ \section2 \\inherits
+
+ The \\inherits command is for documenting that one QML type
+ inherits some other QML type. It must be included in the
+ inheriting element's \l{qmltype-command}{\\qmltype} comment.
+ The argument is the name of the inherited QML type.
+
+ \code
+ / *!
+ \qmltype PauseAnimation
+ \instantiates QDeclarativePauseAnimation
+ \ingroup qml-animation-transition
+ \since 4.7
+ \inherits Animation
+ \brief The PauseAnimation element provides a pause for an animation.
+
+ When used in a SequentialAnimation, PauseAnimation is a step
+ when nothing happens, for a specified duration.
+
+ A 500ms animation sequence, with a 100ms pause between two animations:
+
+ SequentialAnimation {
+ NumberAnimation { ... duration: 200 }
+ PauseAnimation { duration: 100 }
+ NumberAnimation { ... duration: 200 }
+ }
+
+ \sa {QML Animation and Transitions}, {declarative/animation/basics}{Animation basics example}
+ * /
+ \endcode
+
+ QDoc includes this line on the reference page for the
+ \l{http://qt-project.org/doc/qt-4.7/qml-pauseanimation.html} {PauseAnimation}
+ element:
+
+ \quotation
+ Inherits \l{http://qt-project.org/doc/qt-4.7/qml-animation.html} {Animation}
+ \endquotation
+
+ \target overload-command
+ \section2 \\overload
+
+ The \\overload command is for indicating that a function is a
+ secondary overload of its name.
+
+ The command must stand on its own line.
+
+ For a function name that is overloaded (except constructors), QDoc
+ expects one primary version of the function, and all the others
+ marked with the \b {\\overload command}. The primary version
+ should be fully documented. Each overload can have whatever extra
+ documentation you want to add for just that overloaded version.
+
+ From Qt 4.5, you can include the function name plus '()' as a
+ parameter to the \b{\\overload} command, which will include a
+ standard \e{This function overloads...} line of text with a link
+ to the documentation for the primary version of the function.
+
+ \code
+ / *!
+ \overload addAction()
+
+ This convenience function creates a new action with an
+ \a icon and some \a text. The function adds the newly
+ created action to the menu's list of actions, and
+ returns it.
+
+ \sa QWidget::addAction()
+ * /
+ QAction *QMenu::addAction(const QIcon &icon, const QString &text)
+ {
+ QAction *ret = new QAction(icon, text, this);
+ addAction(ret);
+ return ret;
+ }
+ \endcode
+
+ QDoc renders this as:
+
+ \quotation
+ \raw HTML
+ <h3><a href="http://qt-project.org/doc/qt-5.0/qtwidgets/qaction.html">QAction</a>
+ * QMenu::addAction ( const QIcon & <i>icon</i>,
+ const QString & <i>text</i> )
+ </h3>
+ \endraw
+
+ This function overloads \l {http://qt-project.org/doc/qt-5.0/qtwidgets/qwidget.html#addAction} {addAction()}
+
+ This convenience function creates a new action with an
+ \e icon and some \e text. The function adds the newly
+ created action to the menu's list of actions, and
+ returns it.
+
+ See also
+ \l {http://qt-project.org/doc/qt-5.0/qtwidgets/qwidget.html#addAction}
+ {QWidget::addAction}().
+ \endquotation
+
+ If you don't include the function name with the \b{\\overlaod}
+ command, then instead of the "This function overloads..." line
+ with the link to the documentation for the primary version, you
+ get the old standard line:
+
+ \quotation
+ This is an overloaded member function, provided for
+ convenience.
+ \endquotation.
+
+ \target reimp-command
+ \section2 \\reimp
+
+ The \\reimp command is for indicating that a function is a
+ reimplementation of a virtual function.
+
+ The command must stand on its own line.
+
+ QDoc will omit the reimplemented function from the class
+ reference.
+
+ \code
+ / *!
+ \reimp
+ * /
+ void QToolButton::nextCheckState()
+ {
+ Q_D(QToolButton);
+ if (!d->defaultAction)
+ QAbstractButton::nextCheckState();
+ else
+ d->defaultAction->trigger();
+ }
+ \endcode
+
+ This function will not be included in the documentation. Instead,
+ a link to the base function QAbstractButton::nextCheckState() will
+ appear in the documentation.
+
+ \target relates-command
+ \section2 \\relates
+
+ The \\relates command is for including the documentation of a
+ global element to some class or header file. The argument is a
+ class name or header file.
+
+ \code
+ / *!
+ \relates QChar
+
+ Reads a char from the stream \a in into char \a chr.
+
+ \sa {Format of the QDataStream operators}
+ * /
+ QDataStream &operator>>(QDataStream &in, QChar &chr)
+ {
+ quint16 u;
+ in >> u;
+ chr.unicode() = ushort(u);
+ return in;
+ }
+ \endcode
+
+ The documentation for this function will be included on the reference page
+ for class QChar.
+*/
+
+/*!
+ \page 19-qdoc-commands-grouping.html
+ \previouspage Relating Things
+ \contentspage QDoc Manual
+ \nextpage Naming Things
+
+ \title Grouping Things
+
+ The grouping commands relate classes to defined groups and
+ modules. The groups are used when generating lists of related
+ classes in the documentation, while the modules are elements of
+ Qt's structure.
+
+ \section1 Commands
+
+ \target mainclass-command
+ \section2 \\mainclass
+
+ The \\mainclass command relates the documented class to
+ a group called mainclasses.
+
+ The command must stand on its own line.
+
+ \code
+ / *!
+ \class QWidget qwidget.h
+ \brief The QWidget class is the base class of
+ all user interface objects.
+
+ \mainclass
+
+ ...
+ * /
+ \endcode
+
+ This will include the QWidget class in the \e mainclasses
+ group, which means, for example, that the class will appear on the
+ list created by calling the \l {generatelist-command}
+ {\\generatelist} command with the \c mainclasses argument:
+
+ \l http://doc.qt.digia.com/4.0/mainclasses.html
+
+ \note The Qt documentation no longer includes the \e mainclasses
+ page.
+
+ See also \l {generatelist-command} {\\generatelist}.
+
+ \target ingroup-command
+ \section2 \\ingroup
+
+ The \\ingroup command indicates that the given
+ overview or documented class belongs to a certain group of
+ related docmentation.
+
+ A class or overview may belong to many groups.
+
+ The \\ingroup command's argument is a group name, but note
+ that the command considers the rest of the line as part of
+ its argument. Make sure that the group name is followed by
+ a linebreak.
+
+ \code
+ / *!
+ \class QDir
+ \brief The QDir class provides access to directory
+ structures and their contents.
+
+ \ingroup io
+ ...
+ * /
+ \endcode
+
+ This will include the QDir class in the \c io group, which means,
+ for example, that QDir will appear on the list created by calling
+ the \l {group-command} {\\group} command with the \c io argument.
+
+ To list overviews that are related to a certain group, you must
+ generate the list explicitly using the \l {generatelist-command}
+ {\\generatelist} command with the \c related argument.
+
+ See also \l {group-command} {\\group}.
+
+ \target inmodule-command
+ \section2 \\inmodule
+
+ The \\inmodule command relates a class to the module specified by
+ the command's argument.
+
+ For the basic classes in Qt, a class's module is determined by its
+ location, namely its directory. However, for extensions like
+ ActiveQt and Qt Designer, a class must be related to a module
+ explicitly.
+
+ The command's argument is a module name, but note that the command
+ considers the rest of the line as part of its argument. Make sure
+ that the module name is followed by a linebreak.
+
+ \code
+ /*!
+ \class QDesignerTaskMenuExtension
+ \inmodule QtDesigner
+ * /
+ \endcode
+
+ This ensures that the QDesignerTaskMenuExtension class is included
+ in the Qt Designer module, which means, for example, that the
+ class will appear on the list created by calling the \l
+ {generatelist-command} {\\generatelist} command with the \c
+ {{classesbymodule QtDesigner}} argument.
+
+ See also \l {module-command} {\\module} and \l
+ {generatelist-command} {\\generatelist}.
+*/
+
+/*!
+ \page 20-qdoc-commands-namingthings.html
+ \previouspage Grouping Things
+ \contentspage QDoc Manual
+ \nextpage Markup Commands
+
+ \title Naming Things
+
+ In general, a title command considers everything that follows it
+ until the first line break as its argument. If the title is so
+ long it must span multiple lines, end each line (except the last
+ one) with a backslash.
+
+ \section1 Commands
+
+ \target title-command
+ \section2 \\title
+
+ The \\title command sets the title for a documentation page, or
+ allows you to override it.
+
+ \code
+ / *!
+ \page signalandslots.html
+
+ \title Signals & Slots
+
+ Signals and slots are used for communication between
+ objects. The signals and slots mechanism is a central
+ feature of Qt, and probably the part that differs most
+ from the features provided by other frameworks.
+
+ ...
+ * /
+ \endcode
+
+ QDoc renders this as:
+
+ \quotation
+ \raw HTML
+ <h1><center>Signal and Slots</center></h1>
+ \endraw
+
+ Signals and slots are used for communication between
+ objects. The signals and slots mechanism is a central
+ feature of Qt and probably the part that differs most
+ from the features provided by other frameworks.
+ ...
+ \endquotation
+ See also \l {subtitle-command} {\\subtitle}.
+
+ \target subtitle-command
+ \section2 \\subtitle
+
+ The \\subtitle command sets a subtitle for a documentation page.
+
+ \code
+ \beginqdoc
+ \page qtopiacore-overview.html
+
+ \title Qtopia Core
+ \subtitle Qt for Embedded Linux
+
+ Qt/Embedded, the embedded Linux port of Qt, is a
+ complete and self-contained C++ GUI and platform
+ development tool for Linux-based embedded development.
+ ...
+ \endqdoc
+ \endcode
+
+ QDoc renders this as:
+
+ \quotation
+ \raw HTML
+ <h1><center>Qtopia Core</center></h1>
+ <h2><center>Qt for Embedded Linux</center></h2>
+ \endraw
+
+ Qt/Embedded, the embedded Linux port of Qt, is a
+ complete and self-contained C++ GUI and platform
+ development tool for Linux-based embedded development.
+ ...
+ \endquotation
+
+ See also \l {title-command} {\\title}.
+
+*/
diff --git a/src/tools/qdoc/doc/qdoc-manual-intro.qdoc b/src/tools/qdoc/doc/qdoc-manual-intro.qdoc
new file mode 100644
index 0000000000..db34e2a46c
--- /dev/null
+++ b/src/tools/qdoc/doc/qdoc-manual-intro.qdoc
@@ -0,0 +1,181 @@
+/****************************************************************************
+**
+** Copyright (C) 2013 Digia Plc and/or its subsidiary(-ies).
+** Contact: http://www.qt-project.org/legal
+**
+** This file is part of the documentation of the Qt Toolkit.
+**
+** $QT_BEGIN_LICENSE:FDL$
+** Commercial License Usage
+** Licensees holding valid commercial Qt licenses may use this file in
+** accordance with the commercial license agreement provided with the
+** Software or, alternatively, in accordance with the terms contained in
+** a written agreement between you and Digia. For licensing terms and
+** conditions see http://qt.digia.com/licensing. For further information
+** use the contact form at http://qt.digia.com/contact-us.
+**
+** GNU Free Documentation License Usage
+** Alternatively, this file may be used under the terms of the GNU Free
+** Documentation License version 1.3 as published by the Free Software
+** Foundation and appearing in the file included in the packaging of
+** this file. Please review the following information to ensure
+** the GNU Free Documentation License version 1.3 requirements
+** will be met: http://www.gnu.org/copyleft/fdl.html.
+** $QT_END_LICENSE$
+**
+****************************************************************************/
+
+/*!
+ \page 01-qdoc-manual.html
+ \contentspage QDoc Manual
+ \previouspage QDoc Manual
+ \nextpage Command Index
+
+ \title Introduction to QDoc
+
+ QDoc is a tool used by Qt Developers to generate documentation for
+ software projects. It works by extracting \e {QDoc comments} from
+ project source files and then formatting these comments as HTML
+ pages or DITA XML documents. QDoc finds QDoc comments in \c
+ {.cpp} files and in \c {.qdoc} files. QDoc does not look for QDoc
+ comments in \c {.h} files. A QDoc comment always begins with an
+ exclamation mark (\b{!})). For example:
+
+ \code
+ / *!
+ \class QObject
+ \brief The QObject class is the base class of all Qt objects.
+
+ \ingroup objectmodel
+
+ \reentrant
+
+ QObject is the heart of the Qt \l{Object Model}. The
+ central feature in this model is a very powerful mechanism
+ for seamless object communication called \l{signals and
+ slots}. You can connect a signal to a slot with connect()
+ and destroy the connection with disconnect(). To avoid
+ never ending notification loops you can temporarily block
+ signals with blockSignals(). The protected functions
+ connectNotify() and disconnectNotify() make it possible to
+ track connections.
+
+ QObjects organize themselves in \l {Object Trees &
+ Ownership} {object trees}. When you create a QObject with
+ another object as parent, the object will automatically
+ add itself to the parent's \c children() list. The parent
+ takes ownership of the object. It will automatically
+ delete its children in its destructor. You can look for an
+ object by name and optionally type using findChild() or
+ findChildren().
+
+ Every object has an objectName() and its class name can be
+ found via the corresponding metaObject() (see
+ QMetaObject::className()). You can determine whether the
+ object's class inherits another class in the QObject
+ inheritance hierarchy by using the \c inherits() function.
+
+ ....
+ * /
+ \endcode
+
+ From the QDoc comment above, QDoc generates the HTML page
+ \l {http://qt-project.org/doc/qt-5.0/qtcore/qobject.html#details}
+ {QObject Class Reference}.
+
+ 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 current name of the QDoc program is \c {qdoc}. To run qdoc
+ from the command line, give it the name of a configuration file:
+
+ \quotation
+ \c {$ ../../bin/qdoc ./config.qdocconf}
+ \endquotation
+
+ QDoc recognizes the \c {.qdocconf} suffix as a \l{The QDoc
+ Configuration File} {QDoc configuration file}. The configuration
+ file is where you tell QDoc where to find the project source
+ files, header files, and \c {.qdoc} files. It is also where you
+ tell QDoc what kind of output to generate (HTML, DITA XML,...),
+ and where to put the generated documentation. The configuration
+ file also contains other information for QDoc.
+
+ See \l{The QDoc Configuration File} for instructions on how to
+ set up a QDoc configuration file.
+
+ \section1 How QDoc works
+
+ QDoc begins by reading the configuration file you specified on the
+ command line. It stores all the variables from the configuration
+ file for later use. One of the first variables it uses is \c
+ {outputformats}. This variable tells QDoc which output generators
+ it will run. The default value is \e {HTML}, so if you don't set
+ \c {outputformats} in your configuration file, QDoc will generate
+ HTML output. That's usually what you will want anyway, but you can
+ also specify \e {DITAXML} to get DITA XML output instead.
+
+ Next, QDoc uses the values of the
+ \l {22-qdoc-configuration-generalvariables.html#headerdirs-variable}
+ {headerdirs} variable and/or the \l
+ {22-qdoc-configuration-generalvariables.html#headers-variable}
+ {headers} variable to find and parse all the header files for your
+ project. QDoc does \e not scan header files for QDoc comments. It
+ parses the header files to build a master tree of all the items
+ that should be documented, in other words, the items that QDoc should find
+ QDoc comments for.
+
+ After parsing all the header files and building the master tree of
+ items to be documented, QDoc uses the value of the \l
+ {22-qdoc-configuration-generalvariables.html#sourcedirs-variable}
+ {sourcedirs} variable and/or the value of the \l
+ {22-qdoc-configuration-generalvariables.html#sources-variable}
+ {sources} variable to find and parse all the \c {.cpp} and \c
+ {.qdoc} files for your project. These are the files QDoc scans for
+ \e {QDoc comments}. Remember that a QDoc comment begins with
+ an exclamation mark: \b {/*!} .
+
+ For each QDoc comment it finds, it searches the master tree for
+ the item where the documentation belongs. Then it interprets the
+ qdoc commands in the comment and stores the interpreted commands
+ and the comment text in the tree node for the item.
+
+ Finally, QDoc traverses the master tree. For each node, if the
+ node has stored documentation, QDoc calls the output generator
+ specified by the \c {outputformats} variable to format and write
+ the documentation in the directory specified in the configuration
+ file in the \l
+ {22-qdoc-configuration-generalvariables.html#outputdir-variable}
+ {outputdir} variable.
+
+ \section1 Command Types
+
+ QDoc interprets three types of commands:
+
+ \list
+ \li \l {Topic Commands}
+ \li \l {Context Commands}
+ \li \l {Markup Commands}
+ \endlist
+
+ Topic commands identify the element you are documenting, for example
+ a C++ class, function, type, or an extra page of text
+ that doesn't map to an underlying C++ element.
+
+ Context commands tell QDoc how the element being documented
+ relates to other documented elements, for example, next and previous page
+ links, inclusion in page groups, or library modules. Context
+ commands can also provide information about the documented element
+ that QDoc can't get from the source files, for example, whether the
+ element is thread-safe, whether it is an overloaded or reimplemented function,
+ or whether it has been deprecated.
+
+ Markup commands tell QDoc how text and image elements in the
+ document should be rendered, or about the document's outline
+ structure.
+*/
+
diff --git a/src/tools/qdoc/doc/qdoc-manual-markupcmds.qdoc b/src/tools/qdoc/doc/qdoc-manual-markupcmds.qdoc
new file mode 100644
index 0000000000..082d2b44e2
--- /dev/null
+++ b/src/tools/qdoc/doc/qdoc-manual-markupcmds.qdoc
@@ -0,0 +1,3967 @@
+/****************************************************************************
+**
+** Copyright (C) 2013 Digia Plc and/or its subsidiary(-ies).
+** Contact: http://www.qt-project.org/legal
+**
+** This file is part of the documentation of the Qt Toolkit.
+**
+** $QT_BEGIN_LICENSE:FDL$
+** Commercial License Usage
+** Licensees holding valid commercial Qt licenses may use this file in
+** accordance with the commercial license agreement provided with the
+** Software or, alternatively, in accordance with the terms contained in
+** a written agreement between you and Digia. For licensing terms and
+** conditions see http://qt.digia.com/licensing. For further information
+** use the contact form at http://qt.digia.com/contact-us.
+**
+** GNU Free Documentation License Usage
+** Alternatively, this file may be used under the terms of the GNU Free
+** Documentation License version 1.3 as published by the Free Software
+** Foundation and appearing in the file included in the packaging of
+** this file. Please review the following information to ensure
+** the GNU Free Documentation License version 1.3 requirements
+** will be met: http://www.gnu.org/copyleft/fdl.html.
+** $QT_END_LICENSE$
+**
+****************************************************************************/
+
+/*!
+ \page 03-qdoc-commands-markup.html
+ \contentspage QDoc Manual
+ \previouspage Naming Things
+ \nextpage Text Markup
+
+ \title Markup Commands
+
+ The markup commands indicate the generated documentation's visual
+ appearance and logical structure.
+
+ \list
+ \li \l {04-qdoc-commands-textmarkup.html#a-command} {\\a}
+ \li \l {11-qdoc-commands-specialcontent.html#abstract-command} {\\abstract}
+ \li \l {12-0-qdoc-commands-miscellaneous.html#annotatedlist-command} {\\annotatedlist}
+ \li \l {04-qdoc-commands-textmarkup.html#b-command} {\\b} \span {class="newStuff"} {(new 5/3/2012)}
+ \li \l {04-qdoc-commands-textmarkup.html#b-command} {\\bold} {(deprecated, use \\b)}
+ \li \l {11-qdoc-commands-specialcontent.html#brief-command} {\\brief}
+ \li \l {04-qdoc-commands-textmarkup.html#c-command} {\\c}
+ \li \l {09-qdoc-commands-includingimages.html#caption-command} {\\caption}
+ \li \l {05-qdoc-commands-documentstructure.html#chapter-command} {\\chapter}
+ \li \l {06-qdoc-commands-includecodeinline.html#code-command} {\\code}
+ \li \l {07-0-qdoc-commands-includingexternalcode.html#codeline-command} {\\codeline}
+ \li \l {04-qdoc-commands-textmarkup.html#div-command} {\\div}
+ \li \l {07-0-qdoc-commands-includingexternalcode.html#dots-command} {\\dots}
+ \li \l {04-qdoc-commands-textmarkup.html#e-command} {\\e} \span {class="newStuff"} {(new 5/3/2012)}
+ \li \l {12-0-qdoc-commands-miscellaneous.html#else-command} {\\else}
+ \li \l {12-0-qdoc-commands-miscellaneous.html#endif-command} {\\endif}
+ \li \l {11-qdoc-commands-specialcontent.html#footnote-command} {\\footnote}
+ \li \l {12-0-qdoc-commands-miscellaneous.html#generatelist-command} {\\generatelist}
+ \li \l {10-qdoc-commands-tablesandlists.html#header-command} {\\header}
+ \li \l {04-qdoc-commands-textmarkup.html#e-command} {\\i} \span {class="newStuff"} {(deprecated, use \\e)}
+ \li \l {12-0-qdoc-commands-miscellaneous.html#if-command} {\\if}
+ \li \l {09-qdoc-commands-includingimages.html#image-command} {\\image}
+ \li \l {12-0-qdoc-commands-miscellaneous.html#include-command} {\\include}
+ \li \l {12-0-qdoc-commands-miscellaneous.html#include-command} {\\input}
+ \li \l {09-qdoc-commands-includingimages.html#inlineimage-command} {\\inlineimage}
+ \li \l {08-qdoc-commands-creatinglinks.html#keyword-command} {\\keyword}
+ \li \l {08-qdoc-commands-creatinglinks.html#l-command} {\\l}
+ \li \l {11-qdoc-commands-specialcontent.html#legalese-command} {\\legalese}
+ \li \l {10-qdoc-commands-tablesandlists.html#li-command} {\\li} \span {class="newStuff"} {(new 5/3/2012)}
+ \li \l {10-qdoc-commands-tablesandlists.html#list-command} {\\list}
+ \li \l {12-0-qdoc-commands-miscellaneous.html#meta-command} {\\meta}
+ \li \l {06-qdoc-commands-includecodeinline.html#newcode-command} {\\newcode}
+ \li \l {10-qdoc-commands-tablesandlists.html#li-command} {\\o} \span {class="newStuff"} {(deprecated, use \\li)}
+ \li \l {11-qdoc-commands-specialcontent.html#note-command} {\\note}
+ \li \l {06-qdoc-commands-includecodeinline.html#oldcode-command} {\\oldcode}
+ \li \l {12-0-qdoc-commands-miscellaneous.html#omit-command} {\\omit}
+ \li \l {05-qdoc-commands-documentstructure.html#part-command} {\\part}
+ \li \l {07-0-qdoc-commands-includingexternalcode.html#printline-command} {\\printline}
+ \li \l {07-0-qdoc-commands-includingexternalcode.html#printto-command} {\\printto}
+ \li \l {07-0-qdoc-commands-includingexternalcode.html#printuntil-command} {\\printuntil}
+ \li \l {11-qdoc-commands-specialcontent.html#quotation-command} {\\quotation}
+ \li \l {07-0-qdoc-commands-includingexternalcode.html#quotefile-command} {\\quotefile}
+ \li \l {07-0-qdoc-commands-includingexternalcode.html#quotefromfile-command} {\\quotefromfile}
+ \li \l {12-0-qdoc-commands-miscellaneous.html#raw-command} {\\raw}
+ \li \l {10-qdoc-commands-tablesandlists.html#row-command} {\\row}
+ \li \l {08-qdoc-commands-creatinglinks.html#sa-command} {\\sa}
+ \li \l {05-qdoc-commands-documentstructure.html#sectionOne-command} {\\section1}
+ \li \l {05-qdoc-commands-documentstructure.html#sectionTwo-command} {\\section2}
+ \li \l {05-qdoc-commands-documentstructure.html#sectionThree-command} {\\section3}
+ \li \l {05-qdoc-commands-documentstructure.html#sectionFour-command} {\\section4}
+ \li \l {07-0-qdoc-commands-includingexternalcode.html#skipline-command} {\\skipline}
+ \li \l {07-0-qdoc-commands-includingexternalcode.html#skipto-command} {\\skipto}
+ \li \l {07-0-qdoc-commands-includingexternalcode.html#skipuntil-command} {\\skipuntil}
+ \li \l {07-0-qdoc-commands-includingexternalcode.html#snippet-command} {\\snippet}
+ \li \l {04-qdoc-commands-textmarkup.html#span-command} {\\span}
+ \li \l {04-qdoc-commands-textmarkup.html#sub-command} {\\sub}
+ \li \l {04-qdoc-commands-textmarkup.html#sup-command} {\\sup}
+ \li \l {10-qdoc-commands-tablesandlists.html#table-command} {\\table}
+ \li \l {11-qdoc-commands-specialcontent.html#tableofcontents-command} {\\tableofcontents}
+ \li \l {08-qdoc-commands-creatinglinks.html#target-command} {\\target}
+ \li \l {04-qdoc-commands-textmarkup.html#tt-command} {\\tt}
+ \li \l {04-qdoc-commands-textmarkup.html#uicontrol-command} {\\uicontrol} {(new 25/3/2012)}
+ \li \l {04-qdoc-commands-textmarkup.html#underline-command} {\\underline}
+ \li \l {12-0-qdoc-commands-miscellaneous.html#raw-command} {\\unicode}
+ \li \l {11-qdoc-commands-specialcontent.html#warning-command} {\\warning}
+ \li \l {04-qdoc-commands-textmarkup.html#backslash-command} {\\\\}
+ \endlist
+*/
+
+
+/*!
+ \page 04-qdoc-commands-textmarkup.html
+ \contentspage QDoc Manual
+ \previouspage Markup Commands
+ \nextpage Document Structure
+
+ \title Text Markup
+
+ The text formatting commands indicate how text is to be rendered.
+
+ \target a-command
+ \section1 \\a (parameter marker)
+
+ The \\a command tells QDoc the next word is a formal parameter name.
+
+ A warning is emitted when a formal parameter is not documented or
+ is misspelled, so when you document a function you should mention
+ each formal parameter by name in the function description,
+ preceded by the \\a command. The parameter name is then rendered
+ in italics.
+
+ \code
+ / *!
+ Constructs a line edit containing the text
+ \a contents. The \a parent parameter is sent
+ to the QWidget constructor.
+ * /
+
+ QLineEdit::QLineEdit(const QString &contents, QWidget *parent) :QWidget(parent)
+ {
+ ...
+ }
+
+ \endcode
+
+ QDoc renders this as:
+
+ \quotation
+ \b {QLineEdit::QLineEdit ( const QString &
+ contents, QWidget *parent )}
+
+ Constructs a line edit containing the text \a contents.
+ The \a parent parameter is sent to the QWidget constructor.
+ \endquotation
+
+ The formal parameter name may be enclosed between curly brackets,
+ but that isn't required.
+
+ \target c-command
+ \section1 \\c (code font)
+
+ The \\c command is used for rendering variable names, user-defined
+ class names, and C++ keywords (for example, \c int and \c for) in the code
+ font.
+
+ The command renders its argument using a monospace font. For
+ example:
+
+ \code
+ / *!
+ The \c AnalogClock class provides a clock widget with hour
+ and minute hands that is automatically updated every
+ few seconds.
+ * /
+ \endcode
+
+ QDoc renders this as:
+
+ \quotation
+ The \c AnalogClock class provides a clock widget with hour
+ and minute hands, which are automatically updated every
+ few seconds.
+ \endquotation
+
+ If the text to be rendered in the code font contains spaces, enclose the
+ entire text in curly brackets.
+
+ \code
+ \c {QLineEdit::QLineEdit(const QString &contents, QWidget *parent) :QWidget(parent)}
+ \endcode
+
+ QDoc renders this as:
+
+ \quotation
+ \c {QLineEdit::QLineEdit(const QString &contents, QWidget *parent) :QWidget(parent)}
+ \endquotation
+
+ The \\c command accepts the special character \c \ within its
+ argument, which renders it as a normal character. So if you want
+ to use nested commands, you must use the \l {tt-command} {teletype
+ (\\tt)} command instead.
+
+ See also \l {tt-command} {\\tt} and \l {code-command} {\\code}.
+
+ \target div-command
+ \section1 \\div
+
+ The \\div and \\enddiv commands delimit a large or small block of
+ text (which may include other QDoc commands) to which special
+ formatting attributes should be applied.
+
+ An argument must be provided in curly braces, as in the qdoc
+ comment shown below. The argument is not interpreted but is used
+ as attribute(s) of the tag that is output by qdoc.
+
+ For example, we might want to render an inline image so that it
+ floats to the right of the current block of text:
+
+ \code
+ / *!
+ \div {class="float-right"}
+ \inlineimage qml-column.png
+ \enddiv
+
+ * /
+ \endcode
+
+ If qdoc is generating HTML, it will translate these commands to:
+
+ \code
+ <div class="float-right"><p><img src="images/qml-column.png" /></p></div>
+ \endcode
+
+ For HTML, the attribute value \e {float-right} then will refer to
+ a clause in the style.css file, which in this case could be:
+
+ \code
+ div.float-right
+ {
+ float: right; margin-left: 2em
+ }
+ \endcode
+
+ If qdoc is generating DITA XML, it will translate the commands to:
+
+ \code
+ <sectiondiv outputclass="float-right">
+ <p>
+ <fig>
+ <image href="images/qml-column.png" placement="inline"/>
+ </fig>
+ </p>
+ </sectiondiv>
+ \endcode
+
+ Your DITA XML publishing program must then recognize the \e
+ {outputclass} attribute value.
+
+ \note Note that the \b {\\div} command can be nested.
+
+ Below you can find an example taken from the index.qdoc file used to
+ generate index.html for Qt 4.7:
+
+ \code
+ \div {class="indexbox guide"}
+ \div {class="heading"}
+ Qt Developer Guide
+ \enddiv
+ \div {class="indexboxcont indexboxbar"}
+ \div {class="section indexIcon"} \emptyspan
+ \enddiv
+ \div {class="section"}
+ Qt is a cross-platform application and UI
+ framework. Using Qt, you can write web-enabled
+ applications once and deploy them across desktop,
+ mobile and embedded operating systems without
+ rewriting the source code.
+ \enddiv
+ \div {class="section sectionlist"}
+ \list
+ \li \l{Getting Started}
+ \li \l{Installation} {Installation}
+ \li \l{how-to-learn-qt.html} {How to learn Qt}
+ \li \l{tutorials.html} {Tutorials}
+ \li \l{Qt Examples} {Examples}
+ \li \l{qt4-7-intro.html} {What's new in Qt 4.7}
+ \endlist
+ \enddiv
+ \enddiv
+ \enddiv
+ \endcode
+
+ When all the class attribute values are defined as they are in the
+ style.css file that is used for rendering the Qt documentation,
+ the above example is rendered as:
+
+ \div {class="indexbox guide"}
+ \div {class="heading"}
+ Qt Developer Guide
+ \enddiv
+ \div {class="indexboxcont indexboxbar"}
+ \div {class="section indexIcon"} \emptyspan
+ \enddiv
+ \div {class="section"}
+ Qt is a cross-platform application and UI
+ framework. Using Qt, you can write web-enabled
+ applications once and deploy them across desktop,
+ mobile and embedded operating systems without
+ rewriting the source code.
+ \enddiv
+ \div {class="section sectionlist"}
+ \list
+ \li Getting Started
+ \li Installation
+ \li How to learn Qt
+ \li Tutorials
+ \li Examples
+ \li What's new in Qt 4.7
+ \endlist
+ \enddiv
+ \enddiv
+ \enddiv
+
+ When generating DITA XML, qdoc outputs the nested \e {div} commands as:
+
+ \code
+ <sectiondiv outputclass="indexbox guide">
+ <sectiondiv outputclass="heading">
+ <p>Qt Developer Guide</p>
+ </sectiondiv>
+ <sectiondiv outputclass="indexboxcont indexboxbar">
+ <sectiondiv outputclass="section indexIcon"/>
+ <sectiondiv outputclass="section">
+ <p>Qt is a cross-platform application and UI
+ framework. Using Qt, you can write
+ web-enabled applications once and deploy
+ them across desktop, mobile and embedded
+ operating systems without rewriting the
+ source code.
+ </p>
+ </sectiondiv>
+ <sectiondiv outputclass="section sectionlist">
+ <ul>
+ <li>
+ <xref href="gettingstarted.xml#id-606ee7a8-219b-47b7-8f94-91bc8c76e54c">Getting started</xref>
+ </li>
+ <li>
+ <xref href="installation.xml#id-075c20e2-aa1e-4f88-a316-a46517e50443">Installation</xref>
+ </li>
+ <li>
+ <xref href="how-to-learn-qt.xml#id-49f509b5-52f9-4cd9-9921-74217b9a5182">How to learn Qt</xref>
+ </li>
+ <li>
+ <xref href="tutorials.xml#id-a737f955-a904-455f-b4aa-0dc69ed5a64f">Tutorials</xref>
+ </li>
+ <li>
+ <xref href="all-examples.xml#id-98d95159-d65b-4706-b08f-13d80080448d">Examples</xref>
+ </li>
+ <li>
+ <xref href="qt4-7-intro.xml#id-519ae0e3-4242-4c2a-b2be-e05d1e95f177">What's new in Qt 4.7</xref>
+ </li>
+ </ul>
+ </sectiondiv>
+ </sectiondiv>
+ </sectiondiv>
+ \endcode
+
+ Your DITA XML publishing program must recognize the values of the
+ \e {outputclass} attribute.
+
+ See also \l {span-command} {\\span}.
+
+ \target span-command
+ \section1 \\span
+
+ The \\span command applies special formatting to a small block of text.
+
+ Two arguments must be provided, each argument in curly braces, as
+ shown in the QDoc comment below. The first argument is not
+ interpreted, but specifies the formatting attribute(s) of the tag
+ output by QDoc. The second argument is the text to be rendered with
+ the special formatting attributes.
+
+ For example, we might want to render the first word of each
+ element in a numeric list in blue.
+
+ \code
+ / *!
+ Global variables with complex types:
+ \list 1
+ \li \span {class="variableName"} {mutableComplex1} in globals.cpp at line 14
+ \li \span {class="variableName"} {mutableComplex2} in globals.cpp at line 15
+ \li \span {class="variableName"} {constComplex1} in globals.cpp at line 16
+ \li \span {class="variableName"} {constComplex2} in globals.cpp at line 17
+ \endlist
+ * /
+ \endcode
+
+ Class \e {variableName} refers to a clause in your style.css.
+
+ \code
+ .variableName
+ {
+ font-family: courier;
+ color: blue
+ }
+ \endcode
+
+ Using the \e {variableName} clause shown above, the example is rendered as:
+
+ Global variables with complex types:
+ \list 1
+ \li \span {class="variableName"} {mutableComplex1} in globals.cpp at line 14
+ \li \span {class="variableName"} {mutableComplex2} in globals.cpp at line 15
+ \li \span {class="variableName"} {constComplex1} in globals.cpp at line 16
+ \li \span {class="variableName"} {constComplex2} in globals.cpp at line 17
+ \endlist
+
+ \note The \b span command does not cause a new paragraph to be
+ started.
+
+ See also \l {div-command} {\\div}.
+
+ \target tt-command
+ \section1 \\tt (teletype font)
+
+ The \\tt command renders its argument in a monospace font. This
+ command behaves just like the \l {c-command} {\\c} command, except
+ that \\tt allows you to nest QDoc commands within the argument
+ (e.g. \l {e-command} {\\e}, \l {b-command} {\\b} and \l
+ {underline-command} {\\underline}).
+
+ \code
+ / *!
+ After having populated the main container with
+ child widgets, \c setupUi() scans the main container's list of
+ slots for names with the form
+ \tt{on_\e{objectName}_\e{signalName}().}
+ * /
+ \endcode
+
+ QDoc renders this as:
+
+ \quotation
+ After having populated the main container with
+ child widgets, \c setupUi() scans the main container's list of
+ slots for names with the form
+ \tt{on_\e{objectName}_\e{signalName}().}
+ \endquotation
+
+ If the text to be rendered in the code font contains spaces, enclose the
+ entire text in curly brackets.
+
+ \code
+ \tt {QLineEdit::QLineEdit(const QString &contents, QWidget *parent) :QWidget(parent)}
+ \endcode
+
+ QDoc renders this as:
+
+ \quotation
+ \tt {QLineEdit::QLineEdit(const QString &contents, QWidget *parent) :QWidget(parent)}
+ \endquotation
+
+ See also \l {c-command} {\\c}.
+
+ \target b-command
+ \section1 \\b
+
+ The \\b command renders its argument in bold font. This command used
+ to be called \\bold.
+
+ \code
+ / *!
+ This is regular text; \b {this text is
+ rendered using the \\b command}.
+ * /
+ \endcode
+
+ QDoc renders this as:
+
+ \quotation
+ This is regular text; \b {this text is rendered using
+ the \\b command}.
+ \endquotation
+
+ \target e-command
+ \section1 \\e (emphasis, italics) \span {class="newStuff"} {(new 5/3/2012)}
+
+ The \\e command renders its argument in a special font, normally italics. This
+ command used to be called \\i, which is now deprecated. Use \e for italics.
+
+ If the argument contains spaces or other punctuation, enclose the
+ argument in curly brackets.
+
+ \code
+ / *!
+ Here, we render \e {a few words} in italics.
+ * /
+ \endcode
+
+ QDoc renders this as:
+
+ \quotation
+ Here, we render \e {a few words} in italics.
+ \endquotation
+
+ If you want to use other QDoc commands within an argument that
+ contains spaces, you always need to enclose the argument in
+ braces. But QDoc is smart enough to count parentheses [3], so you
+ don't need braces in cases like this:
+
+ \code
+ / *!
+ An argument can sometimes contain whitespaces,
+ for example: \e QPushButton(tr("A Brand New Button"))
+ * /
+ \endcode
+
+ QDoc renders this as:
+
+ \quotation
+ An argument can sometimes contain whitespaces,
+ for example: \e QPushButton(tr("A Brand New Button"))
+ \endquotation
+
+ Finally, trailing punctuation is not included in an argument [4],
+ nor is "'s" [5]
+
+ \raw HTML
+ <table align="center" cellpadding="2"
+ cellspacing="1" border="0">
+ <tr valign="top" bgcolor="#a2c511">
+ <th></th>
+ <th>QDoc Syntax</th>
+ <th>Generated Documentation</th>
+ </tr>
+
+ <tr valign="top" bgcolor="#d0d0d0">
+ <td>1</td>
+ <td>A variation of a command button is a \e menu
+ button.</td>
+ <td>A variation of a command button is a <i>menu</i>
+ button.</td>
+ </tr>
+
+ <tr valign="top" bgcolor="#c0c0c0">
+ <td>2</td>
+ <td>The QPushButton widget provides a
+ \e {command button}.</td>
+ <td>The QPushButton widget provides a
+ <i>command button</i>.</td>
+ </tr>
+
+ <tr valign="top" bgcolor="#d0d0d0">
+ <td>3</td>
+ <td>Another class of buttons are option buttons
+ \e (see QRadioButton).</td>
+ <td>Another class of buttons are option buttons
+ <i> (see QRadioButton)</i>.</td>
+ </tr>
+
+ <tr valign="top" bgcolor="#c0c0c0">
+ <td>4</td>
+ <td>A push button emits the signal \e clicked().</td>
+ <td>A push button emits the signal <i>clicked</i>().</td>
+ </tr>
+
+ <tr valign="top" bgcolor="#d0d0d0">
+ <td>5</td>
+ <td>The \e QPushButton's checked property is
+ false by default.</td>
+ <td>The <i>QPushButton</i>'s checked property is
+ false by default.</td>
+ </tr>
+
+ </table>
+ \endraw
+
+ \target sub-command
+ \section1 \\sub
+
+ The \\sub command renders its argument lower than the baseline of
+ the regular text, using a smaller font.
+
+ \code
+ / *!
+ Definition (Range): Consider the sequence
+ {x\sub n}\sub {n > 1} . The set
+
+ {x\sub 2, x\sub 3, x\sub 4, ...} = {x\sub n ; n = 2, 3, 4, ...}
+
+ is called the range of the sequence.
+ * /
+ \endcode
+
+ QDoc renders this as:
+
+ \quotation
+ Definition (Range): Consider the sequence
+ {x\sub n}\sub {n > 1} . The set
+
+ {x\sub 2, x\sub 3, x\sub 4, ...} = {x\sub n ; n = 2, 3, 4, ...}
+
+ is called the range of the sequence.
+ \endquotation
+
+ If the argument contains spaces or other punctuation, enclose the
+ argument in curly brackets.
+
+ \target sup-command
+ \section1 \\sup
+
+ The \\sup command renders its argument higher than
+ the baseline of the regular text, using a smaller font.
+
+ \code
+ / *!
+ The series
+
+ 1 + a + a\sup 2 + a\sup 3 + a\sup 4 + ...
+
+ is called the \i {geometric series}.
+ * /
+ \endcode
+
+ QDoc renders this as:
+
+ \quotation
+ The series
+
+ 1 + a + a\sup 2 + a\sup 3 + a\sup 4 + ...
+
+ is called the \e {geometric series}.
+ \endquotation
+
+ If the argument contains spaces or other punctuation, enclose the
+ argument in curly brackets.
+
+ \target uicontrol-command
+ \section1 \\uicontrol
+
+ The \\uicontrol command is used to mark content as being used for UI
+ control elements. When using HTML, the output is rendered in bold.
+ When using DITA XML the content is enclosed in a \c{uicontrol} tag.
+
+ \sa \\b
+
+ \target underline-command
+ \section1 \\underline
+
+ The \\underline command renders its argument underlined.
+
+ \code
+ / *!
+ The \underline {F}ile menu gives the users the possibility
+ to edit an existing file, or save a new or modified
+ file, and exit the application.
+ * /
+ \endcode
+
+ QDoc renders this as:
+
+ \quotation
+ The \underline {F}ile menu gives the users the possibility
+ to edit an existing file, or save a new or modified
+ file, and exit the application.
+ \endquotation
+
+ If the argument contains spaces or other punctuation, enclose the
+ argument in curly brackets.
+
+ \target backslash-command
+ \section1 \\\\ (double backslash)
+
+ The \\\\ command expands to a double backslash.
+
+ QDoc commands always start with a single backslash. To display a
+ single backslash in the text you need to type two backslashes. If
+ you want to display two backslashes, you need to type four.
+
+ \code
+ / *!
+ The \\\\ command is useful if you want a
+ backslash to appear verbatim, for example,
+ writing C:\\windows\\home\\.
+ * /
+ \endcode
+
+ QDoc renders this as:
+
+ \quotation
+ The \\\\ command is useful if you want a
+ backslash to appear verbatim, for example,
+ writing C:\\windows\\home\\.
+ \endquotation
+
+ However, if you want your text to appear in a monospace font as
+ well, you can use the \l {c-command} {\\c} command instead, which
+ accepts and renders the backslash as any other character. For
+ example:
+
+ \code
+ / *!
+ The \\c command is useful if you want a
+ backslash to appear verbatim, and the word
+ that contains it written in a monospace font,
+ like this: \c {C:\windows\home\}.
+ * /
+ \endcode
+
+ QDoc renders this as:
+
+ \quotation
+ The \\c command is useful if you want a
+ backslash to appear verbatim, and the word
+ that contains it written in a monospace font,
+ like this: \c {C:\windows\home\}.
+ \endquotation
+
+*/
+
+
+/*!
+ \page 05-qdoc-commands-documentstructure.html
+ \previouspage Text Markup
+ \contentspage QDoc Manual
+ \nextpage Including Code Inline
+
+ \title Document Structure
+
+ The document structuring commands are for dividing your document
+ into sections. QDoc supports six kinds of sections: \c \part, \c
+ \chapter, \c \section1, \c \section2, \c \section3, and \c
+ \section4. The \c \section1..4 commands are the most useful. They
+ correspond to the traditional section, subsection, etc used in
+ outlining.
+
+ \target part-command
+ \section1 \\part
+
+ The \\part command is intended for use in a large document, like a
+ book.
+
+ In general a document structuring command considers everything
+ that follows it until the first line break as its argument. The
+ argument is rendered as the unit's title. If the title needs to be
+ spanned over several lines, make sure that each line (except the
+ last one) is ended with a backslash.
+
+ In total, there are six levels of sections in QDoc: \c \part, \c
+ \chapter, \c \section1, \c \section2, \c \section3 and \c
+ \section4. \c \section1 to \c \section4 correspond to the
+ traditional section, subsection, subsubsection and
+ subsubsubsection.
+
+ There is a strict ordering of the section units:
+
+ \code
+ part
+ |
+ chapter
+ |
+ section1
+ |
+ section2
+ |
+ section3
+ |
+ section4
+ \endcode
+
+ For example, a \c section1 unit can only appear as the top level
+ section or inside a \c chapter unit. Skipping a section unit, for
+ example from \c part to \c section1, is not allowed.
+
+ You can \e begin with either of the three: \c part, \c chapter or
+ \c section1.
+
+
+ \code
+ / *!
+ \part Basic Qt
+
+ This is the first part.
+
+
+ \chapter Getting Started
+
+ This is the first part's first chapter.
+
+
+ \section1 Hello Qt
+
+ This is the first chapter's first section.
+
+
+ \section1 Making Connections
+
+ This is the first chapter's second section.
+
+
+ \section1 Using the Reference Documentation
+
+ This is the first chapter's third section.
+
+
+ \chapter Creating Dialogs
+
+ This is the first part's second chapter.
+
+
+ \section1 Subclassing QDialog
+
+ This is the second chapter's first section.
+
+ ...
+
+
+ \part Intermediate Qt
+
+ This is the second part.
+
+
+ \chapter Layout Management
+
+ This is the second part's first chapter.
+
+
+ \section1 Basic Layouts
+
+ This is the first chapter's first section.
+
+ ...
+ * /
+ \endcode
+
+ QDoc renders this as:
+
+ \quotation
+ \raw HTML
+ <a name="Basic Qt">
+ <h1>Basic Qt</h1>
+ </a>
+ <p>This is the first part.</p>
+
+ <a name="Getting started">
+ <h2>Getting Started</h2>
+ </a>
+ This is the first part's first chapter.</p>
+
+ <a name="Hello Qt">
+ <h3>Hello Qt</h3>
+ </a>
+ <p>This is the first chapter's first section.</p>
+
+ <a name="Making Connections">
+ <h3>Making Connections</h3>
+ </a>
+ <p>This is the first chapter's second section.</p>
+
+ <a name="Using the Reference Documentation">
+ <h3>Using the Reference Documentation</h3>
+ </a>
+ <p>This is the first chapter's third section.</p>
+
+ <a name="Creating Dialogs">
+ <h2>Creating Dialogs</h2>
+ </a>
+ <p>This is the first part's second chapter.</p>
+
+ <a name="Subclassing QDialog">
+ <h3>Subclassing QDialog</h3>
+ </a>
+ <p>This is the second chapter's first section.</p>
+
+ ...
+
+ <a name="Intermediate Qt">
+ <h1>Intermediate Qt</h1>
+ </a>
+ <p>This is the second part.</p>
+
+ <a name="Layout Management">
+ <h2>Layout Management</h2>
+ </a>
+ <p>This is the second part's first chapter.</p>
+
+ <a name="Basic Layouts">
+ <h3>Basic Layouts</h3>
+ </a>
+ <p>This is the first chapter's first section.</p>
+
+ ...
+
+ \endraw
+ \endquotation
+
+ Each section is a logical unit in the document. The section
+ heading appears in the automatically generated table of contents
+ that normally appears in the upper right-hand corner of the page.
+
+ \target chapter-command
+ \section1 \\chapter
+
+ The \\chapter command is intended for use in
+ larger documents, and divides the document into chapters.
+
+ See \l{part} {\\part} for an explanation of the various
+ section units, command argument, and rendering.
+
+ \target sectionOne-command
+ \section1 \\section1
+
+ The \\section1 command starts a new section.
+
+ See \l{part} {\\part} for an explanation of the various
+ section units, command argument, and rendering.
+
+ \target sectionTwo-command
+ \section1 \\section2
+
+ The \\section2 command starts a new section.
+
+ See \l{part} {\\part} for an explanation of the various
+ section units, command argument, and rendering.
+
+ \target sectionThree-command
+ \section1 \\section3
+
+ The \\section3 command starts a new section.
+
+ See \l{part} {\\part} for an explanation of the various
+ section units, command argument, and rendering.
+
+ \target sectionFour-command
+ \section1 \\section4
+
+ The \\section4 command starts a new section.
+
+ See \l{part} {\\part} for an explanation of the various
+ section units, command argument, and rendering.
+
+*/
+
+
+/*!
+ \page 06-qdoc-commands-includecodeinline.html
+ \previouspage Document Structure
+ \contentspage QDoc Manual
+ \nextpage Including External Code
+
+ \title Including Code Inline
+
+ The following commands are used to render source code without
+ formatting. The source code begins on a new line, rendered in the
+ code.
+
+ \b{Note:} Although all these commands are for rendering C++
+ code, the
+ \l{07-0-qdoc-commands-includingexternalcode.html#snippet-command}
+ {\\snippet} and
+ \l{07-0-qdoc-commands-includingexternalcode.html#codeline-command}
+ {\\codeline} commands are preferred over the others. These
+ commands allow equivalent code snippets for other Qt language
+ bindings to be substituted for the C++ snippets in the
+ documentation.
+
+ \target code-command
+ \section1 \\code
+
+ The \\code and \\endcode commands enclose a snippet of source code.
+
+ \note The \l {c-command} {\\c} command can be used for short code
+ fragments within a sentence. The \\code command is for longer code
+ snippets. It renders the code verbatim in a separate paragraph in
+ the code font.
+
+ When processing any of the \\code, \l {newcode-command} {\\newcode} or \l
+ {oldcode-command} {\\oldcode} commands, QDoc removes all
+ indentation that is common for the verbatim code blocks within a
+ \c{/}\c{*!} ... \c{*}\c{/} comment before it adds the standard
+ indentation. For that reason the recommended style is to use 8
+ spaces for the verbatim code contained within these commands
+
+ \note This doesn't apply to externally quoted code using the \l
+ {quotefromfile-command} {\\quotefromfile} or \l
+ {quotefile-command} {\\quotefile} command.
+
+ \code
+ / *!
+ \code
+ #include <QApplication>
+ #include <QPushButton>
+
+ int main(int argc, char *argv[])
+ {
+ ...
+ }
+ \ endcode
+ * /
+ \endcode
+
+ QDoc renders this as:
+
+ \code
+ #include <QApplication>
+ #include <QPushButton>
+
+ int main(int argc, char *argv[])
+ {
+ ...
+ }
+ \endcode
+
+ Other QDoc commands are disabled within \\code... \\endcode, and
+ the special character '\\' is accepted and rendered like the rest
+ of the code.
+
+ To include code snippets from an external file, use the
+ \l{07-0-qdoc-commands-includingexternalcode.html#snippet-command}
+ {\\snippet} and
+ \l{07-0-qdoc-commands-includingexternalcode.html#codeline-command}
+ {\\codeline} commands.
+
+ See also \l {c-command} {\\c}, \l
+ {07-0-qdoc-commands-includingexternalcode.html#quotefromfile-command}
+ {\\quotefromfile}, \l{newcode-command} {\\newcode}, and \l {oldcode-command}
+ {\\oldcode}.
+
+ \target newcode-command
+ \section1 \\newcode
+
+ The \\newcode, \\oldcode, and \\endcode commands enable you to
+ show how to port a snippet of code to a new version of an API.
+
+ The \\newcode command and its companion the \\oldcode command are
+ a convenience combination of the \l {code-command} {\\code} commands:
+ this combination provides a text relating the two code snippets to each
+ other.
+
+ The \\newcode command requires a preceding \\oldcode statement.
+
+ Like the \l{code-command}{\\code} command, the \\newcode command renders its
+ code on a new line in the documentation using a monospace font and the
+ standard indentation.
+
+ \code
+ / *!
+ \oldcode
+ if (printer->setup(parent))
+ ...
+ \newcode
+ QPrintDialog dialog(printer, parent);
+ if (dialog.exec())
+ ...
+ \ endcode
+ * /
+ \endcode
+
+ QDoc renders this as:
+
+ \quotation
+ \oldcode
+ if (printer->setup(parent))
+ ...
+ \newcode
+ QPrintDialog dialog(printer, parent);
+ if (dialog.exec())
+ ...
+ \endcode
+ \endquotation
+
+ Other QDoc commands are disabled within \\oldcode ... \\endcode,
+ and the '\\' character doesn't need to be escaped.
+
+ \target oldcode-command
+ \section1 \\oldcode
+
+ The \\oldcode command requires a corresponding
+ \\newcode statement; otherwise QDoc fails to parse the command
+ and emits a warning.
+
+ See also \l {newcode-command} {\\newcode}.
+
+ \target qml-command
+ \section1 \\qml
+
+ The \\qml and \\endqml commands enclose a snippet of QML source
+ code. Currently, QDoc handles \\qml and \\endqml in exactly the same
+ way as \\code and \\endcode.
+
+ \code
+ / *!
+ \qml
+ import QtQuick 1.0
+
+ Row {
+ Rectangle {
+ width: 100; height: 100
+ color: "blue"
+ transform: Translate { y: 20 }
+ }
+ Rectangle {
+ width: 100; height: 100
+ color: "red"
+ transform: Translate { y: -20 }
+ }
+ }
+ \endqml
+ * /
+ \endcode
+
+ QDoc renders this as:
+
+ \qml
+ import QtQuick 1.0
+
+ Row {
+ Rectangle {
+ width: 100; height: 100
+ color: "blue"
+ transform: Translate { y: 20 }
+ }
+ Rectangle {
+ width: 100; height: 100
+ color: "red"
+ transform: Translate { y: -20 }
+ }
+ }
+ \endqml
+*/
+
+
+/*!
+ \page 07-0-qdoc-commands-includingexternalcode.html
+ \previouspage Including Code Inline
+ \contentspage QDoc Manual
+ \nextpage Creating Links
+
+ \title Including External Code
+
+ The following commands enable you to include code snippets from
+ external files. You can make QDoc include the complete contents of
+ a file, or you can quote specific parts of the file and skip
+ others. The typical use of the latter is to quote a file chunk by
+ chunk.
+
+ \b{Note:} Although all these commands are for rendering C++
+ code, the
+ \l{07-0-qdoc-commands-includingexternalcode.html#snippet-command}
+ {\\snippet} and
+ \l{07-0-qdoc-commands-includingexternalcode.html#codeline-command}
+ {\\codeline} commands are preferred over the others. These
+ commands allow equivalent code snippets for other Qt language
+ bindings to be substituted for the C++ snippets in the
+ documentation.
+
+ \target quotefile-command
+ \section1 \\quotefile
+
+ The \\quotefile command expands to the complete contents of the
+ file given as argument.
+
+ The command considers the rest of the line as part of its
+ argument, make sure to follow the file name with a line break.
+
+ The file's contents is rendered in a separate paragraph, using a
+ monospace font and the standard indentation. The code is shown
+ verbatim.
+
+ \code
+ / *!
+ This is a simple "Hello world" example:
+
+ \quotefile examples/main.cpp
+
+ It contains only the bare minimum you need
+ to get a Qt application up and running.
+ * /
+ \endcode
+
+ QDoc renders this as:
+
+ \quotation
+ This is a simple "Hello world" example:
+
+ \quotefile examples/main.cpp
+
+ It contains only the bare minimum you need to get a Qt
+ application up and running.
+ \endquotation
+
+ See also \l {quotefromfile-command} {\\quotefromfile} and
+ \l {code-command} {\\code}.
+
+
+ \target quotefromfile-command
+ \section1 \\quotefromfile
+
+ The \\quotefromfile command opens the file given as argument for
+ quoting.
+
+ The command considers the rest of the line as part of its
+ argument, make sure to follow the file name with a line break.
+
+ The command is intended for use when quoting parts from file with
+ the walkthrough commands: \l {printline-command} {\\printline}, \l
+ {printto-command} {\\printto}, \l {printuntil-command}
+ {\\printuntil}, \l {skipline-command} {\\skipline}, \l
+ {skipto-command} {\\skipto}, \l {skipuntil-command}
+ {\\skipuntil}. This enables you to quote specific portions of a
+ file.
+
+ \code
+ / *!
+ The whole application is contained within
+ the \c main() function:
+
+ \quotefromfile examples/main.cpp
+
+ \skipto main
+ \printuntil app(argc, argv)
+
+ First we create a QApplication object using
+ the \c argc and \c argv parameters.
+
+ \skipto QPushButton
+ \printuntil resize
+
+ Then we create a QPushButton, and give it a reasonable
+ size using the QWidget::resize() function.
+
+ ...
+ * /
+ \endcode
+
+ QDoc renders this as:
+
+ \quotation
+ The whole application is contained within
+ the \c main() function:
+
+ \quotefromfile examples/main.cpp
+
+ \skipto main
+ \printuntil app(argc, argv)
+
+ First we create a QApplication object using the \c argc
+ and \c argv parameters.
+
+ \skipto QPushButton
+ \printuntil resize
+
+ Then we create a QPushButton, and give it a reasonable
+ size using the QWidget::resize() function.
+
+ ...
+ \endquotation
+
+ QDoc remembers which file it is quoting from, and the current
+ position in that file (see \l {file} {\\printline} for more
+ information). There is no need to "close" the file.
+
+ See also \l {quotefile-command} {\\quotefile}, \l {code-command}
+ {\\code} and \l {dots} {\\dots}.
+
+ \target printline-command
+ \section1 \\printline
+
+ The \\printline command expands to the line from the current
+ position to the next non-blank line of the current source file.
+
+ To ensure that the documentation remains synchronized with the
+ source file, a substring of the line must be specified as an
+ argument to the command. Note that the command considers the rest
+ of the line as part of its argument, make sure to follow the
+ substring with a line break.
+
+ The line from the source file is rendered as a separate paragraph,
+ using a monospace font and the standard indentation. The code is
+ shown verbatim.
+
+ \code
+ / *!
+ There has to be exactly one QApplication object
+ in every GUI application that uses Qt.
+
+ \quotefromfile examples/main.cpp
+
+ \printline QApplication
+
+ This line includes the QApplication class
+ definition. QApplication manages various
+ application-wide resources, such as the
+ default font and cursor.
+
+ \printline QPushButton
+
+ This line includes the QPushButton class
+ definition. The QPushButton widget provides a command
+ button.
+
+ \printline main
+
+ The main function...
+ * /
+ \endcode
+
+ QDoc renders this as:
+
+ \quotation
+ There has to be exactly one QApplication object
+ in every GUI application that uses Qt.
+
+ \quotefromfile examples/main.cpp
+
+ \skipto QApplication
+ \printline QApplication
+
+ This line includes the QApplication class
+ definition. QApplication manages various
+ application-wide resources, such as the
+ default font and cursor.
+
+ \printline QPushButton
+
+ This line includes the QPushButton class
+ definition. The QPushButton widget provides a command
+ button.
+
+ \printline main
+
+ The main function...
+ \endquotation
+
+ \target file
+
+ QDoc reads the file sequentially. To move the current position
+ forward you can use either of the \l {skipline-command}
+ {\\skip...} commands. To move the current position backward, you
+ can use the \l {quotefromfile-command} {\\quotefromfile} command
+ again.
+
+ \target substring
+
+ If the substring argument is surrounded by slashes it is
+ interpreted as a \l {QRegExp}{regular expression}.
+
+ \code
+ / *!
+ \quotefromfile examples/mainwindow.cpp
+
+ \skipto closeEvent
+ \printuntil /^\}/
+
+ Close events are sent to widgets that the users want to
+ close, usually by clicking \c File|Exit or by clicking
+ the \c X title bar button. By reimplementing the event
+ handler, we can intercept attempts to close the
+ application.
+ * /
+ \endcode
+
+ QDoc renders this as:
+
+ \quotation
+ \quotefromfile examples/mainwindow.cpp
+
+ \skipto closeEvent
+ \printuntil /^\}/
+
+ Close events are sent to widgets that the users want to
+ close, usually by clicking \c File|Exit or by clicking
+ the \c X title bar button. By reimplementing the event
+ handler, we can intercept attempts to close the
+ application.
+ \endquotation
+
+ (\l {widgets/scribble} {The complete example file...})
+
+ The regular expression \c /^\}/ makes QDoc print until the first
+ '}' character occurring at the beginning of the line without
+ indentation. /.../ encloses the regular expression, and '^' means
+ the beginning of the line. The '}' character must be escaped since
+ it is a special character in regular expressions.
+
+ QDoc will emit a warning if the specified substring or regular
+ expression cannot be located, i.e. if the source code has changed.
+
+ See also \l {printto-command} {\\printto} and \l
+ {printuntil-command} {\\printuntil}.
+
+ \target printto-command
+ \section1 \\printto
+
+ The \\printto command expands to all the lines from the current
+ position up to and \e excluding the next line containing a given
+ substring.
+
+ The command considers the rest of the line as part of its
+ argument, make sure to follow the substring with a line break. The
+ command also follows the same conventions for \l {file}
+ {positioning} and \l {substring} {argument} as the \l
+ {printline-command} {\\printline} command.
+
+ The lines from the source file are rendered in a separate
+ paragraph, using a monospace font and the standard
+ indentation. The code is shown verbatim.
+
+ \code
+ / *!
+ The whole application is contained within the
+ \c main() function:
+
+ \quotefromfile examples/main.cpp
+ \printto hello
+
+ First we create a QApplication object using the \c argc and
+ \c argv parameters...
+ * /
+ \endcode
+
+ QDoc renders this as:
+
+ \quotation
+ The whole application is contained within the
+ \c main() function:
+
+ \quotefromfile examples/main.cpp
+ \skipto main
+ \printto hello
+
+ First we create a QApplication object using the \c argc
+ and \c argv parameters...
+ \endquotation
+
+ See also \l {printline-command} {\\printline} and \l
+ {printuntil-command} {\\printuntil}.
+
+ \target printuntil-command
+ \section1 \\printuntil
+
+ The \\printuntil command expands to all the lines from the current
+ position up to and \e including the next line containing a given
+ substring.
+
+ The command considers the rest of the line as part of its
+ argument, make sure to follow the substring with a line break. The
+ command also follows the same conventions for \l {file}
+ {positioning} and \l {substring} {argument} as the \l
+ {printline-command} {\\printline} command.
+
+ The lines from the source file are rendered in a separate
+ paragraph, using a monospace font and the standard
+ indentation. The code is shown verbatim.
+
+ \code
+ / *!
+ The whole application is contained within the
+ \c main() function:
+
+ \quotefromfile examples/main.cpp
+ \skipto main
+ \printuntil hello
+
+ First we create a QApplication object using the
+ \c argc and \c argv parameters, then we create
+ a QPushButton.
+ * /
+ \endcode
+
+ QDoc renders this as:
+
+ \quotation
+ The whole application is contained within the
+ \c main() function:
+
+ \quotefromfile examples/main.cpp
+ \skipto main
+ \printuntil hello
+
+ First we create a \l
+ {http://qt-project.org/doc/qt-5.0/qtwidgets/qapplication.html} {QApplication}
+ object using the \c argc and \c argv parameters, then we
+ create a \l
+ {http://qt-project.org/doc/qt-5.0/qtwidgets/qpushbutton.html} {QPushButton}.
+ \endquotation
+
+ See also \l {printline-command} {\\printline} and \l
+ {printto-command} {\\printto}.
+
+ \target skipline-command
+ \section1 \\skipline
+
+ The \\skipline command ignores the next non-blank line in the
+ current source file.
+
+ Doc reads the file sequentially, and the \\skipline command is
+ used to move the current position (omitting a line of the source
+ file). See the remark about \l {file} {file positioning} above.
+
+ The command considers the rest of the line as part of its
+ argument, make sure to follow the substring with a line break. The
+ command also follows the same conventions for \l {substring}
+ {argument} as the \l {printline-command} {\\printline} command,
+ and it is used in conjunction with the \l {quotefromfile-command}
+ {\\quotefromfile} command.
+
+ \code
+ / *!
+ QPushButton is a GUI push button that the user
+ can press and release.
+
+ \quotefromfile examples/main.cpp
+ \skipline QApplication
+ \printline QPushButton
+
+ This line includes the QPushButton class
+ definition. For each class that is part of the
+ public Qt API, there exists a header file of
+ the same name that contains its definition.
+ * /
+ \endcode
+
+ QDoc renders this as:
+
+ \quotation
+ \l
+ QPushButton is a GUI push button that the user
+ can press and release.
+
+ \quotefromfile examples/main.cpp
+ \skipto QApplication
+ \skipline QApplication
+ \printline QPushButton
+
+ This line includes the QPushButton class
+ definition. For each class that is part of the public
+ Qt API, there exists a header file of the same name
+ that contains its definition.
+ \endquotation
+
+ See also \l {skipto-command} {\\skipto}, \l {skipuntil-command}
+ {\\skipuntil} and \l {dots} {\\dots}.
+
+ \target skipto-command
+ \section1 \\skipto
+
+ The \\skipto command ignores all the lines from the current
+ position up to and \e excluding the next line containing a given
+ substring.
+
+ QDoc reads the file sequentially, and the \\skipto command is used
+ to move the current position (omitting one or several lines of the
+ source file). See the remark about \l {file} {file positioning}
+ above.
+
+ The command considers the rest of the line as part of its
+ argument, make sure to follow the substring with a line break.
+
+ The command also follows the same conventions for \l {substring}
+ {argument} as the \l {printline-command} {\\printline} command,
+ and it is used in conjunction with the \l {quotefromfile-command}
+ {\\quotefromfile} command.
+
+ \code
+ / *!
+ The whole application is contained within
+ the \c main() function:
+
+ \quotefromfile examples/main.cpp
+ \skipto main
+ \printuntil }
+
+ First we create a QApplication object. There
+ has to be exactly one such object in
+ every GUI application that uses Qt. Then
+ we create a QPushButton, resize it to a reasonable
+ size...
+ * /
+ \endcode
+
+ QDoc renders this as:
+
+ \quotation
+ The whole application is contained within
+ the \c main() function:
+
+ \quotefromfile examples/main.cpp
+ \skipto main
+ \printuntil }
+
+ First we create a QApplication object. There has to be
+ exactly one such object in every GUI application that
+ uses Qt. Then we create a QPushButton, resize it to a
+ reasonable size ...
+ \endquotation
+
+ See also \l {skipline-command} {\\skipline}, \l
+ {skipuntil-command} {\\skipuntil} and \l {dots} {\\dots}.
+
+ \target skipuntil-command
+ \section1 \\skipuntil
+
+ The \\skipuntil command ignores all the lines from the current
+ position up to and \e including the next line containing a given
+ substring.
+
+ QDoc reads the file sequentially, and the \\skipuntil command is
+ used to move the current position (omitting one or several lines
+ of the source file). See the remark about \l {file} {file
+ positioning} above.
+
+ The command considers the rest of the line as part of its
+ argument, make sure to follow the substring with a line break.
+
+ The command also follows the same conventions for \l {substring}
+ {argument} as the \l {printline-command} {\\printline} command,
+ and it is used in conjunction with the \l {quotefromfile-command}
+ {\\quotefromfile} command.
+
+ \code
+ / *!
+ The first thing we did in the \c main() function
+ was to create a QApplication object \c app.
+
+ \quotefromfile examples/main.cpp
+ \skipuntil show
+ \dots
+ \printuntil }
+
+ In the end we must remember to make \c main() pass the
+ control to Qt. QCoreApplication::exec() will return when
+ the application exits...
+ * /
+ \endcode
+
+ QDoc renders this as:
+
+ \quotation
+ The first thing we did in the \c main() function was to
+ create a QApplication object \c app.
+
+ \quotefromfile examples/main.cpp
+ \skipuntil show
+ \dots
+ \printuntil }
+
+ In the end we must remember to make \c main() pass the
+ control to Qt. QCoreApplication::exec()
+ will return when the application exits...
+ \endquotation
+
+ See also \l {skipline-command} {\\skipline}, \l {skipto-command}
+ {\\skipto} and \l {dots} {\\dots}.
+
+ \target dots-command
+ \section1 \\dots
+
+ The \\dots command indicates that parts of the source file have
+ been omitted when quoting a file.
+
+ The command is used in conjunction with the \l
+ {quotefromfile-command} {\\quotefromfile} command, and should be
+ stated on its own line. The dots are rendered on a new line, using
+ a monospace font.
+
+ \code
+ / *!
+ \quotefromfile examples/main.cpp
+ \skipto main
+ \printuntil {
+ \dots
+ \skipuntil exec
+ \printline }
+ * /
+ \endcode
+
+ QDoc renders this as:
+
+ \quotefromfile examples/main.cpp
+ \skipto main
+ \printuntil {
+ \dots
+ \skipuntil exec
+ \printline }
+
+ The default indentation is 4 spaces, but this can be adjusted
+ using the command's optional argument.
+
+ \code
+ / *!
+ \dots 0
+ \dots
+ \dots 8
+ \dots 12
+ \dots 16
+ * /
+ \endcode
+
+ QDoc renders this as:
+
+ \dots 0
+ \dots
+ \dots 8
+ \dots 12
+ \dots 16
+
+ See also \l {skipline-command} {\\skipline}, \l {skipto-command}
+ {\\skipto} and \l {skipuntil-command} {\\skipuntil}.
+
+ \target snippet-command
+ \section1 \\snippet
+
+ The \\snippet command causes a code snippet to be included
+ verbatim as preformatted text, which may be syntax highlighted.
+
+ Each code snippet is referenced by the file that holds it and by
+ a unique identifier for that file. Snippet files are typically
+ stored in a \c{snippets} directory inside the documentation
+ directory (for example, \c{$QTDIR/doc/src/snippets}).
+
+ For example, the following documentation references a snippet in a
+ file residing in a subdirectory of the documentation directory:
+
+ \code
+ \snippet snippets/textdocument-resources/main.cpp Adding a resource
+ \endcode
+
+ The text following the file name is the unique identifier for the
+ snippet. This is used to delimit the quoted code in the relevant
+ snippet file, as shown in the following example that corresponds to
+ the above \c{\\snippet} command:
+
+ \dots
+ \code
+ QImage image(64, 64, QImage::Format_RGB32);
+ image.fill(qRgb(255, 160, 128));
+
+ //! [Adding a resource]
+ document->addResource(QTextDocument::ImageResource,
+ QUrl("mydata://image.png"), QVariant(image));
+ //! [Adding a resource]
+ \endcode
+ \dots
+
+ \target codeline-command
+ \section1 \\codeline
+
+ The \\codeline command inserts a blank line of preformatted
+ text. It is used to insert gaps between snippets without closing
+ the current preformatted text area and opening a new one.
+
+*/
+
+
+/*!
+ \page 08-qdoc-commands-creatinglinks.html
+ \previouspage Including External Code
+ \contentspage QDoc Manual
+ \nextpage Including Images
+
+ \title Creating Links
+
+ These commands are for creating hyperlinks to classes, functions,
+ examples, and other targets.
+
+ \target l-command
+ \section1 \\l (link)
+
+ The \\l link command is used to create a hyperlink to many
+ different kinds of targets. The command's general syntax is:
+
+ \code
+ \l {link target} {link text}
+ \endcode
+
+ \code
+ / *!
+ Read the \l {http://qt-project.org/doc/qt-5.0/}
+ {Qt 5.0 Documentation} carefully.
+ * /
+ \endcode
+
+ QDoc renders this as:
+
+ \quotation
+ Read the \l {http://qt-project.org/doc/qt-5.0/}
+ {Qt 5.0 Documentation} carefully.
+ \endquotation
+
+ If the link target is equivalent to the link text, the second
+ argument can be omitted.
+
+ For example, if you have documentation like:
+
+ \code
+ / *!
+ \target assertions
+
+ Assertions make some statement about the text at the
+ point where they occur in the regexp, but they do not
+ match any characters.
+
+ ...
+
+ Regexps are built up from expressions, quantifiers, and
+ \l {assertions} {assertions}.
+ * /
+ \endcode
+
+ You can simplify this as follows:
+
+ \code
+ / *!
+ \target assertions
+
+ Assertions make some statement about the text at the
+ point where they occur in the regexp, but they do not
+ match any characters.
+
+ ...
+
+ Regexps are built up from expressions, quantifiers, and
+ \l assertions.
+ * /
+ \endcode
+
+ For the one-parameter version, the braces can often be omitted.
+ The \\l command supports several kinds of links:
+
+ \list
+
+ \li \c {\l QWidget} - The name of a class documented with the \l
+ {class-command} {\\class} command.
+
+ \li \c {\l QWidget::sizeHint()} - The name of a member function,
+ documented with or without an \l {fn-command} {\\fn} command.
+
+ \li \c {\l <QtGlobal>} - The subject of a \l {headerfile-command}
+ {\\headerfile} command.
+
+ \li \c {\l widgets/wiggly} - The relative path used in an \l
+ {example-command} {\\example} command.
+
+ \li \c {\l {QWidget Class Reference}} - The title used in a
+ \l {title-command} {\\title} command.
+
+ \li \c {\l {Introduction to QDoc}}- The text from one of the
+ \l{part-command} {\\part}, \l{chapter} {\\chapter}, or \l
+ {sectionOne-command} {\\section} commands.
+
+ \li \c {\l fontmatching} - The argument of a \l {target-command}
+ {\\target} command.
+
+ \li \c {\l {Shared Classes}} - A keyword named in a \l
+ {keyword-command} {\\keyword} command.
+
+ \li \c {\l network.html} - The file name used in a \l
+ {page-command} {\\page} command.
+
+ \li \c {\l http://qt-project.org/} - A URL.
+
+ \endlist
+
+ QDoc also tries to make a link out of any word that doesn't
+ resemble a normal English word, for example, Qt class names or
+ functions, like QWidget or QWidget::sizeHint(). In these cases,
+ the \\l command can actually be omitted, but by using the command,
+ you ensure that QDoc will emit a warning if it cannot find the
+ link target. In addition, if you only want the function name to
+ appear in the link, you can use the following syntax:
+
+ \list
+ \li \c {\l {QWidget::} {sizeHint()}}
+ \endlist
+
+ QDoc renders this as:
+
+ \quotation
+ \l {QWidget::} {sizeHint()}
+ \endquotation
+
+ See also \l {sa-command} {\\sa}, \l {target-command} {\\target},
+ and \l {keyword-command} {\\keyword}.
+
+
+ \target sa-command
+ \section1 \\sa (see also)
+
+ The \\sa command defines a list of links that will be rendered in
+ a separate "See also" section at the bottom of the documentation
+ unit.
+
+ The command takes a comma-separated list of links as its
+ argument. If the line ends with a comma, you can continue
+ the list on the next line. The general syntax is:
+
+ \code
+ \sa {the first link}, {the second link},
+ {the third link}, ...
+ \endcode
+
+ QDoc will automatically try to generate "See also" links
+ interconnecting a property's various functions. For example, a
+ setVisible() function will automatically get a link to visible()
+ and vice versa.
+
+ In general, QDoc will generate "See also" links that interconnect
+ the functions that access the same property. It recognizes four
+ different syntax versions:
+
+ \list
+ \li \c property()
+ \li \c setProperty()
+ \li \c isProperty()
+ \li \c hasProperty()
+ \endlist
+
+ The \\sa command supports the same kind of links as the \l
+ {l-command} {\\l} command.
+
+ \code
+ / *!
+ Appends the actions \a actions to this widget's
+ list of actions.
+
+ \sa removeAction(), QMenu, addAction()
+ * /
+ void QWidget::addActions(QList<QAction *> actions)
+ {
+ ...
+ }
+ \endcode
+
+ QDoc renders this as:
+
+ \quotation
+ \b {void QWidget::addActions ( QList<QAction*>
+ \e actions )}
+
+ Appends the actions \e actions to this widget's list of
+ actions.
+
+ See also \l {QWidget::removeAction()} {removeAction()},
+ \l QMenu, and \l {QWidget::addAction()} {addAction()}.
+ \endquotation
+
+ See also \l {l-command} {\\l}, \l {target-command} {\\target} and
+ \l {keyword-command} {\\keyword}.
+
+
+ \target target-command
+ \section1 \\target
+
+ The \\target command names a place in the documentation that you
+ can link to using the \l {l-command} {\\l (link)} and \l
+ {sa-command} {\\sa (see also)} commands.
+
+ The text up to the line break becomes the target name. Be sure to
+ follow the target name with a line break. Curly brackets are not
+ required around the target name, but they may be required when the
+ target name is used in a link command. See below.
+
+ \code
+ / *!
+ \target capturing parentheses
+ \section1 Capturing Text
+
+ Parentheses allow us to group elements together so that
+ we can quantify and capture them.
+
+ ...
+ * /
+ \endcode
+
+ The target name \e{capturing parentheses} can be linked from
+ within the same document containing the target in two ways:
+
+ \list
+ \li \c {\l {capturing parentheses}} (from within the same QDoc comment)
+ \li \c {\l qregexp.html#capturing-parentheses} (from elsewhere in the same document)
+ \endlist
+
+ \note The brackets in the link example are required because the
+ target name contains spaces.
+
+ The target name can be linked to in the following way from other documents:
+
+ \list
+ \li \c {\l http://qt-project.org/doc/qt-5.0/qtcore/qregexp.html#capturing-parentheses}
+ \endlist
+
+ 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, but stronger. A keyword can be linked from anywhere using
+ a simple syntax.
+
+ Keywords must be unique over all the documents processed during
+ the QDoc run. The command uses the rest of the line as its
+ argument. Be sure to follow the keyword with a line break.
+
+
+ \code
+ / *!
+ \class QRegExp
+ \reentrant
+ \brief The QRegExp class provides pattern
+ matching using regular expressions.
+ \ingroup tools
+ \ingroup misc
+ \ingroup shared
+ \mainclass
+
+ \keyword regular expression
+
+ Regular expressions, or "regexps", provide a way to
+ find patterns within text.
+
+ ...
+ * /
+ \endcode
+
+ The location marked with the keyword can be linked to with:
+
+ \code
+ / *!
+ When a string is surrounded by slashes, it is
+ interpreted as a \l {QRegExp}{regular expression}.
+ * /
+ \endcode
+
+ QDoc renders this as:
+
+ \quotation
+ When a string is surrounded by slashes, it is
+ interpreted as a \l {QRegExp}{regular expression}.
+ \endquotation
+
+ If the keyword text contains spaces, the brackets are required.
+
+ See also \l {l-command} {\\l (link)}, \l {sa-command} {\\sa (see
+ also)} and \l {target-command} {\\target}.
+
+*/
+
+
+/*!
+ \page 09-qdoc-commands-includingimages.html
+ \previouspage Creating Links
+ \contentspage QDoc Manual
+ \nextpage Tables and Lists
+
+ \title Including Images
+
+ The graphic commands makes it possible to include images in the
+ documentation. The images can be rendered as separate paragraphs,
+ or within running text.
+
+ \target image-command
+ \section1 \\image
+
+ The \\image command expands to the image specified by its first
+ argument, and renders it centered as a separate paragraph.
+
+ The command takes two arguments. The first argument is the name of
+ the image file. The second argument is optional and is a simple
+ description of the image, equivalent to the HTML alt="" in an image
+ tag. The description is used for tooltips and for browsers that don't
+ support images, like the Lynx text browser.
+
+ The remaining text \e{after} the file name is the optional,
+ description argument. Be sure to follow the file name or the
+ description with a line break. Curly brackets are required if the
+ description argument spans multiple lines.
+
+ \code
+ / *!
+ Qt is a C++ toolkit for cross-platform GUI application development.
+
+ \image happyguy.jpg "Happy guy"
+
+ Qt provides single-source portability across Microsoft
+ Windows, Mac OS X, Linux, and all major commercial Unix
+ variants. It is also available for embedded devices.
+ * /
+ \endcode
+
+ QDoc renders this as:
+
+ \quotation
+ Qt is a C++ toolkit for cross-platform GUI application development.
+
+ \image happyguy.jpg image "Happy guy"
+
+ Qt provides single-source portability across Microsoft
+ Windows, Mac OS X, Linux, and all major commercial Unix
+ variants. It is also available for embedded devices.
+ \endquotation
+
+ See also \l {inlineimage-command} {\\inlineimage} and \l
+ {caption-command} {\\caption}.
+
+ \target inlineimage-command
+ \section1 \\inlineimage
+
+ The \\inlineimage command expands to the image specified by its
+ argument. The image is rendered inline with the rest of the text.
+
+ The command takes two arguments. The first argument is the name of
+ the image file. The second argument is optional and is a simple
+ description of the image, equivalent to the HTML alt="" in an image
+ tag. The description is used for tooltips, and for when a browser
+ doesn't support images, like the Lynx text browser.
+
+ The most common use of the \\inlineimage command is in lists and
+ tables. Here is an example of including inline images in a list:
+
+ \code
+ / *!
+ \list 1
+ \li \inlineimage happy.gif Oh so happy!
+ \li \inlineimage happy.gif Oh so happy!
+ \li \inlineimage happy.gif Oh so happy!
+ \endlist
+ * /
+ \endcode
+
+ QDoc renders this as:
+
+ \list 1
+ \li \inlineimage happy.gif Oh so happy!
+ \li \inlineimage happy.gif Oh so happy!
+ \li \inlineimage happy.gif Oh so happy!
+ \endlist
+
+ Here is an example of including inline images in a table:
+
+ \code
+ / *!
+ \table
+ \header
+ \li Qt
+ \li Qt Creator
+ \row
+ \li \inlineimage happy.gif Oh so happy!
+ \li \inlineimage happy.gif Oh so happy!
+ \row
+ \li \inlineimage happy.gif Oh so happy!
+ \li \inlineimage happy.gif Oh so happy!
+ \endtable
+ * /
+ \endcode
+
+ QDoc renders this as:
+
+ \raw HTML
+ <table align="center" cellpadding="2"
+ cellspacing="1" border="0">
+ <tr valign="top" bgcolor="#a2c511">
+ <th>Qt</th>
+ <th>Qt Creator</th>
+ </tr>
+ <tr valign="top" bgcolor="#f0f0f0">
+ <td><img src="images/happy.gif" alt="Oh so happy!" />
+ </td>
+ <td><img src="images/happy.gif" alt="Oh so happy!" />
+ </td>
+ </tr>
+ <tr valign="top" bgcolor="#f0f0f0">
+ <td><img src="images/happy.gif" alt="Oh so happy!"/>
+ </td>
+ <td><img src="images/happy.gif" alt="Oh so happy!" />
+ </td>
+ </tr>
+ </table>
+ \endraw
+
+ The command can also be used to insert an image inline with the
+ text.
+
+ \code
+ / *!
+ \inlineimage training.jpg Qt Training
+ The Qt Programming course is offered as a
+ five day Open Enrollment Course. The classes
+ are open to the public. Although the course is open
+ to anyone who wants to learn, attendees should
+ have significant experience in C++ development
+ to derive maximum benefit from the course.
+ * /
+ \endcode
+
+ QDoc renders this as:
+
+ \quotation
+ \inlineimage training.jpg Qt Training
+ The Qt Programming course is offered as a
+ five day Open Enrollment Course. The classes
+ are open to the public. Although the course is open
+ to anyone who wants to learn, attendees should
+ have significant experience in C++ development
+ to derive maximum benefit from the course.
+ \endquotation
+
+ See also \l {image-command} {\\image} and \l {caption-command} {\\caption}.
+
+ \target caption-command
+ \section1 \\caption
+
+ The \\caption command provides a caption for an image.
+
+ The command takes all the text up to the end of the paragraph to
+ be the caption. Experiment until you get the effect you want.
+
+ \code
+ / *!
+ \table 100%
+ \row
+ \li \image windowsvista-pushbutton.png
+ \caption The QPushButton widget provides a command button.
+ \li \image windowsvista-toolbutton.png
+ \caption The QToolButton class provides a quick-access button to commands
+ or options, usually used inside a QToolBar.
+ \endtable
+ * /
+ \endcode
+
+ QDoc renders this as:
+
+ \table 100%
+ \row
+ \li \image windowsvista-pushbutton.png
+ \caption The QPushButton widget provides a command button.
+ \li \image windowsvista-toolbutton.png
+ \caption The QToolButton class provides a quick-access button to commands
+ or options, usually used inside a QToolBar.
+ \endtable
+
+ See also \l {image-command} {\\image} and \l {inlineimage-command}
+ {\\inlineimage}
+*/
+
+
+/*!
+ \page 10-qdoc-commands-tablesandlists.html
+ \previouspage Including Images
+ \contentspage QDoc Manual
+ \nextpage Special Content
+
+ \title Tables and Lists
+
+ These commands enable creating lists and tables. A list is
+ rendered left aligned as a separate paragraph. A table is rendered
+ centered as a separate paragraph. The table width depends on the
+ width of its contents.
+
+ \target table-command
+ \section1 \\table
+
+ The \\table and \\endtable commands delimit the contents of a
+ table.
+
+ The command accepts a single argument specifying the table's width
+ as a percentage of the page width:
+
+ \code
+ / *!
+ \table 100 %
+
+ ...
+
+ \endtable
+ * /
+ \endcode
+
+ The code above ensures that the table will fill all available
+ space. If the table's width is smaller than 100 %, the table will
+ be centered in the generated documentation.
+
+ A table can contain headers, rows and columns. A row starts with a
+ \l {row-command} {\\row} command and consists of cells, each of which
+ starts with an \l {li-command} {\\li} command. There is also a \l
+ {header-command} {\\header} command which is a special kind of row
+ that has a special format.
+
+ \code
+ / *!
+ \table
+ \header
+ \li Qt Core Feature
+ \li Brief Description
+ \row
+ \li \l {Signal and Slots}
+ \li Signals and slots are used for communication
+ between objects.
+ \row
+ \li \l {Layout Management}
+ \li The Qt layout system provides a simple
+ and powerful way of specifying the layout
+ of child widgets.
+ \row
+ \li \l {Drag and Drop}
+ \li Drag and drop provides a simple visual
+ mechanism which users can use to transfer
+ information between and within applications.
+ \endtable
+ * /
+ \endcode
+
+ QDoc renders this as:
+
+ \raw HTML
+ <table align="center" cellpadding="2"
+ cellspacing="1" border="0">
+ <tr valign="top" bgcolor="#a2c511">
+ <th>Qt Core Feature</th>
+ <th>Brief Description</th>
+ </tr>
+
+ <tr valign="top" bgcolor="#d0d0d0">
+ <td>
+ <a href="http://qt-project.org/doc/qt-5.0/qtcore/signalsandslots.html">
+ Signals and Slots</a>
+ </td>
+ <td>Signals and slots are used for communication
+ between objects.</td>
+ </tr>
+
+ <tr valign="top" bgcolor="#c0c0c0">
+ <td>
+ <a href="http://qt-project.org/doc/qt-5.0/qtwidgets/layout.html">
+ Layout Management</a></td>
+ <td>The Qt layout system provides a simple
+ and powerful way of specifying the layout
+ of child widgets.</td>
+ </tr>
+
+ <tr valign="top" bgcolor="#d0d0d0">
+ <td>
+ <a href="http://qt-project.org/doc/qt-5.0/qtgui/dnd.html">
+ Drag and Drop</a></td>
+ <td>Drag and drop provides a simple visual
+ mechanism which users can use to transfer
+ information between and within applications.</td>
+ </tr>
+
+ </table>
+ \endraw
+
+ You can also make cells span several rows and columns. For
+ example:
+
+ \code
+ / *!
+ \table
+ \header
+ \li {3,1} This header cell spans three columns,
+ but only one row.
+ \row
+ \li {2, 1} This table cell spans two columns,
+ but only one row
+ \li {1, 2} This table cell spans only one column,
+ but two rows.
+ \row
+ \li A regular table cell
+ \li A regular table cell
+ \endtable
+ * /
+ \endcode
+
+ QDoc renders this as:
+
+ \raw HTML
+ <table align="center" cellpadding="2" cellspacing="1"
+ border="0">
+
+ <tr valign="top" bgcolor="#a2c511">
+ <th colspan="3" rowspan=" 1">
+ This header cell spans three columns, but only one row.
+ </th>
+ </tr>
+
+ <tr valign="top" bgcolor="#d0d0d0">
+ <td colspan="2" rowspan=" 1">
+ This table cell spans two columns, but only one row.
+ </td>
+ <td rowspan=" 2">
+ This table cell spans only one column, but two rows.
+ </td>
+ </tr>
+
+ <tr valign="top" bgcolor="#c0c0c0">
+ <td>A regular table cell</td>
+ <td>A regular table cell</td>
+ </tr>
+
+ </table>
+ \endraw
+
+ See also \l {header-command} {\\header}, \l {row-command} {\\row} and \l {li-command} {\\li}.
+
+ \target header-command
+ \section1 \\header
+
+ The \\header command indicates that the following table cells are
+ the current table's column headers.
+
+ The command can only be used within the \l{table-command}
+ {\\table...\\endtable} commands. A header can contain several
+ cells. A cell is created with the \l {li-command} {\\li} command.
+
+ A header cell's text is centered within the table cell and
+ rendered using a bold font.
+
+ \code
+ / *!
+ \table
+ \header
+ \li Qt Core Feature
+ \li Brief Description
+ \row
+ \li \l {Signal and Slots}
+ \li Signals and slots are used for communication
+ between objects.
+ \endtable
+ * /
+ \endcode
+
+ QDoc renders this as:
+
+ \raw HTML
+ <table align="center" cellpadding="2"
+ cellspacing="1" border="0">
+ <tr valign="top" bgcolor="#a2c511">
+ <th>Qt Core Feature</th>
+ <th>Brief Description</th>
+ </tr>
+
+ <tr valign="top" bgcolor="#d0d0d0">
+ <td>
+ <a href="http://qt-project.org/doc/qt-5.0/qtcore/signalsandslots.html">
+ Signals and Slots</a>
+ </td>
+ <td>Signals and slots are used for communication
+ between objects.</td>
+ </tr>
+ </table>
+ \endraw
+
+ See also \l {table-command} {\\table}, \l {row-command} {\\row} and \l {li-command} {\\li}.
+
+ \target row-command
+ \section1 \\row
+
+ The \\row command begins a new row in a table. The \l {li-command}
+ {\\li items} that belong in the new row will immediately follow the
+ \\row.
+
+ The command can only be used within the \l{table-command}
+ {\\table...\\endtable} commands. A row can contain several
+ cells. A cell is created with the \l {li-command} {\\li} command.
+
+ The background cell color of each row alternates between two
+ shades of grey, making it easier to distinguish the rows from each
+ other. The cells' contents is left aligned.
+
+ \code
+ / *!
+ \table
+ \header
+ \li Qt Core Feature
+ \li Brief Description
+ \row
+ \li \l {Signal and Slots}
+ \li Signals and slots are used for communication
+ between objects.
+ \row
+ \li \l {Layout Management}
+ \li The Qt layout system provides a simple
+ and powerful way of specifying the layout
+ of child widgets.
+ \row
+ \li \l {Drag and Drop}
+ \li Drag and drop provides a simple visual
+ mechanism which users can use to transfer
+ information between and within applications.
+ \endtable
+ * /
+ \endcode
+
+ QDoc renders this as:
+
+ \raw HTML
+ <table align="center" cellpadding="2"
+ cellspacing="1" border="0">
+ <tr valign="top" bgcolor="#a2c511">
+ <th>Qt Core Feature</th>
+ <th>Brief Description</th>
+ </tr>
+
+ <tr valign="top" bgcolor="#d0d0d0">
+ <td>
+ <a href="http://qt-project.org/doc/qt-5.0/qtcore/signalsandslots.html">
+ Signals and Slots</a>
+ </td>
+ <td>Signals and slots are used for communication
+ between objects.</td>
+ </tr>
+
+ <tr valign="top" bgcolor="#c0c0c0">
+ <td>
+ <a href="http://qt-project.org/doc/qt-5.0/qtwidgets/layout.html">
+ Layout Management</a></td>
+ <td>The Qt layout system provides a simple
+ and powerful way of specifying the layout
+ of child widgets.</td>
+ </tr>
+
+ <tr valign="top" bgcolor="#d0d0d0">
+ <td>
+ <a href="http://qt-project.org/doc/qt-5.0/qtgui/dnd.html">
+ Drag and Drop</a></td>
+ <td>Drag and drop provides a simple visual
+ mechanism which users can use to transfer
+ information between and within applications.</td>
+ </tr>
+
+ </table>
+ \endraw
+
+ See also \l {table-command} {\\table}, \l {header-command}
+ {\\header}, and \l {li-command} {\\li}.
+
+ \target value-command
+ \section1 \\value
+
+ The \\value command starts the documentation of a C++ enum item.
+
+ The command's first argument is the enum item. Then follows its
+ associated description. The description argument ends at the next
+ blank line or \\value. The arguments are rendered within a table.
+
+ The documentation will be located in the associated class, header
+ file or namespace documentation. See the \l {enum-command}
+ {\\enum} documentation for an example.
+
+ See also \l {enum-command} {\\enum} and \l {omitvalue-command} {\\omitvalue}.
+
+ \target omitvalue-command
+ \section1 \\omitvalue
+
+ The \\omitvalue command excludes a C++ enum item from the
+ documentation.
+
+ The command's only argument is the name of the enum item that will
+ be omitted. See the \l {enum-command} {\\enum} documentation for
+ an example.
+
+ See also \l {enum-command} {\\enum} and \l {value-command}
+ {\\value}.
+
+ \target list-command
+ \section1 \\list
+
+ The \\list and \\endlist commands delimit a list of items.
+
+ Create each list item with the \l {li-command} {\\li} command. A
+ list always contains one or more items. Lists can be nested. For
+ example:
+
+ \code
+ / *!
+ \list
+ \li Qt Reference Documentation: Getting Started
+ \list
+ \li How to Learn Qt
+ \li Installation
+ \list
+ \li Qt/X11
+ \li Qt/Windows
+ \li Qt/Mac
+ \li Qt/Embedded
+ \endlist
+ \li Tutorial and Examples
+ \endlist
+ \endlist
+ * /
+ \endcode
+
+ QDoc renders this as:
+
+ \list
+ \li Qt Reference Documentation: Getting Started
+ \list
+ \li How to Learn Qt
+ \li Installation
+ \list
+ \li Qt/X11
+ \li Qt/Windows
+ \li Qt/Mac
+ \li Qt/Embedded
+ \endlist
+ \li Tutorial and Examples
+ \endlist
+ \endlist
+
+ The \\list command takes an optional argument providing
+ alternative appearances for the list items.
+
+ \code
+ / *!
+ \list
+ \li How to Learn Qt
+ \li Installation
+ \li Tutorial and Examples
+ \endlist
+ * /
+ \endcode
+
+ QDoc renders the list items with bullets (the default):
+
+ \list
+ \li How to Learn Qt
+ \li Installation
+ \li Tutorial and Examples
+ \endlist
+
+ \warning There appears to be a bug in qdoc here. If you include
+ any of the argument types, you get a numeric list. We're looking
+ into it.
+
+ If you provide 'A' as an argument to the \\list command, the
+ bullets are replaced with characters in alphabetical order:
+
+ \list A
+ \li How to Learn Qt
+ \li Installation
+ \li Tutorial and Examples
+ \endlist
+
+ If you replace 'A' with '1', the list items are numbered in
+ ascending order:
+
+ \list 1
+ \li How to Learn Qt
+ \li Installation
+ \li Tutorial and Examples
+
+ \endlist
+
+ If you provide 'i' as the argument, the bullets are replaced with
+ roman numerals:
+
+ \list i
+ \li How to Learn Qt
+ \li Installation
+ \li Tutorial and Examples
+ \endlist
+
+ Finally, you can make the list items appear with roman numbers
+ following in ascending order if you provide 'I' as the optional
+ argument:
+
+ \list I
+ \li How to Learn Qt
+ \li Installation
+ \li Tutorial and Examples
+ \endlist
+
+ You can also make the listing start at any character or number by
+ simply provide the number or character you want to start at. For
+ example:
+
+ \code
+ / *!
+ \list G
+ \li How to Learn Qt
+ \li Installation
+ \li Tutorial and Examples
+ \endlist
+ * /
+ \endcode
+
+ \note This doesn't work in DITA XML, so don't use it because it
+ produces a DITA XML file that doesn't validate. There probably is
+ a way to do this in DITA, so if we figure it out, we will put it
+ in. But this capability is not used anywhere other than right
+ here, so it probably isn't important. For now, if you use this
+ option, qdoc will ignore it and produce a list without it.
+
+ QDoc renders this as:
+
+ \list G
+ \li How to Learn Qt
+ \li Installation
+ \li Tutorial and Examples
+ \endlist
+
+ See also \l {li-command} {\\li}.
+
+ \target li-command
+ \section1 \\li (table cell, list item)
+
+ The \\li command marks a table cell or a list item. This command
+ is only used in \l{table-command} {tables} and \l{list-command}
+ {lists}.
+
+ It considers everything as its argument until the next \\li command, until the
+ next \l {table-command} {\\endtable}, or \l {list-command} {\\endlist}
+ command. See \l {table-command} {\\table} and \l {list-command} {\\list}
+ for examples.
+
+ If the command is used within a table, you can also specify
+ how many rows or columns the item should span.
+
+ \code
+ / *!
+ \table
+ \header
+ \li {3,1} This header cell spans three columns
+ but only one row.
+ \row
+ \li {2, 1} This table item spans two columns
+ but only one row
+ \li {1, 2} This table item spans only one column,
+ but two rows.
+ \row
+ \li A regular table item
+ \li A regular table item
+ \endtable
+ * /
+ \endcode
+
+ QDoc renders this as:
+
+ \raw HTML
+ <table align="center" cellpadding="2" cellspacing="1"
+ border="0">
+
+ <tr valign="top" bgcolor="#a2c511">
+ <th colspan="3" rowspan=" 1">
+ This header cell spans three columns, but only one row.
+ </th>
+ </tr>
+
+ <tr valign="top" bgcolor="#d0d0d0">
+ <td colspan="2" rowspan=" 1">
+ This table item spans two columns, but only one row.
+ </td>
+ <td rowspan=" 2">
+ This table item spans only one column, but two rows.
+ </td>
+ </tr>
+
+ <tr valign="top" bgcolor="#c0c0c0">
+ <td>A regular table item</td>
+ <td>A regular table item</td>
+ </tr>
+
+ </table>
+ \endraw
+
+ If not specified, the item will span one column and one row.
+
+ See also \l {table-command} {\\table}, \l {header-command}
+ {\\header}, and \l {list-command} {\\list}.
+
+*/
+
+
+/*!
+ \page 11-qdoc-commands-specialcontent.html
+ \previouspage Tables and Lists
+ \contentspage QDoc Manual
+ \nextpage Miscellaneous
+
+ \title Special Content
+
+ The document contents commands identify parts of the documentation,
+ parts with a special rendering, conceptual meaning or
+ function.
+
+ \target abstract-command
+ \section1 \\abstract
+
+ The \\abstract and \\endabstract commands delimit a
+ document's abstract section.
+
+ The abstract section is rendered as an indented italicized
+ paragraph.
+
+ \warning The \b{\\abstract} and \b{\\endabstract} commands
+ have not been implemented. The abstract section is rendered as a
+ regular HTML paragraph.
+
+ \target quotation-command
+ \section1 \\quotation
+
+ The \\quotation and \\endquotation commands delimit a long quotation.
+
+ The text in the delimited block is surrounded by
+ \b{<blockquote>} and \b{</blockquote>} in the html output,
+ e.g.:
+
+ \code
+ / *!
+ Although the prospect of a significantly broader market is
+ good news for Firstlogic, the notion also posed some
+ challenges. Dave Dobson, director of technology for the La
+ Crosse, Wisconsin-based company, said:
+
+ \quotation
+ As our solutions were being adopted into new
+ environments, we saw an escalating need for easier
+ integration with a wider range of enterprise
+ applications.
+ \endquotation
+ * /
+ \endcode
+
+ The text in the \b{\\quotation} block will appear in the generated HTML as:
+
+ \code
+ <blockquote>
+ <p>As our solutions were being adopted into new environments,
+ we saw an escalating need for easier integration with a wider
+ range of enterprise applications.</p>
+ </blockquote>
+ \endcode
+
+ The built-in style sheet for most browsers will render the
+ contents of the <blockquote> tag with left and right
+ indentations. The example above would be rendered as:
+
+ \quotation
+ As our solutions were being adopted into new
+ environments, we saw an escalating need for easier
+ integration with a wider range of enterprise
+ applications.
+ \endquotation
+
+ But you can redefine the \b{<blockquote>} tag in your style.css file.
+
+ \target footnote-command
+ \section1 \\footnote
+
+ The \\footnote and \\endfootnote commands delimit a footnote.
+
+ The footnote is rendered at the bottom of the page.
+
+ \warning The \b{\\footnote} and \b{\\endfootnote} commands
+ have not been implemented. The footnote is rendered as a regular
+ HTML paragraph.
+
+ \target note-command
+ \section1 \\note
+
+ The \\note command defines a new paragraph preceded by "Note:"
+ in bold.
+
+ \target tableofcontents-command
+ \section1 \\tableofcontents
+
+ The \\tableofcontents command has been disabled because QDoc
+ now generates a table of contents automatically.
+
+ The automatically generated table of contents appears in the upper
+ righthand corner of the page.
+
+ \target brief-command
+ \section1 \\brief
+
+ The \\brief command introduces a one-sentence description of a
+ class, namespace, header file, property, or variable.
+
+ The brief text is used to introduce the documentation of the
+ associated object, and in lists generated using the \l
+ {generatelist-command} {\\generatelist} command and the \l
+ {annotatedlist-command} {\\annotatedlist} command.
+
+ The \\brief command can be used in two significant different ways:
+ \l {brief class} {One for classes, namespaces and header files},
+ and \l {brief-property} {one for properties and variables}.
+
+ \target brief-property
+
+ When the \\brief command is used to describe a property or a
+ variable, the brief text must be a sentence fragment starting with
+ "whether" (for a boolean property or variable) or starting with
+ "the" (for any other property or variable).
+
+ For example the boolean QWidget::isWindow property:
+
+ \code
+ / *!
+ \property QWidget::isActiveWindow
+ \brief Whether this widget's window is the active window
+
+ The active window is the window that contains the widget that
+ has keyboard focus.
+
+ When popup windows are visible, this property is true
+ for both the active window \e and the popup.
+
+ \sa activateWindow(), QApplication::activeWindow()
+ * /
+ \endcode
+
+ and the QWidget::geometry property
+
+ \code
+ / *!
+ \property QWidget::geometry
+ \brief The geometry of the widget relative to its parent and
+ excluding the window frame
+
+ When changing the geometry, the widget, if visible,
+ receives a move event (moveEvent()) and/or a resize
+ event (resizeEvent()) immediately.
+
+ ...
+
+ \sa frameGeometry(), rect(), ...
+ * /
+ \endcode
+
+ QDoc renders this as:
+
+ \quotation
+ \raw HTML
+ <h3>geometry :
+ <a href="http://qt-project.org/doc/qt-5.0/qtcore/qrect.html">QRect</a>
+ </h3>
+ \endraw
+
+ This property holds the geometry of the widget relative
+ to its parent and excluding the window frame.
+
+ ...
+
+ Access functions:
+ \list
+ \li \b {const QRect & geometry () const}
+ \li \b {void setGeometry ( int x, int y, int w, int h )}
+ \li \b {void setGeometry ( const QRect & )}
+ \endlist
+
+ See also \l
+ {QWidget::frameGeometry()} {frameGeometry()}, \l
+ {QWidget::rect()} {rect()}, ...
+ \endquotation
+
+ \target brief class
+
+ When the \\brief command is used to describe a class, the brief
+ text should be a complete sentence and must start like this:
+
+ \code
+ The <classname> class is|provides|contains|specifies...
+ \endcode
+
+ \warning The brief statement is used as the first paragraph of the
+ detailed description. Do not repeat the sentence.
+
+ \code
+ / *!
+ \class PreviewWindow
+ \brief The PreviewWindow class is a custom widget
+ displaying the names of its currently set
+ window flags in a read-only text editor.
+
+ The PreviewWindow class inherits QWidget. The widget
+ displays the names of its window flags set with the
+ setWindowFlags() function. It is also provided with a
+ QPushButton that closes the window.
+
+ ...
+
+ \sa QWidget
+ * /
+ \endcode
+
+ QDoc renders this as:
+
+ \quotation
+ \raw HTML
+ <h1>PreviewWindow Class Reference</h1>
+ \endraw
+
+ The PreviewWindow class is a custom widget displaying
+ the names of its currently set window flags in a
+ read-only text editor. \l {preview window} {More...}
+
+ \raw HTML
+ <h3>Properties</h3>
+ \endraw
+
+ \list
+ \li 52 properties inherited from QWidget
+ \li 1 property inherited from QObject
+ \endlist
+
+ \raw HTML
+ <h3>Public Functions</h3>
+ \endraw
+
+ \list
+ \li \l {constructor} {PreviewWindow}(QWidget *parent = 0)
+ \li void \l {function} {setWindowFlags}(Qt::WindowFlags flags)
+ \endlist
+
+ \list
+ \li 183 public functions inherited from QWidget
+ \li 28 public functions inherited from QObject
+ \endlist
+
+ \raw HTML
+ <h3>Public Slots</h3>
+ \endraw
+
+ \list
+ \li 17 public slots inherited from QWidget
+ \li 1 public slot inherited from QObject
+ \endlist
+
+ \raw HTML
+ <h3>Additional Inherited Members</h3>
+ \endraw
+
+ \list
+ \li 1 signal inherited from QWidget
+ \li 1 signal inherited from QObject
+ \li 4 static public members inherited from QWidget
+ \li 4 static public members inherited from QObject
+ \li 39 protected functions inherited from QWidget
+ \li 7 protected functions inherited from QObject
+ \endlist
+
+ \target preview window
+
+ \raw HTML
+ <hr />
+ <h2>Detailed Description</h2>
+ \endraw
+
+ The PreviewWindow class is a custom widget displaying
+ the names of its currently set window flags in a
+ read-only text editor.
+
+ The PreviewWindow class inherits QWidget. The widget
+ displays the names of its window flags set with the \l
+ {function} {setWindowFlags()} function. It is also
+ provided with a QPushButton that closes the window.
+
+ ...
+
+ See also QWidget.
+
+ \raw HTML
+ <hr />
+ <h2>Member Function Documentation</h2>
+ \endraw
+
+ \target constructor
+ \raw HTML
+ <h3>PreviewWindow(QWidget *parent = 0)</h3>
+ \endraw
+
+ Constructs a preview window widget with \e parent.
+
+ \target function
+ \raw HTML
+ <h3>setWindowFlags(Qt::WindowFlags flags)</h3>
+ \endraw
+
+ Sets the widgets flags using the
+ QWidget::setWindowFlags() function.
+
+ Then runs through the available window flags,
+ creating a text that contains the names of the flags
+ that matches the flags parameter, displaying
+ the text in the widgets text editor.
+ \endquotation
+
+ Using \\brief in a \l{namespace-command}{\\namespace}:
+
+ \code
+ / *!
+ \namespace Qt
+
+ \brief The Qt namespace contains miscellaneous identifiers
+ used throughout the Qt library.
+ * /
+ \endcode
+
+ Using \\brief in a \l{headerfile-command}{\\headerfile}:
+
+ \code
+ / *!
+ \headerfile <QtGlobal>
+ \title Global Qt Declarations
+
+ \brief The <QtGlobal> header file provides basic
+ declarations and is included by all other Qt headers.
+
+ \sa <QtAlgorithms>
+ * /
+ \endcode
+
+ See also \l{property-command} {\\property}, \l{class-command}
+ {\\class}, \l{namespace-command} {\\namespace} and
+ \l{headerfile-command} {\\headerfile}.
+
+ \target legalese-command
+ \section1 \\legalese
+
+ The \\legalese and \\endlegalese commands delimit a license agreement.
+
+ In the generated HTML, the delimited text is surrounded by a \b
+ {<div class="LegaleseLeft">} and \b {</div>} tags.
+
+ An example of a license agreement enclosed in \\legalese
+ and \\endlegalese:
+
+ \code
+ / *!
+ \legalese
+ Copyright 1996 Daniel Dardailler.
+
+ Permission to use, copy, modify, distribute, and sell this
+ software for any purpose is hereby granted without fee,
+ provided that the above copyright notice appear in all
+ copies and that both that copyright notice and this
+ permission notice appear in supporting documentation, and
+ that the name of Daniel Dardailler not be used in
+ advertising or publicity pertaining to distribution of the
+ software without specific, written prior permission. Daniel
+ Dardailler makes no representations about the suitability of
+ this software for any purpose. It is provided "as is"
+ without express or implied warranty.
+
+ Modifications Copyright 1999 Matt Koss, under the same
+ license as above.
+ \endlegalese
+ * /
+ \endcode
+
+ It will appear in the generated HTML as:
+
+ \code
+ <div class="LegaleseLeft">
+ <p>Copyright 1996 Daniel Dardailler.</p>
+ <p>Permission to use, copy, modify, distribute, and sell
+ this software for any purpose is hereby granted without fee,
+ provided that the above copyright notice appear in all
+ copies and that both that copyright notice and this
+ permission notice appear in supporting documentation, and
+ that the name of Daniel Dardailler not be used in
+ advertising or publicity pertaining to distribution of the
+ software without specific, written prior permission. Daniel
+ Dardailler makes no representations about the suitability of
+ this software for any purpose. It is provided "as is"
+ without express or implied warranty.</p>
+
+ <p>Modifications Copyright 1999 Matt Koss, under the same
+ license as above.</p>
+ </div>
+ \endcode
+
+ If the \\endlegalese command is omitted, QDoc will process the
+ \\legalese command but considers the rest of the documentation
+ page as the license agreement.
+
+ Ideally, the license text is located with the licensed code.
+
+ Elsewhere, the documentation identified as \e{\\legalese} command
+ can be accumulated using \l {generatelist-command} {\\generatelist}
+ with \c {legalese-command} as the argument. This is useful for
+ generating an overview of the license agreements associated with
+ the source code.
+
+ \target warning-command
+ \section1 \\warning
+
+ The \\warning command prepends "Warning:" to the command's
+ argument, in bold font.
+
+ \code
+ / *!
+ Qt::HANDLE is a platform-specific handle type
+ for system objects. This is equivalent to
+ \c{void *} on Windows and Mac OS X, and to
+ \c{unsigned long} on X11.
+
+ \warning Using this type is not portable.
+ * /
+ \endcode
+
+ QDoc renders this as:
+
+ \quotation
+ Qt::HANDLE is a platform-specific handle type
+ for system objects. This is equivalent to
+ \c{void *} on Windows and Mac OS X, and to
+ \c{unsigned long} on X11.
+
+ \warning Using this type is not portable.
+ \endquotation
+
+*/
+
+
+/*!
+ \page 12-0-qdoc-commands-miscellaneous.html
+ \previouspage Special Content
+ \contentspage QDoc Manual
+ \nextpage Creating DITA Maps
+
+ \title Miscellaneous
+
+ These commands provide miscellaneous functions connected to the
+ visual appearance of the documentation, and to the process of
+ generating the documentation.
+
+ \target annotatedlist-command
+ \section1 \\annotatedlist
+
+ The \\annotatedlist command expands to a list of the members of a
+ group, each member listed with its \e {brief} text. Below is an
+ example from the Qt Reference Documentation:
+
+ \code
+ / *!
+ ...
+ \section1 Drag and Drop Classes
+
+ These classes deal with drag and drop and the necessary mime type
+ encoding and decoding.
+
+ \annotatedlist draganddrop
+
+ * /
+ \endcode
+
+ This generates a list of all the C++ classes and/or QML types in
+ the \e{draganddrop} group. A C++ class or QML type in the
+ \e{draganddrop} group will have \e{\\ingroup draganddrop} in its
+ \e{\\class} or \e{\\qmltype} comment.
+
+
+ \target generatelist-command
+ \section1 \\generatelist
+
+ The \\generatelist command expands to a list of various
+ documentation or links to documentation. Below is an example from
+ the Qt Reference Documentation:
+
+ \code
+ / *!
+ \page classes.html
+ \title All Classes
+
+ For a shorter list that only includes the most
+ frequently used classes, see \l{Qt's Main Classes}.
+
+ \generatelist classes
+ * /
+ \endcode
+
+ This generates the \e {All Classes} page. The command accepts the
+ following arguments:
+
+ \target table example
+ \section2 \c annotatedclasses
+
+ The \c annotatedclasses argument provides a table containing the
+ names of all the classes, and a description of each class. Each
+ class name is a link to the class's reference documentation. For
+ example:
+
+ \table
+ \row
+ \li QDial
+ \li Rounded range control (like a speedometer or potentiometer)
+ \row
+ \li QDialog
+ \li The base class of dialog windows
+ \row
+ \li QDir
+ \li Access to directory structures and their contents
+ \endtable
+
+ A C++ class is documented with the \l {class-command} {\\class}
+ command. The annotation for the class is taken from the argument
+ of the class comment's \l {brief-command} {\\brief} command.
+
+ \target list example
+ \section2 \c classes
+
+ The \c classes argument provides a complete alphabetical list of
+ the classes. Each class name is a link to the class's reference
+ documentation. This command is used to generate the
+ \e {All Classes} page this way:
+
+ \code
+ / *!
+ \page classes.html
+ \title All Classes
+ \ingroup classlists
+
+ \brief Alphabetical list of classes.
+
+ This is a list of all Qt classes. For a list of the classes
+ provided for compatibility with Qt3, see \l{Qt3 Support
+ Classes}. For classes that have been deprecated, see the
+ \l{Obsolete Classes} list.
+
+ \generatelist classes
+ * /
+ \endcode
+
+ A C++ class is documented with the \l {class-command} {\\class}
+ command.
+
+ \section2 \c classesbymodule
+
+ When this argument is used, a second argument is required, which
+ specifies the module whose classes are to be listed. QDoc
+ generates a table containing those classes. Each class is listed
+ with the text of its \l{brief-command} {\\brief} command.
+
+ For example, this command can be used on a module page as follows:
+
+ \code
+ / *!
+ \page phonon-module.html
+ \module Phonon
+ \title Phonon Module
+ \ingroup modules
+
+ \brief Contains namespaces and classes for multimedia functionality.
+
+ \generatelist{classesbymodule Phonon}
+
+ ...
+
+ * /
+ \endcode
+
+ Each class that is a member of the specified module must be marked
+ with the \l {inmodule-command} {\\inmodule} command in its \\class
+ comment.
+
+ \section2 \c compatclasses
+
+ The \c compatclasses argument generates a list in alphabetical
+ order of the support classes. It is normally used only to
+ generate the Qt3 Support Classes page this way:
+
+ \code
+ / *!
+ \page compatclasses.html
+ \title Qt3 Support Classes
+ \ingroup classlists
+
+ \brief Enable porting of code from Qt 3 to Qt 4.
+
+ These are the classes that Qt provides for compatibility with Qt
+ 3. Most of these are provided by the Qt3Support module.
+
+ \generatelist compatclasses
+ * /
+ \endcode
+
+ A support class is identified in the \\class comment with the \l
+ {compat-command} {\\compat} command.
+
+ \section2 \c functionindex
+
+ The \c functionindex argument provides a complete alphabetical
+ list of all the documented member functions. It is normally used
+ only to generate the \e {Qt function index} page
+ this way:
+
+ \code
+ / *!
+ \page functions.html
+ \title All Functions
+ \ingroup funclists
+
+ \brief All documented Qt functions listed alphabetically with a
+ link to where each one is declared.
+
+ This is the list of all documented member functions and global
+ functions in the Qt API. Each function has a link to the
+ class or header file where it is declared and documented.
+
+ \generatelist functionindex
+ * /
+ \endcode
+
+ \section2 \c legalese
+
+ The \c legalese argument tells QDoc to generate a complete list of
+ licenses in the documentation. Each license is identified using
+ the \l {legalese-command} {\\legalese} command. This command is
+ used to generate the \e {Qt license information}
+ page this way:
+
+ \code
+ / *!
+ \page licenses.html
+ \title Other Licenses Used in Qt
+ \ingroup licensing
+ \brief Information about other licenses used for Qt components and third-party code.
+
+ Qt contains some code that is not provided under the
+ \l{GNU General Public License (GPL)},
+ \l{GNU Lesser General Public License (LGPL)} or the
+ \l{Qt Commercial Edition}{Qt Commercial License Agreement}, but rather under
+ specific licenses from the original authors. Some pieces of code were developed
+ by Digia and others originated from third parties.
+ This page lists the licenses used, names the authors, and links
+ to the places where it is used.
+
+ Digia gratefully acknowledges these and other contributions
+ to Qt. We recommend that programs that use Qt also acknowledge
+ these contributions, and quote these license statements in an
+ appendix to the documentation.
+
+ See also: \l{Licenses for Fonts Used in Qt for Embedded Linux}
+
+ \generatelist legalese
+ * /
+ \endcode
+
+ \section2 \c mainclasses
+
+ The \c mainclasses argument tells QDoc to generate an alphabetical
+ list of the main classes. A class is marked as a main class by
+ including a \l {mainclass-command} {\\mainclass} command in the
+ \\class comment.
+
+ \note The Qt documentation no longer includes a main classes page,
+ but you can generate one for your main classes if you want it.
+
+ \section2 \c overviews
+
+ The \c overviews argument is used to tell QDoc to generate a list
+ by concatenating the contents of all the \l {group-command}
+ {\\group} pages. Qt uses it to generate the \e {overviews} page
+ this way:
+
+ \code
+ / *!
+ \page overviews.html
+
+ \title All Overviews and HOWTOs
+
+ \generatelist overviews
+ * /
+ \endcode
+
+ \section2 \c related
+
+ The \c related argument is used in combination with the \l
+ {group-command} {\\group} and \l {ingroup-command} {\\ingroup}
+ commands to list all the overviews related to a specified
+ group. For example, the page for the \e {Programming with Qt}
+ page is generated this way:
+
+ \code
+ / *!
+ \group qt-basic-concepts
+ \title Programming with Qt
+
+ \brief The basic architecture of the Qt cross-platform application and UI framework.
+
+ Qt is a cross-platform application and UI framework for
+ writing web-enabled applications for desktop, mobile, and
+ embedded operating systems. This page contains links to
+ articles and overviews explaining key components and
+ techniuqes used in Qt development.
+
+ \generatelist {related}
+ * /
+ \endcode
+
+ Each page listed on this group page contains the command:
+
+ \code
+ \ingroup qt-basic-concepts
+ \endcode
+
+ \section2 \c service
+
+ The \c service argument tells QDoc to generate an alphabetical
+ list of the services. Each service name is a link to the service's
+ reference documentation.
+
+ A service is identified with the \l {service-command} {\\service}
+ command.
+
+ \note This command and the \l {service-command} {\\service}
+ command are not used in the Qt documentation.
+
+ \target if-command
+ \section1 \\if
+
+ The \\if command and the corresponding \\endif command
+ enclose parts of a QDoc comment that only will be included if
+ the condition specified by the command's argument is true.
+
+ The command reads the rest of the line and parses it as an C++ #if
+ statement.
+
+ \code
+ / *!
+ \if defined(opensourceedition)
+
+ \b{Note:} This edition is for the development of
+ \l{Qt Open Source Edition} {Free and Open Source}
+ software only; see \l{Qt Commercial Editions}.
+
+ \endif
+ * /
+ \endcode
+
+ This QDoc comment will only be rendered if the \c
+ opensourceedition preprocessor symbol is defined, and specified in
+ the \l {defines-variable} {defines} variable in the configuration
+ file to make QDoc process the code within #ifdef and #endif:
+
+ \code
+ defines = opensourceedition
+ \endcode
+
+ You can also define the preprocessor symbol manually on the
+ command line. For more information see the documentation of the \l
+ {defines-variable} {defines} variable.
+
+ See also \l{endif-command} {\\endif}, \l{else-command} {\\else},
+ \l {defines-variable} {defines} and \l {falsehoods-variable}
+ {falsehoods}.
+
+ \target endif-command
+ \section1 \\endif
+
+ The \\endif command and the corresponding \\if command
+ enclose parts of a QDoc comment that will be included if
+ the condition specified by the \l {if-command} {\\if} command's
+ argument is true.
+
+ For more information, see the documentation of the \l {if-command}
+ {\\if} command.
+
+ See also \l{if-command} {\\if}, \l{else-command} {\\else}, \l
+ {defines-variable} {defines} and \l {falsehoods-variable}
+ {falsehoods}.
+
+ \target else-command
+ \section1 \\else
+
+ The \\else command specifies an alternative if the
+ condition in the \l {if-command} {\\if} command is false.
+
+ The \\else command can only be used within \l {if-command}
+ {\\if...\\endif} commands, but is useful when there is only two
+ alternatives.
+
+ \code
+ / *!
+ The Qt 3 support library is provided to keep old
+ source code working.
+
+ In addition to the \c Qt3Support classes, Qt 4 provides
+ compatibility functions when it's possible for an old
+ API to cohabit with the new one.
+
+ \if !defined(QT3_SUPPORT)
+ \if defined(QT3_SUPPORTWARNINGS)
+ The compiler emits a warning when a
+ compatibility function is called. (This works
+ only with GCC 3.2+ and MSVC 7.)
+ \else
+ To use the Qt 3 support library, you need to
+ have the line QT += qt3support in your .pro
+ file (qmake automatically define the
+ QT3_SUPPORT symbol, turning on compatibility
+ function support).
+
+ You can also define the symbol manually (for example,
+ if you don't want to link against the \c
+ Qt3Support library), or you can define \c
+ QT3_SUPPORT_WARNINGS instead, telling the
+ compiler to emit a warning when a compatibility
+ function is called. (This works only with GCC
+ 3.2+ and MSVC 7.)
+ \endif
+ \endif
+ * /
+ \endcode
+
+ If the \c QT3_SUPPORT is defined, the comment will be rendered
+ like this:
+
+ \quotation
+ The Qt 3 support library is provided to keep old source
+ code working.
+
+ In addition to the Qt3Support classes, Qt 4 provides
+ compatibility functions when it's possible for an old
+ API to cohabit with the new one.
+ \endquotation
+
+ If \c QT3_SUPPORT is not defined but \c QT3_SUPPORT_WARNINGS is
+ defined, the comment will be rendered like this:
+
+ \quotation
+ The Qt 3 support library is provided to keep old source
+ code working.
+
+ In addition to the Qt3Support classes, Qt 4 provides
+ compatibility functions when it's possible for an old
+ API to cohabit with the new one.
+
+ The compiler emits a warning when a compatibility
+ function is called. (This works only with GCC 3.2+ and
+ MSVC 7.)
+ \endquotation
+
+ If none of the symbols are defined, the comment will be
+ rendered as
+
+ \quotation
+ The Qt 3 support library is provided to keep old
+ source code working.
+
+ In addition to the \c Qt3Support classes, Qt 4 provides
+ compatibility functions when it's possible for an old
+ API to cohabit with the new one.
+
+ To use the Qt 3 support library, you need to have the
+ line QT += qt3support in your .pro file (qmake
+ automatically define the QT3_SUPPORT symbol, turning on
+ compatibility function support).
+
+ You can also define the symbol manually (e.g., if you
+ don't want to link against the \c Qt3Support library),
+ or you can define \c QT3_SUPPORT_WARNINGS instead,
+ telling the compiler to emit a warning when a
+ compatibility function is called. (This works only with
+ GCC 3.2+ and MSVC 7.)
+ \endquotation
+
+ See also \l{if-command} {\\if}, \l{endif-command} {\\endif}, \l
+ {defines-variable} {defines} and \l {falsehoods-variable}
+ {falsehoods}.
+
+ \target include-command
+ \section1 \\include
+
+ The \\include command sends all or part of the file specified by
+ its first argument to the QDoc input stream to be processed as a
+ QDoc comment snippet. This command is often assigned the alias,
+ \e {input}, in the QDoc configuration file, for example \e {alias.include
+ = input}.
+
+ The command is useful when some snippet of commands and text is to
+ be used in multiple places in the documentation. In that case,
+ move the snippet into a separate file and use the \\include
+ command wherever you want to insert the snippet into the
+ documentation. To prevent QDoc from reading the file as a
+ stand-alone page of documentation, we recommend that you use the
+ \c .qdocinc extension for these \e {include} files.
+
+ The command can have either one or two arguments. The first
+ argument is always a file name. The contents of the file must be
+ QDoc input, in other words, a sequence of QDoc commands and text, but
+ without the enclosing QDoc comment \c{/}\c{*!} ... \c{*}\c{/} delimiters.
+ If you want to include the entire named file, don't use the second
+ argument. If you want to include only part of the file, see the
+ \l{2-argument-form}{two argument form} below. Here is an example
+ of the one argument form:
+
+ \code
+ / *!
+ \page corefeatures.html
+ \title Core Features
+
+ \include examples/signalandslots.qdocinc
+ \include examples/objectmodel.qdocinc
+ \include examples/layoutmanagement.qdocinc
+ * /
+ \endcode
+
+ QDoc renders this page \l{corefeatures.html} {as shown here}.
+
+ \target 2-argument-form}
+ \section2 \\include filename snippet-identifier
+
+ It is a waste of time to make a separate \c .qdocinc file for every
+ QDoc include snippet you want to use in multiple places in the
+ documentation, especially given that you probably have to put the
+ copyright/license notice in every one of these files. So if you
+ have a large number of snippets to be included, you can put them all in a
+ single file if you want, and surround each one with:
+ \code
+ //! [snippet-id1]
+
+ QDoc commands and text...
+
+ //! [snippet-id1]
+
+ //! [snippet-id2]
+
+ More QDoc commands and text...
+
+ //! [snippet-id2]
+ \endcode
+
+ Then you can use the two-argument form of the command:
+
+ \code
+ \input examples/signalandslots.qdocinc snippet-id2
+ \input examples/objectmodel.qdocinc another-snippet-id
+ \endcode
+
+ It works as expected. The sequence of QDoc commands and text found
+ between the two tags with the same name as the second argument is
+ sent to the QDoc input stream. You can even nest these snippets,
+ although it's not clear why you would want to do that.
+
+ \target meta-command
+ \section1 \\meta
+
+ The \\meta command is mainly used for including metadata in DITA
+ XML files. It is also used when generating HTML output for specifying
+ the \e maintainer(s) of a C++ class.
+
+ The command has two arguments: the first argument is the name of the
+ metadata attribute, and the second argument is the
+ value for the attribute. Each argument should be enclosed in curly
+ brackets, as shown in this example:
+
+ \code
+ / *!
+ \class QWidget
+ \brief The QWidget class is the base class of all user interface objects.
+
+ \ingroup basicwidgets
+
+ \meta {technology} {User Interface}
+ \meta {platform} {OS X 10.6}
+ \meta {platform} {Symbian}
+ \meta {platform} {MeeGo}
+ \meta {audience} {user}
+ \meta {audience} {programmer}
+ \meta {audience} {designer}
+ * /
+ \endcode
+
+ When running QDoc to generate HTML, the example above will have no
+ effect on the generated output, but if you run QDoc to generate
+ DITA XML, the example will generate the following:
+
+ \code
+ <?xml version="1.0" encoding="UTF-8"?>
+ <!DOCTYPE cxxClass PUBLIC "-//NOKIA//DTD DITA C++ API Class Reference Type v0.6.0//EN" "dtd/cxxClass.dtd">
+ <!--qwidget.cpp-->
+ <cxxClass id="id-9a14268e-6b09-4eee-b940-21a00a0961df">
+ <apiName>QWidget</apiName>
+ <shortdesc>the QWidget class is the base class of all user interface objects.</shortdesc>
+ <prolog>
+ <author>Qt Development Frameworks</author>
+ <publisher>Qt Project</publisher>
+ <copyright>
+ <copyryear year="2013"/>
+ <copyrholder>Qt Project</copyrholder>
+ </copyright>
+ <permissions view="all"/>
+ <metadata>
+ <audience type="designer"/>
+ <audience type="programmer"/>
+ <audience type="user"/>
+ <category>Class reference</category>
+ <prodinfo>
+ <prodname>Qt Reference Documentation</prodname>
+ <vrmlist>
+ <vrm version="4" release="7" modification="3"/>
+ </vrmlist>
+ <component>QtGui</component>
+ </prodinfo>
+ <othermeta name="platform" content="MeeGo"/>
+ <othermeta name="platform" content="Symbian"/>
+ <othermeta name="platform" content="OS X 10.6"/>
+ <othermeta name="technology" content="User Interface"/>
+ </metadata>
+ </prolog>
+ \endcode
+
+ In the example output, several values have been set using default
+ values obtained from the QDoc configuration file. See \l
+ {Generating DITA XML Output} for details.
+
+ \target omit-command
+ \section1 \\omit
+
+ The \\omit command and the corresponding \\endomit command
+ delimit parts of the documentation that you want QDoc to skip. For
+ example:
+
+ \code
+ / *!
+ \table
+ \row
+ \li Basic Widgets
+ \li Basic GUI widgets such as buttons, comboboxes
+ and scrollbars.
+
+ \omit
+ \row
+ \li Component Model
+ \li Interfaces and helper classes for the Qt
+ Component Model.
+ \endomit
+
+ \row
+ \li Database Classes
+ \li Database related classes, e.g. for SQL databases.
+ \endtable
+ * /
+ \endcode
+
+ QDoc renders this as:
+
+ \raw HTML
+ <table align="center" cellpadding="2"
+ cellspacing="1" border="0">
+
+ <tr valign="top" bgcolor="#d0d0d0">
+ <td>Basic Widgets</td>
+ <td>Basic GUI widgets such as buttons, comboboxes
+ and scrollbars.</td>
+ </tr>
+
+ <tr valign="top" bgcolor="#c0c0c0">
+ <td>Database Classes</td>
+ <td>Database related classes, e.g. for SQL databases.</td>
+ </tr>
+ </table>
+ \endraw
+
+ \target raw-command
+ \section1 \\raw \span {class="newStuff"} {(avoid)}
+
+ The \\raw command and the corresponding
+ \\endraw command delimit a block of raw mark-up language code.
+
+ \note Avoid using this command if possible, because it generates
+ DITA XML code that causes problems. If you are trying to generate
+ special table or list behavior, try to get the behavior you want
+ using the \l {span-command} {\\span} and \l {div-command} {\\div}
+ commands in your \l {table-command} {\\table} or \l {list-command}
+ {\\list}.
+
+ The command takes an argument specifying the code's format.
+ Currently, the only supported format is HTML.
+
+ The \\raw command is useful if you want some special HTML effects
+ in your documentation.
+
+ \code
+ / *!
+ Qt has some predefined QColor objects.
+
+ \raw HTML
+ <style type="text/css" id="colorstyles">
+ #color-blue { background-color: #0000ff; color: #ffffff }
+ #color-darkBlue { background-color: #000080; color: #ffffff }
+ #color-cyan { background-color: #00ffff; color: #000000 }
+ </style>
+
+ <p>
+ <tt id="color-blue">Blue(#0000ff)</tt>,
+ <tt id="color-darkBlue">dark blue(#000080)</tt> and
+ <tt id="color-cyan">cyan(#00ffff)</tt>.
+ </p>
+ \endraw
+ * /
+ \endcode
+
+ QDoc renders this as:
+
+ \quotation
+ Qt has some predefined QColor objects.
+
+ \raw HTML
+ <style type="text/css" id="colorstyles">
+ #color-blue { background-color: #0000ff; color: #ffffff }
+ #color-darkBlue { background-color: #000080; color: #ffffff }
+ #color-cyan { background-color: #00ffff; color: #000000 }
+ </style>
+
+ <p>
+ <tt id="color-blue">Blue(#0000ff)</tt>,
+ <tt id="color-darkBlue">dark blue(#000080)</tt> and
+ <tt id="color-cyan">cyan(#00ffff)</tt>.
+ </p>
+ \endraw
+ \endquotation
+
+ \note But you can achieve the exact same thing using qdoc
+ commands. In this case, all you have to do is include the color
+ styles in your style.css file. Then you can write:
+
+ \code
+ \tt {\span {id="color-blue"} {Blue(#0000ff)}},
+ \tt {\span {id="color-darkBlue"} {dark blue(#000080)}} and
+ \tt {\span {id="color-cyan"} {cyan(#00ffff)}}.
+ \endcode
+
+ ...which is rendered as:
+
+ \tt {\span {id="color-blue"} {Blue(#0000ff)}},
+ \tt {\span {id="color-darkBlue"} {dark blue(#000080)}} and
+ \tt {\span {id="color-cyan"} {cyan(#00ffff)}}.
+
+ \target unicode-command
+ \section1 \\unicode
+
+ The \\unicode command allows you to insert an arbitrary Unicode
+ character in the document.
+
+ The command takes an argument specifying the character as an
+ integer. By default, base 10 is assumed, unless a '0x' or '0'
+ prefix is specified (for base 16 and 8, respectively). For
+ example:
+
+ \code
+ O G\unicode{0xEA}nio e as Rosas
+
+ \unicode 0xC0 table en famille avec 15 \unicode 0x20AC par jour
+
+ \unicode 0x3A3 \e{a}\sub{\e{i}}
+ \endcode
+
+ QDoc renders this as:
+
+ \quotation
+ O G\unicode{0xEA}nio e as Rosas
+
+ \unicode 0xC0 table en famille avec 15 \unicode 0x20AC par jour
+
+ \unicode 0x3A3 \e{a}\sub{\e{i}}
+ \endquotation
+*/
+
diff --git a/src/tools/qdoc/doc/qdoc-manual-qdocconf-minimal.qdoc b/src/tools/qdoc/doc/qdoc-manual-qdocconf-minimal.qdoc
deleted file mode 100644
index dd4becef17..0000000000
--- a/src/tools/qdoc/doc/qdoc-manual-qdocconf-minimal.qdoc
+++ /dev/null
@@ -1,78 +0,0 @@
-/****************************************************************************
-**
-** Copyright (C) 2013 Digia Plc and/or its subsidiary(-ies).
-** Contact: http://www.qt-project.org/legal
-**
-** This file is part of the documentation of the Qt Toolkit.
-**
-** $QT_BEGIN_LICENSE:FDL$
-** Commercial License Usage
-** Licensees holding valid commercial Qt licenses may use this file in
-** accordance with the commercial license agreement provided with the
-** Software or, alternatively, in accordance with the terms contained in
-** a written agreement between you and Digia. For licensing terms and
-** conditions see http://qt.digia.com/licensing. For further information
-** use the contact form at http://qt.digia.com/contact-us.
-**
-** GNU Free Documentation License Usage
-** Alternatively, this file may be used under the terms of the GNU Free
-** Documentation License version 1.3 as published by the Free Software
-** Foundation and appearing in the file included in the packaging of
-** this file. Please review the following information to ensure
-** the GNU Free Documentation License version 1.3 requirements
-** will be met: http://www.gnu.org/copyleft/fdl.html.
-** $QT_END_LICENSE$
-**
-****************************************************************************/
-/*!
-\page qdoc-manual-qdocconf-minimal
-\title Minimal qdocconf file
-\brief Describes a qdocconf file with a minimal number of statements
-
-The full contents of the minimal qdocconf file:
-
-\code
- #include(compat.qdocconf)
- headerdirs = .
- sourcedirs = .
- exampledirs = .
- imagedirs = ./images
-
-\endcode
-
-\title Statements with Comments
-
-\code
- #include(compat.qdocconf)
-\endcode
-
-In order to avoid compatibility issues between different versions of QDoc,
-it is advised to include compat.qdocconf.
-
-\code
- headerdirs = .
-\endcode
-
-The header files associated with the .cpp source files can be found in the
-current directory.
-
-\code
- #sourcedirs = .
-\endcode
-
-The .cpp or .qdoc files can be found in the current directory.
-
-\code
- exampledirs = .
-\endcode
-
-The source code of the example files can be found in the current directory.
-
-\code
- imagedirs = ./images
-\endcode
-
-The images used in the documentation can be found in subdirectory \e images.
-
-\note Please take care with this minimal qdocconf file. Using it in the wrong directory could cause qdoc to include a large number of files.
-*/
diff --git a/src/tools/qdoc/doc/qdoc-manual-qdocconf.qdoc b/src/tools/qdoc/doc/qdoc-manual-qdocconf.qdoc
new file mode 100644
index 0000000000..74f5ad0c7b
--- /dev/null
+++ b/src/tools/qdoc/doc/qdoc-manual-qdocconf.qdoc
@@ -0,0 +1,1603 @@
+/****************************************************************************
+**
+** Copyright (C) 2013 Digia Plc and/or its subsidiary(-ies).
+** Contact: http://www.qt-project.org/legal
+**
+** This file is part of the documentation of the Qt Toolkit.
+**
+** $QT_BEGIN_LICENSE:FDL$
+** Commercial License Usage
+** Licensees holding valid commercial Qt licenses may use this file in
+** accordance with the commercial license agreement provided with the
+** Software or, alternatively, in accordance with the terms contained in
+** a written agreement between you and Digia. For licensing terms and
+** conditions see http://qt.digia.com/licensing. For further information
+** use the contact form at http://qt.digia.com/contact-us.
+**
+** GNU Free Documentation License Usage
+** Alternatively, this file may be used under the terms of the GNU Free
+** Documentation License version 1.3 as published by the Free Software
+** Foundation and appearing in the file included in the packaging of
+** this file. Please review the following information to ensure
+** the GNU Free Documentation License version 1.3 requirements
+** will be met: http://www.gnu.org/copyleft/fdl.html.
+** $QT_END_LICENSE$
+**
+****************************************************************************/
+
+/*!
+ \page 21-0-qdoc-configuration.html
+ \previouspage Creating DITA Maps
+ \contentspage QDoc Manual
+ \nextpage Generic Configuration Variables
+
+ \title The QDoc Configuration File
+
+ Before running QDoc, you must create a QDoc configuration file to
+ tell QDoc where to find the source files that contain the QDoc
+ comments. The pathname to your configuration file is passed to
+ QDoc on the command line:
+
+ \quotation
+ \c {/current/dir$ ../../bin/qdoc ./config.qdocconf}
+ \endquotation
+
+ \section1 General Description
+
+ The configuration file is a list of entries of the form \e
+ {"variable = value"}. Using the configuration variables, you can
+ define where QDoc should find the various source files, images and
+ examples, where to put generated documentation etc. The
+ configuration file can also contain directives like \c
+ include. For an example, see \l {minimal-qdocconf}{a minimal qdocconf file}.
+
+ You can also use configuration variables to get QDoc to support
+ \l{Supporting Derived Projects} {derived projects}, i.e QDoc can
+ generate links in your project's documentation to elements in the
+ Qt online documentation. See the \l {Supporting Derived projects}
+ section.
+
+ The value of a configuration variable can be set using either '='
+ or '+='. The difference is that '=' overrides the previous value,
+ while '+=' adds a new value to the current one.
+
+ Some configuration variables accept a list of strings as their
+ value, for example:
+ \l {22-qdoc-configuration-generalvariables.html#sourcedirs-variable}
+ {\c{sourcedirs}}, while others accept only a single string. Double
+ quotes around a value string are optional, but including them allows
+ you to use special characters like '=' and ' \" ' within the value
+ string, for example:
+
+ \code
+ HTML.postheader = "<a href=\"index.html\">Home</a>"
+ \endcode
+
+ If an entry spans many lines, use a backslash at the end of every
+ line but the last:
+
+ \code
+ sourcedirs = kernel \
+ tools \
+ widgets
+ \endcode
+
+ \section1 Configuration Variables
+
+ \section1 Variable List
+
+ \list
+ \li \l {22-qdoc-configuration-generalvariables.html#alias-variable} {alias}
+ \li \l {23-qdoc-configuration-cppvariables.html#Cpp.ignoredirectives-variable} {Cpp.ignoredirectives}
+ \li \l {23-qdoc-configuration-cppvariables.html#Cpp.ignoretokens-variable} {Cpp.ignoretokens}
+ \li \l {22-qdoc-configuration-generalvariables.html#defines-variable} {defines}
+ \li \l {22-qdoc-configuration-generalvariables.html#edition-variable} {edition}
+ \li \l {22-qdoc-configuration-generalvariables.html#exampledirs-variable} {exampledirs}
+ \li \l {22-qdoc-configuration-generalvariables.html#examples-variable} {examples}
+ \li \l {22-qdoc-configuration-generalvariables.html#examples.fileextensions-variable} {examples.fileextensions}
+ \li \l {22-qdoc-configuration-generalvariables.html#excludedirs-variable} {excludedirs}
+ \li \l {22-qdoc-configuration-generalvariables.html#excludefiles-variable} {excludefiles}
+ \li \l {22-qdoc-configuration-generalvariables.html#extraimages-variable} {extraimages}
+ \li \l {22-qdoc-configuration-generalvariables.html#falsehoods-variable} {falsehoods}
+ \li \l {22-qdoc-configuration-generalvariables.html#headerdirs-variable} {headerdirs}
+ \li \l {22-qdoc-configuration-generalvariables.html#headers-variable} {headers}
+ \li \l {22-qdoc-configuration-generalvariables.html#headers.fileextensions-variable} {headers.fileextensions}
+ \li \l {24-qdoc-configuration-htmlvariables.html#HTML.footer-variable} {HTML.footer}
+ \li \l {24-qdoc-configuration-htmlvariables.html#HTML.postheader-variable} {HTML.postheader}
+ \li \l {24-qdoc-configuration-htmlvariables.html#HTML.style-variable} {HTML.style}
+ \li \l {22-qdoc-configuration-generalvariables.html#imagedirs-variable} {imagedirs}
+ \li \l {22-qdoc-configuration-generalvariables.html#images-variable} {images}
+ \li \l {22-qdoc-configuration-generalvariables.html#images.fileextensions-variable} {images.fileextensions}
+ \li \l {22-qdoc-configuration-generalvariables.html#language-variable} {language}
+ \li \l {22-qdoc-configuration-generalvariables.html#macro-variable} {macro}
+ \li \l {22-qdoc-configuration-generalvariables.html#manifestmeta-variable} {manifestmeta}
+ \li \l {22-qdoc-configuration-generalvariables.html#outputdir-variable} {outputdir}
+ \li \l {22-qdoc-configuration-generalvariables.html#outputformats-variable} {outputformats}
+ \li \l {22-qdoc-configuration-generalvariables.html#sourcedirs-variable} {sourcedirs}
+ \li \l {22-qdoc-configuration-generalvariables.html#sources-variable} {sources}
+ \li \l {22-qdoc-configuration-generalvariables.html#sources.fileextensions-variable} {sources.fileextensions}
+ \li \l {22-qdoc-configuration-generalvariables.html#spurious-variable} {spurious}
+ \li \l {22-qdoc-configuration-generalvariables.html#tabsize-variable} {tabsize}
+ \li \l {22-qdoc-configuration-generalvariables.html#version-variable} {version}
+ \li \l {22-qdoc-configuration-generalvariables.html#versionsym-variable} {versionsym}
+ \endlist
+
+ \section1 Categories
+
+ \list
+ \li \l {Generic Configuration Variables}
+ \li \l {C++ Specific Configuration Variables}
+ \li \l {HTML Specific Configuration Variables}
+ \endlist
+
+ \section1 Configuration File Examples
+
+ \list
+ \li A minimum configuration file: \l minimum.qdocconf
+ \li The Qt configuration file: \l qtgui.qdocconf
+ \endlist
+*/
+
+
+/*!
+ \page 22-qdoc-configuration-generalvariables.html
+ \previouspage The QDoc Configuration File
+ \contentspage QDoc Manual
+ \nextpage Creating Help Project Files
+
+ \title Generic Configuration Variables
+
+ With the general QDoc configuration variables, you can define
+ where QDoc will find the various source files it needs to generate
+ the documentation, as well as the directory to put the generated
+ documentation. You can also do some minor manipulation of QDoc
+ itself, controlling its output and processing behavior.
+
+ \target alias-variable
+ \section1 alias
+
+ The \c alias variable renames a QDoc command.
+
+ The general syntax is \tt {alias.\e{original-command-name} = \e
+ temporary-command-name}.
+
+ \code
+ alias.e = i
+ \endcode
+
+ This renames the built-in command \\e (italics) to be \\i. The \c
+ alias variable is often used for compatibility reasons.
+
+ See also \l {macro-variable} {macro}.
+
+ \target codeindent-variable
+ \section1 codeindent
+
+ The \c codeindent variable specifies the level of indentation that
+ QDoc uses when writing code snippets.
+
+ QDoc originally used a hard-coded value of four spaces for code
+ indentation to ensure that code snippets could be easily
+ distinguished from surrounding text. Since we can use \l{HTML
+ Specific Configuration Variables#HTML.stylesheets} {stylesheets}
+ to adjust the appearance of certain types of HTML elements, this
+ level of indentation is not always required.
+
+ \target defines-variable
+ \section1 defines
+
+ The \c defines variable specifies the C++ preprocessor symbols
+ that QDoc will recognize and respond to.
+
+ When a preprocessor symbol is specified using the \c defines
+ variable, you can also use the \l {if-command} {\\if} command to
+ enclose documentation that only will be included if the
+ preprocessor symbol is defined.
+
+ The values of the variable are regular expressions (see QRegExp
+ for details). By default, no symbol is defined, meaning that code
+ protected with #ifdef...#endif will be ignored.
+
+ \code
+ defines = Q_QDOC \
+ QT_.*_SUPPORT \
+ QT_.*_LIB \
+ QT_COMPAT \
+ QT3_SUPPORT \
+ Q_WS_.* \
+ Q_OS_.* \
+ Q_BYTE_ORDER \
+ __cplusplus
+ \endcode
+
+ This ensures that QDoc will process the code that requires these
+ symbols to be defined. For example:
+
+ \code
+ #ifdef Q_WS_WIN
+ HDC getDC() const;
+ void releaseDC(HDC) const;
+ #endif
+ \endcode
+
+ Since the Q_WS_.* regular expression (specified using the \c
+ defines variable) matches Q_WS_WIN, QDoc will process the code
+ within #ifdef and #endif in our example.
+
+ You can also define preprocessor symbols manually on the command
+ line using the -D option. For example:
+
+ \code
+ currentdirectory$ qdoc -Dconsoleedition qtgui.qdocconf
+ \endcode
+
+ In this case the -D option ensures that the \c consoleedition
+ preprocessor symbol is defined when QDoc processes the source
+ files defined in the qtgui.qdocconf file.
+
+ See also \l {falsehoods-variable} {falsehoods} and \l {if-command} {\\if}.
+
+ \target edition-variable
+ \section1 edition
+
+ The \c edition variable specifies which modules are included in
+ each edition of a package, and provides QDoc with information to
+ provide class lists for each edition.
+
+ This feature is mostly used when providing documentation for Qt
+ packages.
+
+ The \c edition variable is always used with a particular edition
+ name to define the modules for that edition:
+
+ \code
+ edition.Console = QtCore QtNetwork QtSql QtXml
+ edition.Desktop = QtCore QtGui QtNetwork QtOpenGL QtSql QtXml \
+ QtDesigner QtAssistant Qt3Support QAxContainer \
+ QAxServer
+ edition.DesktopLight = QtCore QtGui Qt3SupportLight
+ \endcode
+
+ In the above examples, the \c Console edition only includes the
+ contents of four modules. Only the classes from these modules will
+ be used when the \l{Miscellaneous#generatelist-command}
+ {generatelist} command is used to generate a list of classes for
+ this edition:
+
+ \code
+ \generatelist{classesbyedition Console}
+ \endcode
+
+ \target exampledirs-variable
+ \section1 exampledirs
+
+ The \c exampledirs variable specifies the directories containing
+ the source code of the example files.
+
+ The \l {examples-variable} {examples} and \l
+ {exampledirs-variable} {exampledirs} variables are used by the \l
+ {quotefromfile-command} {\\quotefromfile}, \l {quotefile-command}
+ {\\quotefile} and \l {example-command} {\\example} commands. If
+ both the \l {examples-variable} {examples} and \l
+ {exampledirs-variable} {exampledirs} variables are defined, QDoc
+ will search in both, first in \l {examples-variable} {examples}
+ then in \l {exampledirs-variable} {exampledirs}.
+
+ QDoc will search through the directories in the specified order,
+ and accept the first matching file it finds. It will only search
+ in the specified directories, \e not in subdirectories.
+
+ \code
+ exampledirs = $QTDIR/doc/src \
+ $QTDIR/examples \
+ $QTDIR \
+ $QTDIR/qmake/examples
+
+ examples = $QTDIR/examples/widgets/analogclock/analogclock.cpp
+ \endcode
+
+ When processing
+
+ \code
+ \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
+
+ \code
+ $QTDIR/doc/src/widgets/calculator/calculator.cpp
+ \endcode
+
+ If it doesn't, QDoc will continue looking for a file called
+
+ \code
+ $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:
+
+ \code
+ \quotefromfile calculator.cpp
+ \endcode
+
+ See also \l {exampledirs-variable} {exampledirs}.
+
+ \target examples.fileextensions-variable
+ \section1 examples.fileextensions
+
+ The \c examples.fileextensions variable specifies the file
+ extensions that qdoc will look for when collecting example files
+ for display in the documentation.
+
+ The default extensions are *.cpp, *.h, *.js, *.xq, *.svg, *.xml
+ and *.ui.
+
+ The extensions are given as standard wildcard expressions. You
+ can add a file extension to the filter using '+='. For example:
+
+ \code
+ 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:
+
+ \code
+ 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.
+
+ \code
+ excludefiles += $QT_CORE_SOURCES/../../src/widgets/kernel/qwidget.h \
+ $QT_CORE_SOURCES/../../src/widgets/kernel/qwidget.cpp
+ \endcode
+
+ If you include the above in your qdocconf file for qtbase, there
+ will be no qwidget.html generated for html and no qwidget.xml
+ generated for DITA XML.
+
+ See also \l {excludedirs-variable} {excludedirs}.
+
+ \target extraimages-variable
+ \section1 extraimages
+
+ The \c extraimages variable tells QDoc to incorporate specific
+ images in the generated documentation.
+
+ QDoc will not recognize images used within HTML (or any other
+ markup language). If we want the images to be copied from the
+ directories specified by \l {imagedirs} {\c imagedirs} (the images
+ in question must be located in these directories) to the output
+ directory, we must specify the images using the \c extraimages
+ variable.
+
+ The general syntax is \tt {extraimages.\e{format} = \e image}. The
+ file extension is optional.
+
+ For example, in \l qtgui.qdocconf we use a couple of images within
+ the HTML.postheader variable which value is pure HTML. For that
+ reason, these images are specified using the \c extraimages
+ variable:
+
+ \code
+ extraimages.HTML = qt-logo
+ \endcode
+
+ See also \l images and \l imagedirs.
+
+ \target falsehoods-variable
+ \section1 falsehoods
+
+ The \c falsehoods variable defines the truth value of specified
+ preprocessor symbols as false.
+
+ If this variable is not set for a preprocessor symbol, QDoc
+ assumes its truth value is true. The exception is '0', which value
+ always is false.
+
+ QDoc will recognize, and is able to evaluate, the following
+ preprocessor syntax:
+
+ \code
+ #ifdef NOTYET
+ ...
+ #endif
+
+ #if defined (NOTYET)
+ ...
+ #end if
+ \endcode
+
+ However, faced with unknown syntax like
+
+ \code
+ #if NOTYET
+ ...
+ #endif
+ \endcode
+
+ QDoc will evaluate it as true by default, \e unless the
+ preprocessor symbol is specified within the \c falsehoods variable
+ entry:
+
+ \code
+ 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.
+
+ \code
+ headerdirs = $QTDIR/src \
+ $QTDIR/extensions/activeqt \
+ $QTDIR/extensions/motif \
+ $QTDIR/tools/designer/src/lib/extension \
+ $QTDIR/tools/designer/src/lib/sdk \
+ $QTDIR/tools/designer/src/lib/uilib
+ \endcode
+
+ When executed, the first thing QDoc will do is to read through the
+ headers specified in the \l {headers} {\c headers} variable, and
+ the ones located in the directories specified in the \c headerdir
+ variable (including all subdirectories), building an internal
+ structure of the classes and their functions.
+
+ Then it will read through the sources specified in the \l
+ {sources-variable} {\c sources}, and the ones located in the
+ directories specified in the \l {sourcedirs-variable} {\c
+ sourcedirs} varible (including all subdirectories), merging the
+ documentation with the structure it retrieved from the header
+ files.
+
+ If both the \c headers and \c headerdirs variables are defined,
+ QDoc will read through both, first \l {headers} {\c headers} then
+ \c headerdirs.
+
+ In the specified directories, QDoc will only read the files with
+ the \c fileextensions specified in the \l {headers.fileextensions}
+ {\c headers.fileextensions} variable. The default extensions are
+ *.ch, *.h, *.h++, *.hh, *.hpp, and *.hxx". The files specified by
+ \l {headers} {\c headers} will be read without taking into account
+ their fileextensions.
+
+ See also \l headers and \l headers.fileextensions.
+
+ \target headers-variable
+ \section1 headers
+
+ The \c headers variable allows you to specify individual header
+ files in addition to those located in the directories specified by
+ the \l {headerdirs} {\c headerdirs} variable.
+
+ \code
+ 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:
+
+ \code
+ header.fileextensions += *.H
+ \endcode
+
+ \warning The above assignment may not work as described.
+
+ See also \l headerdirs.
+
+ \target imagedirs-variable
+ \section1 imagedirs
+
+ The \c imagedirs variable specifies the directories containing the
+ images used in the documentation.
+
+ The \l {images} {\c images} and \c imagedirs variables are used by
+ the \l {image-command} {\\image} and \l {inlineimage-command}
+ {\\inlineimage} commands. If both the \l {images} {\c images} and
+ \c imagedirs variables are defined, QDoc will search in both. First
+ in \l {images} {\c images}, then in \c imagedirs.
+
+ QDoc will search through the directories in the specified order,
+ and accept the first matching file it finds. It will only search
+ in the specified directories, \e not in subdirectories.
+
+ \code
+ imagedirs = $QTDIR/doc/src/images \
+ $QTDIR/examples
+
+ images = $QTDIR/doc/src/images/calculator-example.png
+ \endcode
+
+ When processing
+
+ \code
+ \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:
+
+ \code
+ $QTDIR/doc/src/images/calculator-example.png
+ \endcode
+
+ If the file doesn't exist, QDoc will look for a file called
+
+ \code
+ $QTDIR/examples/calculator-example.png
+ \endcode
+
+ You can filter the images in an image directory using the \l
+ {images.fileextensions} {\c images.fileextensions} variable. The
+ general idea behind the \l {images.fileextensions} {\c images.fileextensions}
+ variable is to enable different image format for different output format.
+
+ \warning The \l {images.fileextensions} {\c images.fileextensions}
+ variable's functionality is preliminary since QDoc at this point
+ only supports HTML.
+
+ See also \l images and \l images.fileextensions.
+
+ \target images-variable
+ \section1 images
+
+ The \c images variable allows you to specify individual image
+ files in addition to those located in the directories specified by
+ the \l {imagedirs} {\c imagedirs} variable.
+
+ \code
+ images = $QTDIR/doc/src/images/calculator-example.png
+ \endcode
+
+ When processing the \c images variable, QDoc behaves in the same
+ way as it does when processing the \l {imagedirs} {\c imagedirs}
+ variable. For more information, see the \l {imagedirs} {\c
+ imagedirs} variable.
+
+ See also \l imagedirs and \l images.fileextensions.
+
+ \target images.fileextensions-variable
+ \section1 images.fileextensions
+
+ The images.fileextensions variable filters the files within an
+ image directory.
+
+ The variable's values (the extensions) are given as standard
+ wildcard expressions. The general syntax is: \tt
+ {images.fileextensions.\e{format} = *.\e{extension}}.
+
+ The idea is to enable different image format for different output
+ format.
+
+ \code
+ images.fileextensions.HTML = *.png
+ images.fileextensions.LOUT = *.eps
+ \endcode
+
+ Then, when processing the \l {image-command} {\\image} and \l
+ {inlineimage-command} {\\inlineimage} commands, QDoc will only
+ search for files with extensions specified in the variable
+ containing the list of output formats.
+
+ \warning This is only a preliminary functionality since QDoc at this
+ point only supports HTML.
+
+ The default extensions for HTML are *.png, *.jpg, *.jpeg, and
+ *.gif.
+
+ You can add a file extension to the filter using '+='. For
+ example:
+
+ \code
+ images.fileextensions.HTML += *.eps
+ \endcode
+
+ See also \l imagedirs and \l images.
+
+ \target language-variable
+ \section1 language
+
+ The \c language variable specifies the language of the source code
+ that is used in the documentation.
+
+ Currently, C++ is the only language that QDoc understands. It is
+ also the default language, and doesn't really need to be
+ specified. However, a possible example of a language variable
+ statement:
+
+ \code
+ language = Cpp
+ \endcode
+
+ This identifies C++ as the language of the Qt source code.
+
+ \target macro-variable
+ \section1 macro
+
+ The \c macro variable is used to create your own simple QDoc
+ commands. The syntax is \tt {macro.\e{command} = \e{definition}},
+ where the definition is written using QDoc syntax.
+
+ A macro variable can be restricted for use in one type of output
+ generation. By appending \c {.HTML} to the macro name, for
+ example, the macro is only used when generating HTML output. By
+ appending \c {.DITAXML} to the macro name, the macro is only used
+ when generating DITA XML.
+
+ \code
+ macro.gui = "\\b"
+ macro.raisedaster.HTML = "<sup>*</sup>"
+ \endcode
+
+ The first macro defines the \\gui command to render its argument
+ using a bold font. The second macro defines the \\raisedaster
+ command to render a superscript asterisk, but only when generating
+ HTML.
+
+ See also \l {alias-variable} {alias}.
+
+ \target manifestmeta-variable
+ \section1 manifestmeta
+
+ The \c manifestmeta variable specifies additional meta-content
+ for the example manifest files generated by QDoc.
+
+ See the \l{Manifest Meta Content} section for more information.
+
+ \target naturallanguage-variable
+ \section1 naturallanguage
+
+ The \c naturallanguage variable specifies the natural language
+ used for the documentation generated by qdoc.
+
+ \code
+ naturallanguage = zh-Hans
+ \endcode
+
+ By default, the natural language is \c en for compatibility with
+ legacy documentation.
+
+ qdoc will add the natural language information to the HTML it
+ generates, using the \c lang and \c xml:lang attributes.
+
+ See also \l {sourceencoding-variable} {sourceencoding},
+ \l {outputencoding-variable} {outputencoding},
+ \l{http://www.w3.org/TR/xhtml1/#C_7}
+ {C.7. The lang and xml:lang Attributes} and
+ \l{http://www.w3.org/TR/i18n-html-tech-lang/#ri20040429.113217290}
+ {Best Practice 13: Using Hans and Hant codes}.
+
+ \target outputdir-variable
+ \section1 outputdir
+
+ The \c outputdir variable specifies the directory where QDoc will
+ put the generated documentation.
+
+ \code
+ 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
+
+ \code
+ $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.
+
+ \code
+ outputencoding = UTF-8
+ \endcode
+
+ By default, the output encoding is \c ISO-8859-1 (Latin1) for
+ compatibility with legacy documentation. When generating
+ documentation for some languages, particularly non-European
+ languages, this is not sufficient and an encoding such as UTF-8 is
+ required.
+
+ qdoc will encode HTML using this encoding and generate the correct
+ declarations to indicate to browsers which encoding is being
+ used. The \l naturallanguage configuration variable should also be
+ specified to provide browsers with a complete set of character
+ encoding and language information.
+
+ See also \l outputencoding and \l naturallanguage.
+
+ \target outputformats-variable
+ \section1 outputformats
+
+ The \c outputformats variable specifies the format of
+ the generated documentation.
+
+ Currently, QDoc only supports the HTML format. It is also
+ the default format, and doesn't need to be specified.
+
+ \target outputprefixes
+ \section1 outputprefixes
+
+ The \c outputprefixes variable specifies a mapping between types of files
+ and the prefixes to prepend to the HTML file names in the generated
+ documentation.
+
+ \code
+ outputprefixes = QML
+ outputprefixes.QML = uicomponents-
+ \endcode
+
+ By default, files containing the API documentation for QML types
+ are prefixed with "qml-". In the above example, the
+ prefix \c "uicomponents" is used instead.
+
+ \target qhp-variable
+ \section1 qhp
+
+ The \c qhp variable is used to define the information to be
+ written out to Qt Help Project (\c{qhp}) files.
+
+ See the \l{Creating Help Project Files} chapter for information
+ about this process.
+
+ \target sourcedirs-variable
+ \section1 sourcedirs
+
+ The \c sourcedirs variable specifies the directories containing
+ the \c .cpp or \c .qdoc files used in the documentation.
+
+ \code
+ sourcedirs += .. \
+ ../../../examples/gui/doc/src
+ \endcode
+
+ When executed, the first thing QDoc will do is to read through the
+ headers specified in the \l {header-command} {\c header} variable,
+ and the ones located in the directories specified in the \c
+ headerdir variable (including all subdirectories), building an
+ internal structure of the classes and their functions.
+
+ Then it will read through the sources specified in the \l
+ {sources} {\c sources}, and the ones located in the directories
+ specified in the \l {sourcedirs} {\c sourcedirs} variable
+ (including all subdirectories), merging the documentation with the
+ structure it retrieved from the header files.
+
+ If both the \c sources and \c sourcedirs variables are defined,
+ QDoc will read through both, first \l {sources} {\c sources} then
+ \c sourcedirs.
+
+ In the specified directories, QDoc will only read the files with
+ the \c fileextensions specified in the \l {sources.fileextensions}
+ {\c sources.fileextensions} variable. The default extensions are
+ *.c++, *.cc, *.cpp and *.cxx. The files specified by \l {sources}
+ {\c sources} will be read independent of their fileextensions.
+
+ See also \l {sources-variable} {sources} and
+ \l {sources.fileextensions-variable} {sources.fileextensions}.
+
+ \target sourceencoding-variable
+ \section1 sourceencoding
+
+ The \c sourceencoding variable specifies the encoding used for the
+ source code and documentation.
+
+ \code
+ 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.
+
+ \code
+ sources = $QTDIR/src/gui/widgets/qlineedit.cpp \
+ $QTDIR/src/gui/widgets/qpushbutton.cpp
+ \endcode
+
+ When processing the \c sources variable, QDoc behaves in the same
+ way as it does when processing the \l {sourcedirs-variable}
+ {sourcedirs} variable. For more information, see the \l
+ {sourcedirs-variable} {sourcedirs} variable.
+
+ See also \l {sourcedirs-variable} {sourcedirs}.
+
+ \target sources.fileextensions-variable
+ \section1 sources.fileextensions
+
+ The \c sources.fileextensions variable filters the files within a
+ source directory.
+
+ When processing the source files specified in the \l {sourcedirs}
+ {\c sourcedirs} variable, QDoc will only read the files with the
+ fileextensions specified in the \c sources.fileextensions
+ variable. In this way QDoc avoid spending time reading irrelevant
+ files.
+
+ The default extensions are *.c++, *.cc, *.cpp and *.cxx.
+
+ The extensions are given as standard wildcard expressions. You
+ can add a file extension to the filter using '+='. For example:
+
+ \code
+ 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.
+
+ \code
+ 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:
+
+ \code
+ qt-4.0/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.
+
+ \code
+ 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.
+
+ \code
+ 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.
+
+ \code
+ version = 4.0.1
+ \endcode
+
+ When a version number is specified (using the \tt{\l version} or
+ \tt {\l versionsym} variables in a \c .qdocconf file), it is
+ accessible through the corresponding \\version command for use in
+ the documentation.
+
+ \warning The \\version command's functionality is not fully
+ implemented; currently it only works within raw HTML code.
+
+ See also \l versionsym.
+
+ \target versionsym-variable
+ \section1 versionsym
+
+ The \c versionsym variable specifies a C++ preprocessor symbol
+ that defines the version number of the documented software.
+
+ \code
+ versionsym = QT_VERSION_STR
+ \endcode
+
+ QT_VERSION_STR is defined in qglobal.h as follows
+
+ \code
+ #define QT_VERSION_STR "4.0.1"
+ \endcode
+
+ When a version number is specified (using the \tt{\l version} or
+ \tt {\l versionsym} variables in a \c .qdocconf file), it is
+ accessible through the corresponding \\version command for use in
+ the documentation.
+
+ \warning The \\version command's functionality is not fully
+ implemented. Currently, it only works within raw HTML code.
+
+ See also \l {version} {\\version}.
+*/
+
+/*!
+ \page 22-creating-help-project-files.html
+ \previouspage Generic Configuration Variables
+ \contentspage QDoc Manual
+ \nextpage C++ Specific Configuration Variables
+
+ \title Creating Help Project Files
+
+ \section1 Overview
+
+ Starting with Qt 4.4, Qt Assistant uses a different system for managing
+ Qt documentation that requires QDoc to generate inventories of files in a
+ format that is similar to the old style DCF format, but with additional
+ features.
+
+ Instead of hard-coding information about the documentation sets for Qt,
+ 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 qch variable with each set declared using a unique
+ identifier as a subvariable.
+
+ For example, the configuration file for the Qt documentation defines a
+ \c Qt documentation set by specifying information about the set as
+ subvariables with the \c{qhp.Qt} prefix:
+
+ \code
+ qhp.Qt.file = qt.qhp
+ qhp.Qt.namespace = com.trolltech.qt.440
+ qhp.Qt.virtualFolder = qdoc
+ qhp.Qt.indexTitle = Qt Reference Documentation
+ qhp.Qt.indexRoot =
+ qhp.Qt.extraFiles = classic.css images/qt-logo.png
+ qhp.Qt.filterAttributes = qt 4.4.0 qtrefdoc
+ qhp.Qt.customFilters.Qt.name = Qt 4.4.0
+ qhp.Qt.customFilters.Qt.filterAttributes = qt 4.4.0
+ qhp.Qt.subprojects = classes overviews examples
+ qhp.Qt.subprojects.classes.title = Classes
+ qhp.Qt.subprojects.classes.indexTitle = Qt's Classes
+ qhp.Qt.subprojects.classes.selectors = class
+ qhp.Qt.subprojects.overviews.title = Overviews
+ qhp.Qt.subprojects.overviews.indexTitle = All Overviews and HOWTOs
+ qhp.Qt.subprojects.overviews.selectors = fake:page,group,module
+ qhp.Qt.subprojects.examples.title = Tutorials and Examples
+ qhp.Qt.subprojects.examples.indexTitle = Qt Examples
+ qhp.Qt.subprojects.examples.selectors = fake:example
+ \endcode
+
+ 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:
+
+ \code
+ qhp.QtCreator.subprojects = manual
+ qhp.QtCreator.subprojects.manual.title = Qt Creator Manual
+ qhp.QtCreator.subprojects.manual.indexTitle = Qt Creator Manual
+ qhp.QtCreator.subprojects.manual.type = manual
+ \endcode
+
+ In this example, the page entitled "Qt Creator Manual" contains a nested
+ list of links to pages in the documentation which is duplicated in
+ Qt Assistant's Contents tab.
+*/
+
+/*!
+ \page 23-qdoc-configuration-cppvariables.html
+ \previouspage Creating Help Project Files
+ \contentspage QDoc Manual
+ \nextpage HTML Specific Configuration Variables
+
+ \title C++ Specific Configuration Variables
+
+ The C++ specific configuration variables are provided to avoid
+ erroneous documentation due to non-standard C++ constructs.
+
+ \target Cpp.ignoredirectives-variable
+ \section1 Cpp.ignoredirectives
+ The \c Cpp.ignoredirectives variable makes QDoc ignore the
+ specified non-standard constructs, within C++ source code.
+
+ If not specified by the \tt {\l Cpp.ignoretokens} or \tt {\l
+ Cpp.ignoredirectives} variables, non-standard constructs
+ (typically macros) can result in erroneous documentation.
+
+ \code
+ Cpp.ignoredirectives = Q_DECLARE_INTERFACE \
+ Q_DECLARE_OPERATORS_FOR_FLAGS \
+ Q_DECLARE_PRIVATE \
+ Q_DECLARE_PUBLIC \
+ Q_DISABLE_COPY \
+ Q_DUMMY_COMPARISON_OPERATOR \
+ Q_ENUMS \
+ Q_FLAGS \
+ Q_INTERFACES \
+ __attribute__
+ \endcode
+
+ makes sure that when processing the code below, for example, QDoc
+ will simply ignore the 'Q_ENUMS' and 'Q_FLAGS' expressions:
+
+ \code
+ class Q_CORE_EXPORT Qt {
+ Q_OBJECT
+ Q_ENUMS(Orientation TextFormat BackgroundMode
+ DateFormat ScrollBarPolicy FocusPolicy
+ ContextMenuPolicy CaseSensitivity
+ LayoutDirection ArrowType)
+ Q_ENUMS(ToolButtonStyle)
+ Q_FLAGS(Alignment)
+ Q_FLAGS(Orientations)
+ Q_FLAGS(DockWidgetAreas)
+
+ public:
+ ...
+ };
+ \endcode
+
+ The Q_OBJECT macro, however, is an exception: QDoc recognizes this
+ particular non-standard construct, so there is no need specifying
+ it using the \tt {\l Cpp.ignoredirectives} variable.
+
+ Regarding the Q_CORE_EXPORT macro; see the documentation of the
+ \tt {\l Cpp.ignoretokens} variable.
+
+ See also \l Cpp.ignoretokens.
+
+ \target Cpp.ignoretokens-variable
+ \section1 Cpp.ignoretokens
+
+ The \c Cpp.ignoretokens variable makes QDoc ignore the specified
+ non-standard constructs, within C++ source code.
+
+ If not specified by the \tt {\l Cpp.ignoretokens} or \tt {\l
+ Cpp.ignoredirectives} variables, non-standard constructs
+ (typically macros) can result in erroneous documentation.
+
+ In \l qtgui.qdocconf:
+
+ \code
+ Cpp.ignoretokens = QAXFACTORY_EXPORT \
+ QM_EXPORT_CANVAS \
+ ...
+ Q_COMPAT_EXPORT \
+ Q_CORE_EXPORT \
+ Q_EXPLICIT \
+ Q_EXPORT \
+ ...
+ Q_XML_EXPORT
+ \endcode
+
+ makes sure that when processing the code below, for example, QDoc
+ will simply ignore the 'Q_CORE_EXPORT' expression:
+
+ \code
+ class Q_CORE_EXPORT Qt {
+ Q_OBJECT
+ Q_ENUMS(Orientation TextFormat BackgroundMode
+ DateFormat ScrollBarPolicy FocusPolicy
+ ContextMenuPolicy CaseSensitivity
+ LayoutDirection ArrowType)
+ Q_ENUMS(ToolButtonStyle)
+ Q_FLAGS(Alignment)
+ Q_FLAGS(Orientations)
+ Q_FLAGS(DockWidgetAreas)
+ public:
+ ...
+ };
+ \endcode
+
+ Regarding the Q_OBJECT, Q_ENUMS and Q_FLAGS macros; see the
+ documentation of the \tt {\l Cpp.ignoredirectives} variable.
+
+ See also \l Cpp.ignoredirectives.
+*/
+
+/*!
+ \page 24-qdoc-configuration-htmlvariables.html
+ \previouspage C++ Specific Configuration Variables
+ \contentspage QDoc Manual
+ \nextpage Supporting Derived Projects
+
+ \title HTML Specific Configuration Variables
+
+ The HTML specific configuration variables define the generated
+ documentation's style, or define the contents of the
+ documentation's footer or postheader. The format of the variable
+ values are raw HTML.
+
+ \target HTML.footer-variable
+ \section1 HTML.footer
+
+ The \c HTML.footer variable defines the content of the generated
+ HTML documentation's footer.
+
+ The footer is rendered at the bottom of the generated
+ documentation page.
+
+ The variable's value is given as raw HTML code enclosed by
+ quotation marks. Note that if the value spans several lines, each
+ line needs to be enclosed by quotation marks.
+
+ \code
+ HTML.footer = "<p /><address><hr /><div align=\"center\">\n" \
+ ...
+ "</tr></table></div></address>"
+ \endcode
+
+ The complete variable entry provides the standard footer of the
+ \l {http://doc.qt.digia.com/4.0/index.html} {Qt Reference Documentation}.
+
+ \target HTML.postheader-variable
+ \section1 HTML.postheader
+
+ 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.
+
+ \code
+ 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.digia.com/}
+ {Qt Reference Documentation}.
+
+ \target HTML.style-variable
+ \section1 HTML.style
+
+ The HTML.style variable defines the style for
+ the generated HTML documentation.
+
+ The variable's value is given as raw HTML enclosed by quotation
+ marks. Note that if the value spans several lines, each line needs
+ to be enclosed by quotation marks.
+
+ \code
+ 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
+
+ provides the HTML style for the \l
+ {http://doc.qt.digia.com/4.0/index.html} {Qt Reference
+ Documentation}.
+
+ \target HTML.stylesheets-variable
+ \section1 HTML.stylesheets
+
+ 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:
+
+ \code
+ HTML.stylesheets = classic.css
+ \endcode
+
+ QDoc expects to find stylesheets in the directory containing the
+ \l qtgui.qdocconf file, and it will copy those specified to the output
+ directory alongside the HTML pages.
+
+*/
+
+/*!
+ \page 25-qdoc-configuration-derivedprojects.html
+ \previouspage HTML Specific Configuration Variables
+ \contentspage QDoc Manual
+ \nextpage Example Manifest Files
+
+ \title Supporting Derived Projects
+
+ Some configuration variables allow you to use QDoc to support
+ Qt-based projects. They allow your project to contain links to the
+ online Qt documentation, which means that QDoc will be able to
+ create links to the class reference documentation, without any
+ explicit linking command.
+
+ \target description-variable
+ \section1 description
+
+ The description variable holds a short description of the
+ associated project.
+
+ See also \l project.
+
+ \target indexes-variable
+ \section1 indexes
+
+ The \c indexes variable lists the index files that will be used to
+ generate references.
+
+ For example. to make a derived Qt project contain links to the Qt
+ Reference documentation, you need to specify the associated index
+ file:
+
+ \code
+ indexes = $QTDIR/doc/html/qt.index
+ \endcode
+
+ See also \l project and \l url.
+
+ \target project-variable
+ \section1 project
+
+ The \c project variable provides a name for the project associated
+ with the \c .qdocconf file.
+
+ The project's name is used to form a file name for the associated
+ project's \e index file.
+
+ \code
+ project = QtCreator
+ \endcode
+
+ This will cause an index file called \c qtcreator.index to be
+ created.
+
+ See also \l description and \l indexes.
+
+ \target url-variable
+ \section1 url
+
+ The \c url variable holds the base URL for the reference
+ documentation associated with the current project.
+
+ The URL is stored in the generated index file for the
+ project. When we use the index on its own, QDoc will use this as
+ the base URL when constructing links to classes, functions, and
+ other things listed in the index.
+
+ \code
+ project = Qt
+ description = Qt Reference Documentation
+ url = http://qt-project.org/doc/qt-4.8/
+
+ ...
+ \endcode
+
+ This makes sure that whenever \c qt.index is used to generate
+ references to for example Qt classes, the base URL is \c
+ http://doc.qt.digia.com/4.7.
+
+ See also \l indexes.
+
+ \target howto
+ \section1 How to Support Derived Projects
+
+ This feature makes use of the comprehensive indexes generated by
+ QDoc when it creates the Qt reference documentation.
+
+ For example, \l qtgui.qdocconf (the configuration file for Qt)
+ contains the following variable definitions:
+
+ \code
+ project = Qt
+ description = Qt Reference Documentation
+ url = http://qt-project.org/doc/qt-4.8/
+
+ ...
+ \endcode
+
+ The \l project variable name is used to form a file name for the
+ index file; in this case the \c qt.index file is created. The \l
+ url is stored in the index file. Afterwards, QDoc will use this
+ as the base URL when constructing links to classes, functions,
+ and other things listed in the index.
+
+*/
+
+/*!
+ \page 26-qdoc-configuration-example-manifest-files.html
+ \previouspage Supporting Derived Projects
+ \contentspage QDoc Manual
+
+ \title Example Manifest Files
+
+ QDoc generates XML files that contain information about all documented
+ examples and demos. These files, named \c {examples-manifest.xml} and
+ \c {demos-manifest.xml}, are used by Qt Creator to present a list of
+ examples in its welcome screen and to link to their documentation.
+
+ \section1 Manifest XML Structure
+
+ A manifest file has the following structure:
+
+ \code
+ <?xml version="1.0" encoding="UTF-8"?>
+ <instructionals module="QtGui">
+ <examples>
+ <example
+ name="Analog Clock Window Example"
+ docUrl="qthelp://org.qt-project.qtgui.502/qtgui/analogclock.html"
+ projectPath="gui/analogclock/analogclock.pro"
+ imageUrl="qthelp://org.qt-project.qtgui.502/qtgui/images/analogclock-window-example.png">
+ <description><![CDATA[The Analog Clock Window example shows how
+ to draw the contents of a custom window.]]></description>
+ <tags>analog,clock,window</tags>
+ <fileToOpen>gui/analogclock/main.cpp</fileToOpen>
+ </example>
+ ...
+ </examples>
+ </instructionals>
+ \endcode
+
+ Each \c {<example>} element contains information about a name,
+ description, the location of the project file and documentation,
+ as well as a list of tags associated with the example.
+
+ \target metacontent
+ \section1 Manifest Meta Content
+
+ It is possible to augment the manifest files with additional
+ meta-content - that is, extra attributes and tags for selected
+ examples, using the \c manifestmeta configuration command.
+
+ One use case for meta-content is highlighting a number of prominent
+ examples. Another is improving search functionality by adding
+ relevant keywords as tags for a certain category of examples.
+
+ The examples for which meta-content is applied to is specified using
+ one or more filters. Matching examples to filters is done based on
+ names, with each example name prefixed with a module name and a
+ slash. Simple wildcard matching is supported; by using \c {*} at the
+ end it's possible to match multiple examples with a single string.
+
+ Example:
+
+ \code
+ manifestmeta.filters = highlighted sql webkit global
+
+ manifestmeta.highlighted.names = "QtGui/Analog Clock Window Example" \
+ "QtWidgets/Analog Clock Example"
+ manifestmeta.highlighted.attributes = isHighlighted:true
+
+ manifestmeta.sql.names = "QtSql/*"
+ manifestmeta.sql.tags = database,sql
+
+ manifestmeta.webkit.names = "QtWebKitExamples/*"
+ manifestmeta.webkit.tags = webkit
+
+ manifestmeta.global.names = *
+ manifestmeta.global.tags = qt5
+ \endcode
+
+ Above, an \c isHighlighted attribute is added to two examples. If
+ the attribute value is omitted, QDoc uses the string \c {true} by
+ default. Extra tags are added for Qt WebKit and Qt SQL examples, and
+ another tag is applied to all examples by using just \c {*} as the
+ match string.
+*/
+/*!
+ \page 21-3-qt-dita-xml-output.html
+ \previouspage minimum.qdocconf
+ \contentspage QDoc Manual
+ \nextpage QDoc Manual
+
+ \title Generating DITA XML Output
+
+ QDoc can generate \l {http://dita.xml.org} {DITA XML output}.
+
+ In your configuration file, set your \c {outputformats} variable
+ to \c {DITAXML}, and send the output to an appropriate directory:
+
+ \code
+ outputdir = $QTDIR/doc/ditaxml
+ outputformats = DITAXML
+ \endcode
+
+ And include these macros in your configuration file to prevent
+ QDoc from doing some escaping that doesn't validate in XML:
+
+ \code
+ macro.aacute.DITAXML = "&aacute;"
+ macro.Aring.DITAXML = "&Aring;"
+ macro.aring.DITAXML = "&aring;"
+ macro.Auml.DITAXML = "&Auml;"
+ macro.br.DITAXML = " "
+ macro.BR.DITAXML = " "
+ macro.copyright.DITAXML = "&copy;"
+ macro.eacute.DITAXML = "&eacute;"
+ macro.hr.DITAXML = " "
+ macro.iacute.DITAXML = "&iacute;"
+ macro.oslash.DITAXML = "&oslash;"
+ macro.ouml.DITAXML = "&ouml;"
+ macro.raisedaster.DITAXML = "<sup>*</sup>"
+ macro.rarrow.DITAXML = "&rarr;"
+ macro.reg.DITAXML = "<sup>&reg;</sup>"
+ macro.uuml.DITAXML = "&uuml;"
+ macro.mdash.DITAXML = "&mdash;"
+ macro.emptyspan.DITAXML = " "
+ \endcode
+
+ You can also set default values for some of the tags in the DITA
+ \c {<prolog>} and \c {<metadata>} elements:
+
+ \code
+ dita.metadata.default.author = Qt Development Frameworks
+ dita.metadata.default.permissions = all
+ dita.metadata.default.publisher = Qt Project
+ dita.metadata.default.copyryear = 2013
+ dita.metadata.default.copyrholder = Qt Project
+ dita.metadata.default.audience = programmer
+ \endcode
+
+ See the \l {12-0-qdoc-commands-miscellaneous.html#meta-command}
+ {\\meta} command for more details on DITA metadata.
+
+*/
+
+
+/*!
+ \page 21-1-minimum-qdocconf.html
+ \previouspage qtgui.qdocconf
+ \contentspage QDoc Manual
+ \nextpage Generating DITA XML Output
+
+ \title minimum.qdocconf
+
+ \quotefile examples/minimum.qdocconf
+*/
+
+/*!
+ \page 21-2-qtgui-qdocconf.html
+ \previouspage Supporting Derived Projects
+ \contentspage QDoc Manual
+ \nextpage minimum.qdocconf
+
+ \title qtgui.qdocconf
+
+ \quotefile files/qtgui.qdocconf
+*/
diff --git a/src/tools/qdoc/doc/qdoc-manual-topiccmds.qdoc b/src/tools/qdoc/doc/qdoc-manual-topiccmds.qdoc
new file mode 100644
index 0000000000..3253a052a1
--- /dev/null
+++ b/src/tools/qdoc/doc/qdoc-manual-topiccmds.qdoc
@@ -0,0 +1,1608 @@
+/****************************************************************************
+**
+** Copyright (C) 2013 Digia Plc and/or its subsidiary(-ies).
+** Contact: http://www.qt-project.org/legal
+**
+** This file is part of the documentation of the Qt Toolkit.
+**
+** $QT_BEGIN_LICENSE:FDL$
+** Commercial License Usage
+** Licensees holding valid commercial Qt licenses may use this file in
+** accordance with the commercial license agreement provided with the
+** Software or, alternatively, in accordance with the terms contained in
+** a written agreement between you and Digia. For licensing terms and
+** conditions see http://qt.digia.com/licensing. For further information
+** use the contact form at http://qt.digia.com/contact-us.
+**
+** GNU Free Documentation License Usage
+** Alternatively, this file may be used under the terms of the GNU Free
+** Documentation License version 1.3 as published by the Free Software
+** Foundation and appearing in the file included in the packaging of
+** this file. Please review the following information to ensure
+** the GNU Free Documentation License version 1.3 requirements
+** will be met: http://www.gnu.org/copyleft/fdl.html.
+** $QT_END_LICENSE$
+**
+****************************************************************************/
+
+/*!
+ \page 13-qdoc-commands-topics.html
+ \previouspage Command Index
+ \contentspage QDoc Manual
+ \nextpage Context Commands
+
+ \title Topic Commands
+
+ A topic command tells QDoc which source code element is being
+ documented. Some topic commands allow you to create documentation
+ pages that aren't tied to any underlying source code element.
+
+ When QDoc processes a QDoc comment, it tries to connect the
+ comment to an element in the source code by first looking for a
+ topic command that names the source code element. If there is no
+ topic command, QDoc tries to connect the comment to the source
+ code element that immediately follows the comment. If it can't do
+ either of these and if there is no topic command that indicates
+ the comment does not have an underlying source code element (e.g.
+ \l{page-command} {\\page}), then the comment is discarded.
+
+ \target topic argument
+
+ The name of the entity being documented is usually the only
+ argument for a topic command. Use the complete name. Sometimes
+ there can be a second parameter in the argument. See e.g. \l
+ {page-command} {\\page}.
+
+ \code
+ \enum QComboBox::InsertPolicy
+ \endcode
+
+ The \l {fn-command} {\\fn} command is a special case. For the \l
+ {fn-command} {\\fn} command, use the function's signature
+ including the class qualifier.
+
+ \code
+ \fn void QGraphicsWidget::setWindowFlags(Qt::WindowFlags wFlags)
+ \endcode
+
+ A topic command can appear anywhere in a comment but must stand
+ alone on its own line. It is good practice is to let the topic command
+ be the first line of the comment. If the argument spans several
+ lines, make sure that each line (except the last one) is ended
+ with a backslash. Moreover, QDoc counts parentheses, which means
+ that if it encounters a '(' it considers everything until the
+ closing ')' as its argument.
+
+ If a topic command is repeated with different arguments, the
+ same documentation will appear for both the units.
+
+ \code
+ / *!
+ \fn void PreviewWindow::setWindowFlags()
+ \fn void ControllerWindow::setWindowFlags()
+
+ Sets the widgets flags using the QWidget::setWindowFlags()
+ function.
+
+ Then runs through the available window flags, creating a text
+ that contains the names of the flags that matches the flags
+ parameter, displaying the text in the widgets text editor.
+ * /
+ \endcode
+
+ The \c PreviewWindow::setWindowFlags() and \c
+ ControllerWindow::setWindowFlags() functions will get the same
+ documentation.
+
+ \target class-command
+ \section1 \\class
+
+ The \\class command is for documenting a C++ class. The argument
+ is the complete name of the class. The command tells QDoc that a
+ class is part of the public API, and lets you enter a detailed
+ description.
+
+ \code
+ / *!
+ \class QMap::iterator
+
+ \brief The QMap::iterator class provides an STL-style
+ non-const iterator for QMap and QMultiMap.
+
+ QMap features both \l{STL-style iterators} and
+ \l{Java-style iterators}. The STL-style iterators ...
+ * /
+ \endcode
+
+ The HTML documentation for the named class is written to a
+ \c{.html} file named from the class name, in lower case, and with
+ the double colon qualifier(s) replaced with '-'. For example, the
+ documentation for the \c QMap::Iterator class is written to \c
+ qmap-iterator.html.
+
+ \target framework
+
+ The file contains the class description from the \\class comment,
+ plus the documentation generated from QDoc comments for all the
+ class members: a list of the class's types, properties,
+ functions, signals, and slots.
+
+ In addition to the detailed description of the class, the \\class
+ comment typically contains a \l {brief-command} {\\brief} command
+ and one or more \l{Markup Commands}. See the \\class command for
+ any of the Qt class for examples. Here is a very simple example:
+
+ \code
+ / *!
+ \class PreviewWindow
+ \brief The PreviewWindow class is a custom widget.
+ displaying the names of its currently set
+ window flags in a read-only text editor.
+
+ \ingroup miscellaneous
+
+ The PreviewWindow class inherits QWidget. The widget
+ displays the names of its window flags set with the \l
+ {function} {setWindowFlags()} function. It is also
+ provided with a QPushButton that closes the window.
+
+ ...
+
+ \sa QWidget
+ * /
+ \endcode
+
+ The way QDoc renders this \\class will depend a lot on your \c
+ {style.css} file, but the general outline of the class reference
+ page will look like this:
+
+ \quotation
+ \raw HTML
+ <h1>PreviewWindow Class Reference</h1>
+ \endraw
+
+ The PreviewWindow class is a custom widget displaying
+ the names of its currently set window flags in a
+ read-only text editor. \l {preview window} {More...}
+
+ \raw HTML
+ <h3>Properties</h3>
+ \endraw
+
+ \list
+ \li 52 properties inherited from QWidget
+ \li 1 property inherited from QObject
+ \endlist
+
+ \raw HTML
+ <h3>Public Functions</h3>
+ \endraw
+
+ \list
+ \li \l {constructor} {PreviewWindow}(QWidget *parent = 0)
+ \li void \l {function} {setWindowFlags}(Qt::WindowFlags flags)
+ \endlist
+
+ \list
+ \li 183 public functions inherited from QWidget
+ \li 28 public functions inherited from QObject
+ \endlist
+
+ \raw HTML
+ <h3>Public Slots</h3>
+ \endraw
+
+ \list
+ \li 17 public slots inherited from QWidget
+ \li 1 public slot inherited from QObject
+ \endlist
+
+ \raw HTML
+ <h3>Additional Inherited Members</h3>
+ \endraw
+
+ \list
+ \li 1 signal inherited from QWidget
+ \li 1 signal inherited from QObject
+ \li 4 static public members inherited from QWidget
+ \li 4 static public members inherited from QObject
+ \li 39 protected functions inherited from QWidget
+ \li 7 protected functions inherited from QObject
+ \endlist
+
+ \target preview window
+
+ \raw HTML
+ <hr />
+ <h2>Detailed Description</h2>
+ \endraw
+
+ The PreviewWindow class is a custom widget displaying
+ the names of its currently set window flags in a
+ read-only text editor.
+
+ The PreviewWindow class inherits QWidget. The widget
+ displays the names of its window flags set with the \l
+ {function} {setWindowFlags()} function. It is also
+ provided with a QPushButton that closes the window.
+
+ ...
+
+ See also QWidget.
+
+ \raw HTML
+ <hr />
+ <h2>Member Function Documentation</h2>
+ \endraw
+
+ \target constructor
+ \raw HTML
+ <h3>PreviewWindow(QWidget *parent = 0)</h3>
+ \endraw
+
+ Constructs a preview window widget with \e parent.
+
+ \target function
+ \raw HTML
+ <h3>setWindowFlags(Qt::WindowFlags flags)</h3>
+ \endraw
+
+ Sets the widgets flags using the
+ QWidget::setWindowFlags() function.
+
+ Then runs through the available window flags,
+ creating a text that contains the names of the flags
+ that matches the flags parameter, displaying
+ the text in the widgets text editor.
+ \endquotation
+
+ \target enum-command
+ \section1 \\enum
+
+ The \\enum command is for documenting a C++ enum type. The
+ argument is the full name of the enum type.
+
+ The enum values are documented in the \\enum comment using the \l
+ {value-command} {\\value} command. If an enum value is not
+ documented with \\value, QDoc emits a warning. These warnings can
+ be avoided using the \l {omitvalue-command} {\\omitvalue} command
+ to tell QDoc that an enum value should not be documented. The enum
+ documentation will be included on the class reference page, header
+ file page, or namespace page where the enum type is defined. For
+ example, consider the enum type \c {Corner} in the Qt namespace:
+
+ \code
+ enum Corner {
+ TopLeftCorner = 0x00000,
+ TopRightCorner = 0x00001,
+ BottomLeftCorner = 0x00002,
+ BottomRightCorner = 0x00003
+ #if defined(QT3_SUPPORT) && !defined(Q_MOC_RUN)
+ ,TopLeft = TopLeftCorner,
+ TopRight = TopRightCorner,
+ BottomLeft = BottomLeftCorner,
+ BottomRight = BottomRightCorner
+ #endif
+ };
+ \endcode
+
+ This enum can be cocumented this way:
+
+ \code
+ / *!
+ \enum Qt::Corner
+
+ This enum type specifies a corner in a rectangle:
+
+ \value TopLeftCorner
+ The top-left corner of the rectangle.
+ \value TopRightCorner
+ The top-right corner of the rectangle.
+ \value BottomLeftCorner
+ The bottom-left corner of the rectangle.
+ \value BottomRightCorner
+ The bottom-right corner of the rectangle.
+
+ \omitvalue TopLeft
+ \omitvalue TopRight
+ \omitvalue BottomLeft
+ \omitvalue BottomRight
+ * /
+ \endcode
+
+ Note the inclusion of the namespace qualifier. QDoc will render
+ this enum type in \c {qt.html} like this:
+
+ \quotation
+ \raw HTML
+ <h3 class="fn"><a name="Corner-enum"></a>enum Qt::Corner</h3>
+
+ <p>This enum type specifies a corner in a rectangle:</p>
+
+ <table border="1" cellpadding="2" cellspacing="1" width="100%">
+ <tr>
+ <th width="25%">Constant</th>
+ <th width="15%">Value</th>
+ <th width="60%">Description</th>
+ </tr>
+
+ <tr>
+ <td valign="top"><tt>Qt::TopLeftCorner</tt></td>
+ <td align="center" valign="top"><tt>0x00000</tt></td>
+ <td valign="top">The top-left corner of the rectangle.</td>
+ </tr>
+
+ <tr>
+ <td valign="top"><tt>Qt::TopRightCorner</tt></td>
+ <td align="center" valign="top"><tt>0x00001</tt></td>
+ <td valign="top">The top-right corner of the rectangle.</td>
+ </tr>
+
+ <tr>
+ <td valign="top"><tt>Qt::BottomLeftCorner</tt></td>
+ <td align="center" valign="top"><tt>0x00002</tt></td>
+ <td valign="top">The bottom-left corner of the rectangle.</td>
+ </tr>
+
+ <tr>
+ <td valign="top"><tt>Qt::BottomRightCorner</tt></td>
+ <td align="center" valign="top"><tt>0x00003</tt></td>
+ <td valign="top">The bottom-right corner of the rectangle.</td>
+ </tr>
+
+ </table>
+ \endraw
+ \endquotation
+
+ See also \l {value-command} {\\value} and \l {omitvalue-command} {\\omitvalue}.
+
+ \target example-command
+ \section1 \\example
+
+ The \\example command is for documenting an example. The argument
+ is the example's path relative to omne of the paths listed in the
+ \l {exampledirs-variable} {exampledirs} variable in the QDoc
+ configuration file.
+
+ The documentation page will be output to \c {path-to-example}.html.
+ QDoc will add a list of all the example's source files at the top
+ of the page.
+
+ For example, if \l {exampledirs-variable} {exampledirs} contains
+ \c $QTDIR/examples/widgets/imageviewer, then
+
+ \code
+ / *!
+ \example widgets/imageviewer
+ \title ImageViewer Example
+ \subtitle
+
+ The example shows how to combine QLabel and QScrollArea
+ to display an image.
+
+ ...
+ * /
+ \endcode
+
+ QDoc renders this example in widgets-imageviewer.html:
+
+ \quotation
+ \raw HTML
+ <center><h1>Image Viewer Example</h1></center>
+ \endraw
+
+ Files:
+ \list
+ \li \l{http://qt-project.org/doc/qt-5.0/qtwidgets/widgets-imageviewer-imageviewer-cpp.html}
+ {widgets/imageviewer/imageviewer.cpp}
+ \li \l{http://qt-project.org/doc/qt-5.0/qtwidgets/widgets-imageviewer-imageviewer-h.html}
+ {widgets/imageviewer/imageviewer.h}
+ \li \l{http://qt-project.org/doc/qt-5.0/qtwidgets/widgets-imageviewer-main-cpp.html}
+ {widgets/imageviewer/main.cpp}
+ \endlist
+
+ The example shows how to combine QLabel and QScrollArea
+ to display an image.
+
+ ...
+ \endquotation
+
+ \target externalpage-command
+ \section1 \\externalpage
+
+ The \\externalpage command assigns a title to an external URL.
+
+ \code
+ / *!
+ \externalpage http://qt-project.org/doc/
+ \title Qt Documentation Site
+ * /
+ \endcode
+
+ This allows you to include a link to the external page in your
+ documentation this way:
+
+ \code
+ / *!
+ At the \l {Qt Documentation Site} you can find the latest
+ documentation for Qt, Qt Creator, the Qt SDK and much more.
+ * /
+ \endcode
+
+ QDoc renders this as:
+
+ \quotation
+ At the \l {http://qt-project.org/doc/}{Qt Documentation Site}
+ you can find the latest documentation for Qt, Qt Creator, the Qt SDK
+ and much more.
+ \endquotation
+
+ To achieve the same result without using the \\externalpage
+ command, you would have to hard-code the address into your
+ documentation:
+
+ \code
+ / *!
+ At the \l {http://qt-project.org/doc/}{Qt Documentation Site}
+ you can find the latest documentation for Qt, Qt Creator, the Qt SDK
+ and much more.
+ * /
+ \endcode
+
+ The \\externalpage command makes it easier to maintain the
+ documentation. If the address changes, you only need to change the
+ argument of the \\externalpage command.
+
+ \target fn-command
+ \section1 \\fn (function)
+
+ The \\fn command is for documenting a function. The argument is
+ the function's signature, including its return type, const-ness,
+ and list of formal arguments with types. If the named function
+ doesn't exist, QDoc emits a warning.
+
+ \note The \\fn command is QDoc's default command: when no
+ topic command can be found in a QDoc comment, QDoc tries to tie
+ the documentation to the following code as if it is the
+ documentation for a function. Hence, it is normally not necessary
+ to include this command when documenting a function, if the
+ function's QDoc comment is written immediately above the function
+ implementation in the \c .cpp file. But it must be present when
+ documenting an inline function in the \c .cpp file that is
+ implemented in the \c .h file.
+
+ \code
+ / *!
+ \fn bool QToolBar::isAreaAllowed(Qt::ToolBarArea area) const
+
+ Returns true if this toolbar is dockable in the given
+ \a area; otherwise returns false.
+ * /
+ \endcode
+
+ QDoc renders this as:
+
+ \quotation
+ \raw HTML
+ <h3>bool QToolBar::isAreaAllowed(Qt::ToolBarArea area) const
+ </h3>
+ \endraw
+
+ Returns true if this toolbar is dockable in the given
+ \a area; otherwise returns false.
+ \endquotation
+
+ See also \l {overload-command} {\\overload}.
+
+ \target group-command
+ \section1 \\group
+
+ The \\group command creates a separate page that lists the classes
+ belonging to the group. The argument is the group name.
+
+ A class is included in a group by using the \l {ingroup-command}
+ {\\ingroup} command. Overview pages can also be related to a group
+ using the same command, but the list of overview pages must be
+ requested explicitly using the \l {generatelist-command}
+ {\\generatelist} command (see example below).
+
+ The \\group command is typically followed by a \l {title-command}
+ {\\title} command and a short introduction to the group. The
+ HTML page for the group is written to a \c {.html} file put in
+ <lower-case>\e{group}.html.
+
+ Each class name is listed as a link to the class reference page
+ followed by the text from the class's \l {brief-command} {\\brief}
+ texts.
+
+ \code
+ / *!
+ \group io
+
+ \title Input/Output and Networking
+
+ These classes are used to handle input and output to
+ and from external devices, processes, files etc., as
+ well as manipulating files and directories.
+ * /
+ \endcode
+
+ QDoc generates a group page in \c{io.html} that will look
+ like this:
+
+ \quotation
+ \raw HTML
+
+ <h1>Input/Output and Networking</h1>
+
+ <p>These classes are used to handle input and output
+ to and from external devices, processes, files etc., as
+ well as manipulating files and directories.</p>
+
+ <p>
+ <table width="100%">
+ <tr valign="top" bgcolor="#e0e0e0">
+ <td><b>
+ <a href="http://qt-project.org/doc/qt-5.0/qtnetwork/qabstractsocket.html">QAbstractSocket</a>
+ </b></td>
+ <td>
+ The base functionality common to all socket types
+ </td></tr>
+
+ <tr valign="top" bgcolor="#e0e0e0">
+ <td><b>
+ <a href="http://qt-project.org/doc/qt-5.0/qtcore/qbuffer.html">QBuffer</a>
+ </b></td>
+ <td>
+ QIODevice interface for a QByteArray
+ </td></tr>
+
+ <tr valign="top" bgcolor="#e0e0e0">
+ <td><b>
+ <a href="http://qt-project.org/doc/qt-5.0/qtgui/qclipboard.html">QClipboard</a>
+ </b></td>
+ <td>
+ Access to the window system clipboard
+ </td></tr>
+ </table>
+ \endraw
+ \endquotation
+
+ Note that overview pages related to the group, must be listed
+ explicitly using the \l {generatelist-command} {\\generatelist}
+ command with the \c related argument.
+
+ \code
+ / *!
+ \group architecture
+
+ \title Architecture
+
+ These documents describe aspects of Qt's architecture
+ and design, including overviews of core Qt features and
+ technologies.
+
+ \generatelist{related}
+ * /
+ \endcode
+
+ See also \l {ingroup-command} {\\ingroup} and \l
+ {generatelist-command} {\\generatelist}.
+
+ \target headerfile-command
+ \section1 \\headerfile
+
+ The \\headerfile command is for documenting the global functions,
+ types and macros that are declared in a header file, but not in a
+ namespace. The argument is the name of the header file. The HTML
+ page is written to a \c {.html} file constructed from the header
+ file argument.
+
+ The documentation for a function, type, or macro that is declared
+ in the header file being documented, is included in the header file
+ page using the \l {relates-command} {\\relates} command.
+
+ If the argument doesn't exist as a header file, the \\headerfile
+ command creates a documentation page for the header file anyway.
+
+ \code
+ / *!
+ \headerfile <QtAlgorithms>
+
+ \title Generic Algorithms
+
+ \brief The <QtAlgorithms> header file provides
+ generic template-based algorithms.
+
+ Qt provides a number of global template functions in \c
+ <QtAlgorithms> that work on containers and perform
+ well-know algorithms.
+ * /
+ \endcode
+
+ QDoc generates a header file page \c{qtalgorithms.html} that looks
+ like this:
+
+ \quotation
+ \raw HTML
+ <center><h1>&lt;QtAlgorithms&gt; -
+ Generic Algorithms</h1></center>
+ <p>The <QtAlgorithms> header file provides generic
+ template-based algorithms.
+ <a href="13-qdoc-commands-topics.html#header-command">More...</a>
+ </p>
+
+ <h3>Functions</h3>
+ <ul>
+ <li>RandomAccessIterator
+ <a href="http://qt-project.org/doc/qt-5.0/qtcore/qtalgorithms.html#qBinaryFind">qBinaryFind</a></b>
+ (RandomAccessIterator begin, RandomAccessIterator end,
+ const T & value)</li>
+ <li>...</li></ul>
+ <hr />
+ \endraw
+
+ \target header
+
+ \raw HTML
+ <h2>Detailed Description</h2>
+ <p>The <QtAlgorithms> header file provides generic
+ template-based algorithms. </p>
+ \endraw
+
+ Qt provides a number of global template functions in \c
+ <QtAlgorithms> that work on containers and perform
+ well-know algorithms.
+
+ ...
+ \endquotation
+
+ \target macro-command
+ \section1 \\macro
+
+ The \\macro command is for documenting a C++ macro. The argument
+ is the macro in one of three styles: function-like macros like
+ Q_ASSERT(), declaration-style macros like Q_PROPERTY(), and macros
+ without parentheses like Q_OBJECT.
+
+ The \\macro comment must contain a \l {relates-command}
+ {\\relates} command that attaches the macro comment to a class,
+ header file, or namespace. Otherwise, the documentation will be
+ lost. Here are three example macro comments followed by what they
+ might look like in \c {qtglobal.html} or \c {qobject.html}:
+
+ \code
+ / *!
+ \macro void Q_ASSERT(bool test)
+ \relates <QtGlobal>
+
+ Prints a warning message containing the source code
+ file name and line number if \a test is false.
+
+ ...
+
+ \sa Q_ASSERT_X(), qFatal(), {Debugging Techniques}
+ * /
+ \endcode
+
+ \quotation
+ \raw HTML
+ <h3>void Q_ASSERT ( bool <i>test</i> )</h3>
+ \endraw
+
+ Prints a warning message containing the source code
+ file name and line number if \a test is false.
+
+ ...
+
+ See also Q_ASSERT_X(), qFatal() and \l {Debugging Techniques}.
+
+ \endquotation
+
+ \code
+ / *!
+ \macro Q_PROPERTY(...)
+ \relates QObject
+
+ This macro declares a QObject property. The syntax is:
+
+ ...
+
+ \sa {Qt's Property System}
+ * /
+ \endcode
+
+ \quotation
+ \raw HTML
+ <h3>Q_PROPERTY ( ... )</h3>
+ \endraw
+
+ This macro declares a QObject property. The syntax is:
+
+ ...
+
+ See also \l {Qt's Property System}.
+ \endquotation
+
+ \code
+ / *!
+ \macro Q_OBJECT
+ \relates QObject
+
+ The Q_OBJECT macro must appear in the private section
+ of a class definition that declares its own signals and
+ slots, or that uses other services provided by Qt's
+ meta-object system.
+
+ ...
+
+ \sa {Meta-Object System}, {Signals and Slots}, {Qt's
+ Property System}
+ * /
+ \endcode
+
+ \quotation
+ \raw HTML
+ <h3>Q_OBJECT</h3>
+ \endraw
+
+ The Q_OBJECT macro must appear in the private section
+ of a class definition that declares its own signals and
+ slots or that uses other services provided by Qt's
+ meta-object system.
+
+ ...
+
+ See also \l {Meta-Object System}, \l {Signals &
+ Slots} and \l {Qt's Property System}.
+ \endquotation
+
+ \target module-command
+ \section1 \\module
+
+ The \\module creates a page that lists the classes belonging to
+ the module specified by the command's argument. A class included
+ in the module by including the \l {inmodule-command} {\\inmodule}
+ command in the \\class comment.
+
+ The \\module command is typically followed by a \l {title-command}
+ {\\title} and a \l {brief-command} {\\brief} command. Each class
+ is listed as a link to the class reference page followed by the
+ text from the class's \l {brief-command} {\\brief} command. For
+ example:
+
+ \code
+ / *!
+ \module QtNetwork
+
+ \title Qt Network Module
+
+ \brief Contains classes for writing TCP/IP clients and servers.
+
+ The network module provides classes to make network
+ programming easier and portable. It offers both
+ high-level classes such as QNetworkAccessManager that
+ implements application-level protocols, and
+ lower-level classes such as QTcpSocket, QTcpServer, and
+ QUdpSocket.
+ * /
+ \endcode
+
+ QDoc renders this in \c {qtnetwork.html} like this:
+
+ \quotation
+ \raw HTML
+ <h1><center>Qt Network Module</center></h1>
+ \endraw
+
+ The Qt Network module offers classes that allow you to
+ write TCP/IP clients and servers.\l {module
+ details} {More...}
+
+ \raw HTML
+ <p>
+ <table width="100%">
+ <tr valign="top" bgcolor="#d0d0d0">
+ <td><b>
+ <a href="http://qt-project.org/doc/qt-5.0/qtnetwork/qabstractsocket.html">QAbstractSocket</a>
+ </b></td>
+ <td>
+ The base functionality common to all socket types
+ </td></tr>
+
+ <tr valign="top" bgcolor="#d0d0d0">
+ <td><b>
+ <a href="http://doc.qt.digia.com/4.0/qftp.html">QFtp</a>
+ </b></td>
+ <td>
+ Implementation of the FTP protocol
+ </td></tr>
+
+ <tr valign="top" bgcolor="#d0d0d0">
+ <td>...</td>
+ <td>...</td>
+ </tr>
+ </table>
+
+ <p><hr /></p>
+ \endraw
+
+ \target module details
+
+ \raw HTML
+ <h2>Detailed Description</h2>
+
+ <p>
+ The Qt Network module offers classes that allow you to
+ write TCP/IP clients and servers.
+ </p>
+
+ <p>
+ The network module provides classes to make network
+ programming easier and portable. It offers both
+ high-level classes such as QNetworkAccessManager that
+ implements application-level protocols, and
+ lower-level classes such as QTcpSocket, QTcpServer, and
+ QUdpSocket.
+ </p>
+ \endraw
+
+ ...
+
+ \endquotation
+
+ See also \l {inmodule-command} {\\inmodule}
+
+ \target namespace-command
+ \section1 \\namespace
+
+ The \\namespace command is for documenting the contents of the C++
+ namespace named as its argument. The documentation outline QDoc
+ generates for a namespace is similar to the outline it generates
+ for a C++ class.
+
+ \code
+ / *!
+ \namespace Qt
+
+ \brief Contains miscellaneous identifiers used throughout the Qt library.
+ * /
+ \endcode
+
+ QDoc renders this in \c{qt.html} like this:
+
+ \quotation
+ \raw HTML
+ <center><h1>Qt Namespace Reference</h1></center>
+ <p>The Qt namespace contains miscellaneous
+ identifiers used throughout the Qt library.
+ <a href="13-qdoc-commands-topics.html#name">More...</a>
+ </p>
+
+ <pre>#include &lt;Qt&gt;</pre>
+ <ul>
+ <li>
+ <a href="http://doc.qt.digia.com/4.0/qt-qt3.html">
+ Qt 3 support members</a></li>
+ </ul>
+
+
+ <h3>Types</h3>
+ <ul>
+ <li>flags
+ <a href="http://doc.qt.digia.com/4.0/qt.html#AlignmentFlag-enum">Alignment</a></b></li>
+ <li>...</li></ul>
+ <hr />
+ \endraw
+
+ \target name
+
+ \raw HTML
+ <h2>Detailed Description</h2>
+ <p>Contains miscellaneous identifiers
+ used throughout the Qt library.</p>
+ \endraw
+
+ ...
+ \endquotation
+
+ \target page-command
+ \section1 \\page
+
+ The \\page command is for creating a stand-alone documentation
+ page. The argument can consist of two parts separated by a
+ space. The first part is the name of the file where QDoc should
+ store the page. The second part, if present, is a word that
+ specifies the page type. Currently, the second part can be one of
+ the following list of words:
+
+ \list
+
+ \li faq - A frequently asked question.
+
+ \li howto - A user guide on how to use some components of the
+ software.
+
+ \li example - A page that describes a working example.
+
+ \li overview - For text pages that provide an overview of some
+ important subject.
+
+ \li tutorial - For text pages that are part of a tutorial.
+
+ \li api - This is the type of page used for C++ class references and
+ QML type references. You should never use this one for the pages
+ you write, because this one is reserved for qdoc.
+
+ \endlist
+
+ The page title is set using the \l {title-command} {\\title}
+ command.
+
+ \code
+ / *!
+ \page aboutqt.html
+
+ \title About Qt
+
+ Qt is a C++ toolkit for cross-platform GUI
+ application development. Qt provides single-source
+ portability across Microsoft Windows, Mac OS X, Linux,
+ and all major commercial Unix variants.
+
+ Qt provides application developers with all the
+ functionality needed to build applications with
+ state-of-the-art graphical user interfaces. Qt is fully
+ object-oriented, easily extensible, and allows true
+ component programming.
+
+ ...
+ * /
+ \endcode
+
+ QDoc renders this page in \c {aboutqt.html}.
+
+ \target property-command
+ \section1 \\property
+
+ The \\property command is for documenting a Qt property. The
+ argument is the full property name.
+
+ A property is defined using the Q_PROPERTY() macro. The macro
+ takes as arguments the property's name and its set, reset and get
+ functions.
+
+ \code
+ Q_PROPERTY(QString state READ state WRITE setState)
+ \endcode
+
+ The set, reset and get functions don't need to be documented,
+ documenting the property is sufficient. QDoc will generate a list
+ of the access function that will appear in the property
+ documentation which in turn will be located in the documentation
+ of the class that defines the property.
+
+ The \\property command comment typically includes a \l
+ {brief-command} {\\brief} command. For properties the \l
+ {brief-command} {\\brief} command's argument is a sentence
+ fragment that will be included in a one line description of the
+ property. The command follows the same rules for the \l
+ {brief-property} {description} as the \l {variable-command}
+ {\\variable} command.
+
+ \code
+ / *!
+ \property QPushButton::flat
+ \brief Whether the border is disabled.
+
+ This property's default is false.
+ * /
+ \endcode
+
+ QDoc includes this in \c {qpushbutton.html} like this:
+
+ \quotation
+ \raw HTML
+ <h3>flat : bool</h3>
+ \endraw
+
+ This property holds whether the border is disabled.
+
+ This property's default is false.
+
+ Access functions:
+
+ \list
+ \li \b { bool isFlat () const}
+ \li \b { void setFlat ( bool )}
+ \endlist
+
+ \endquotation
+
+ \code
+ / *!
+ \property QWidget::width
+ \brief The width of the widget excluding any window frame.
+
+ See the \l {Window Geometry} documentation for an
+ overview of window geometry.
+
+ \sa geometry, height, size
+ * /
+ \endcode
+
+ QDoc includes this in \c {qwidget.html} like this:
+
+ \quotation
+ \raw HTML
+ <h3>width : const int</h3>
+ \endraw
+
+ This property holds the width of the widget excluding
+ any window frame.
+
+ See the \l {Window Geometry} documentation for an
+ overview of window geometry.
+
+ Access functions:
+
+ \list
+ \li \b { int width () const}
+ \endlist
+
+ See also \l{QWidget::geometry} {geometry},
+ \l{QWidget::height} {height}, and \l{QWidget::size} {size}.
+ \endquotation
+
+ \target service-command
+ \section1 \\service
+
+ The \\service command tells QDoc that a class is a service class
+ and names the service. The command takes two arguments, the name
+ of the class and the name of the service. Currently, this command
+ is not used in the Qt documentation.
+
+ \code
+ / *!
+ \service TimeService Time
+ ...
+ * /
+ class TimeService : public QCopObjectService
+ {
+ ...
+ }
+ \endcode
+
+ See also \l {class-command} {\\class} and \l
+ {generatelist-command} {\\generatelist}.
+
+ \target qmlattachedproperty-command
+ \section1 \\qmlattachedproperty
+
+ The \\qmlattachedproperty command is for documenting a QML
+ property that will be attached to some QML type. See
+ \l{http://qt-project.org/doc/qt-4.7/qdeclarativeintroduction.html#attached-properties}
+ {Attached Properties}. The argument is the rest of the line. The
+ argument text should be the property type, followed by the QML
+ element name where the property is being declared, the \c{::}
+ qualifier, and finally the property name. If we have a QML
+ attached property named \c isCurrentItem in QML \c ListView,
+ and the property has type \c {bool}, the \\qmlattachedproperty for
+ it would look like this:
+
+ \code
+ / *!
+ \qmlattachedproperty bool ListView::isCurrentItem
+ This attached property is true if this delegate is the current
+ item; otherwise false.
+
+ It is attached to each instance of the delegate.
+
+ This property may be used to adjust the appearance of the current
+ item, for example:
+
+ \snippet doc/src/snippets/declarative/listview/listview.qml isCurrentItem
+ * /
+ \endcode
+
+ QDoc includes this attached property on the QML reference page for the
+ \l{http://qt-project.org/doc/qt-4.7/qml-listview.html#isCurrentItem-prop}
+ {ListView} element.
+
+ \target qmlattachedsignal-command
+ \section1 \\qmlattachedsignal
+
+ The \\qmlattachedsignal command is for documenting an attachable
+ \l{http://qt-project.org/doc/qt-4.7/qdeclarativeintroduction.html#signal-handlers}
+ {signal handler}. 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 handler is declared, the \c{::}
+ qualifier, and finally the signal handler name. If we have a QML
+ attached signal handler named \c onAdd() in the \c GridView
+ element, the \\qmlattachedsignal for it would look like this:
+
+ \code
+ / *!
+ \qmlattachedsignal GridView::onAdd()
+ This attached handler is called immediately after an item is
+ added to the view.
+ * /
+ \endcode
+
+ QDoc includes this documentation on the QML reference page for the
+ \l{http://qt-project.org/doc/qt-4.7/qml-gridview.html#onAdd-signal}
+ {GridView} element.
+
+ \target qmlbasictype-command
+ \section1 \\qmlbasictype
+
+ The \\qmlbasictype command is for documenting a basic type for QML.
+ The argument is the type name. The type must be included in the
+ QML basic types group using the \l{ingroup-command}{\\ingroup}
+ command as shown below. This will cause QDoc to include the
+ documentation for the type on the
+ \l{http://qt-project.org/doc/qt-4.7/qdeclarativebasictypes.html}
+ {QML Basic Types} page. The \l{brief-command} {\\brief} command
+ is also required, because it appears on the
+ \l{http://qt-project.org/doc/qt-4.7/qdeclarativebasictypes.html}
+ {QML Basic Types} page as well.
+
+ \code
+ / *!
+ \qmlbasictype int
+ \ingroup qmlbasictypes
+
+ \brief An integer is a whole number, for example 0, 10, or -20.
+
+ An integer is a whole number, e.g. 0, 10, or -20. The possible
+ \c int values range from around -2000000000 to around
+ 2000000000, although most elements will only accept a reduced
+ range (which they mention in their documentation).
+
+ Example:
+ \qml
+ Item { width: 100; height: 200 }
+ \endqml
+
+ \sa {QML Basic Types}
+ * /
+ \endcode
+
+ QDoc outputs this as \l{http://qt-project.org/doc/qt-4.7/qml-int.html}
+ {qml-int.html}.
+
+ \target qmlclass-command
+ \section1 \\qmlclass
+
+ This command is deprecated. Use \l{qmltype-command} {\\qmltype}
+ instead.
+
+ The \\qmlclass command is for documenting a QML type that is
+ instantiated by a C++ class. The command has two arguments. The
+ first argument is the name of the QML type. The second argument
+ is the name of the C++ class that instantiates the QML type.
+
+ \code
+ / *!
+ \qmlclass Transform QGraphicsTransform
+ \ingroup qml-transform-elements
+ \since 4.7
+ \brief Provides a way of building advanced transformations on Items.
+
+ The Transform element is a base type which cannot be
+ instantiated directly. The following concrete Transform types
+ are available:
+
+ \list
+ \li \l Rotation
+ \li \l Scale
+ \li \l Translate
+ \endlist
+
+ The Transform elements let you create and control advanced
+ transformations that can be configured independently using
+ specialized properties.
+
+ You can assign any number of Transform elements to an \l
+ Item. Each Transform is applied in order, one at a time.
+
+ * /
+ \endcode
+
+ This example generates the
+ \l {http://qt-project.org/doc/qt-4.7/qml-transform.html} {QML Transform}
+ page. The \\qmlclass comment should include the \l
+ {since-command} {\\since} command, because all QML types are
+ new. It should also include the \l{brief-command} {\\brief}
+ command. If a type is a member of a group of QML
+ types, it should also include one or more \l{ingroup-command}
+ {\\ingroup} commands.
+
+ \target qmlmethod-command
+ \section1 \\qmlmethod
+
+ The \\qmlmethod command is for documenting a QML method. The
+ argument is the complete method signature, including return
+ type and parameter names and types.
+
+ \code
+ / *!
+ \qmlmethod void TextInput::select(int start, int end)
+
+ Causes the text from \a start to \a end to be selected.
+
+ If either start or end is out of range, the selection is not changed.
+
+ After having called this, selectionStart will become the lesser, and
+ selectionEnd the greater (regardless of the order passed to this method).
+
+ \sa selectionStart, selectionEnd
+ * /
+ \endcode
+
+ QDoc includes this documentation on the element reference page for the
+ \l{http://qt-project.org/doc/qt-4.7/qml-textinput.html#select-method}
+ {TextInput} element.
+
+ \target qmltype-command
+ \section1 \\qmltype
+
+ The \\qmltype command is for documenting a QML type. The command
+ has one argument, which is the name of the QML type.
+
+ If the QML type is instantiated by a C++ class, that class must be
+ specified using the \l{instantiates-command} {\\instantiates}
+ context command.
+
+ \code
+ / *!
+ \qmltype Transform
+ \instantiates QGraphicsTransform
+ \ingroup qml-transform-elements
+ \since 4.7
+ \brief The Transform elements provide a way to build
+ advanced transformations on Items.
+
+ The Transform element is a base type which cannot be
+ instantiated directly. The concrete Transform types are:
+
+ \list
+ \li \l Rotation
+ \li \l Scale
+ \li \l Translate
+ \endlist
+
+ The Transform elements let you create and control advanced
+ transformations that can be configured independently using
+ specialized properties.
+
+ You can assign any number of Transform elements to an \l
+ Item. Each Transform is applied in order, one at a time.
+
+ * /
+ \endcode
+
+ The example generates the \l
+ {http://qt-project.org/doc/qt-4.7/qml-transform.html} {QML Transform}
+ page. The \e{\\qmltype} comment includes \l{instantiates-command}
+ {\\instantiates} to specify that a Transform is instantiated by
+ the C++ class QGraphicsTransform. A \\qmltype comment should
+ always include a \l {since-command} {\\since} command, because all
+ QML types are new. It should also include a \l{brief-command}
+ {\\brief} description. If a QML type is a member of a QML type group,
+ the \\qmltype comment should include one or more \l{ingroup-command}
+ {\\ingroup} commands.
+
+
+ \target qmlproperty-command
+ \section1 \\qmlproperty
+
+ The \\qmlproperty command is for documenting a QML property. The
+ argument is the rest of the line. The argument text should be the
+ property type, followed by the QML type name, the \c{::}
+ qualifier, and finally the property name. If we have a QML
+ property named \c x in QML type \c Translate, and the property
+ has type \c {real}, the \\qmlproperty for it would look like this:
+
+ \code
+ / *!
+ \qmlproperty real Translate::x
+
+ The translation along the X axis.
+ * /
+ \endcode
+
+ QDoc includes this QML property on the QML reference page for the
+ \l {http://qt-project.org/doc/qt-4.7/qml-translate.html} {Translate}
+ element.
+
+ \target qmlsignal-command
+ \section1 \\qmlsignal
+
+ The \\qmlsignal command is for documenting a QML signal.
+ The argument is the rest of the line. The arguments should be: the QML type
+ where the signal is declared, the \c{::} qualifier, and finally the signal
+ name. If we have a QML signal named \c clicked(), the documentation for it
+ would look like this:
+
+ \code
+ / *!
+ \qmlsignal UIComponents::Button::clicked()
+ This signal is emitted when the user clicks the button. A click is defined
+ as a press followed by a release. The corresponding handler is
+ \c onClicked.
+ * /
+ \endcode
+
+ QDoc includes this documentation on the QML reference page for the
+ \l{http://qt-project.org/doc/qt-4.7/qml-mousearea.html#onEntered-signal}
+ {MouseArea} element.
+
+ \target qmlmodule-command
+ \section1 \\qmlmodule
+
+ Insert the \c{\\qmlmodule} command to create a \c QML module page. A QML
+ module is a collection of QML types or any related material. This
+ command is similar to the \l{group-command}.
+
+ A QML class may belong to a module by inserting the
+ \l{inqmlmodule-command}{\\inqmlmodule} command as a topic command.
+ Every member of a group must be linked to using the module name and two
+ colons (\c{::}).
+
+ \code
+ \beginqdoc
+ A link to the TabWidget of the UI Component is \l {UIComponent::TabWidget}.
+ \endqdoc
+ \endcode
+
+ QDoc will generate a page for the module with a listing of the members
+ of the module.
+
+ \code
+ \qmlmodule ClickableComponents
+
+ This is a list of the Clickable Components set. A Clickable component
+ responds to a \c clicked() event.
+ \endcode
+
+ The \l{componentset}{UIComponents} example demonstrates proper usage of
+ QDoc commands to document QML types and QML modules.
+
+ \target inqmlmodule-command
+ \section1 \\inqmlmodule
+
+ A QML class may belong to a \l{qmlmodule-command}{QML module} by inserting
+ the \l{inqmlmodule-command}{\\inqmlmodule} command as a topic command.
+ Every member of a group must be linked to using the module name and two
+ colons (\c{::}).
+
+ \code
+ \qmltype ClickableButton
+ \inqmlmodule ClickableComponents
+
+ A clickable button that responds to the \c click() event.
+ \endcode
+
+ To link to the \c ClickableButton, use the
+ \c{\l ClickableComponents::ClickableButton} format.
+
+ The \l{componentset}{UIComponents} example demonstrates proper usage of
+ QDoc commands to document QML types and QML modules.
+
+ \target instantiates-command
+ \section1 \\instantiates
+
+ The \\instantiates command is used in the \l{qmltype-command} {QML
+ type} comment of an elemental QML type to specify the name of the
+ C++ class that instantiates the QML type.
+
+ If the QML type is not instantiated by a C++ class, this command
+ is not used.
+
+ \code
+ / *!
+ \qmltype Transform
+ \instantiates QGraphicsTransform
+ \ingroup qml-transform-elements
+ \since 4.7
+ \brief Provides elements provide a way to build
+ advanced transformations on Items.
+
+ The Transform element is a base type which cannot be
+ instantiated directly.
+ * /
+ \endcode
+
+ The example generates the \l
+ {http://qt-project.org/doc/qt-4.7/qml-transform.html} {QML Transform}
+ page. The \e{\\qmltype} comment includes \l{instantiates-command}
+ {\\instantiates} to specify that a Transform is instantiated by
+ the C++ class QGraphicsTransform. A \\qmltype comment should
+
+ \target typedef-command
+ \section1 \\typedef
+
+ The \\typedef command is for documenting a C++ typedef. The
+ argument is the name of the typedef. The documentation for
+ the typedef will be included in the reference documentation
+ for the class, namespace, or header file in which the typedef
+ is declared. To relate the \\typedef to a class, namespace, or
+ header file, the \\typedef comment must contain a
+ \l {relates-command} {\\relates} command.
+
+ \code
+ / *!
+ \typedef QObjectList
+ \relates QObject
+
+ Synonym for QList<QObject>.
+ * /
+ \endcode
+
+ QDoc includes this in \c {qobject.html} as:
+
+ \quotation
+ \raw HTML
+ <h3>typedef QObjectList</h3>
+ \endraw
+
+ Synonym for QList<QObject>.
+ \endquotation
+
+ Another, although more rare, example:
+
+ \code
+ / *!
+ \typedef QMsgHandler
+ \relates QtGlobal
+
+ This is a typedef for a pointer to a function with the
+ following signature:
+
+ \code
+ void myMsgHandler(QtMsgType, const char *);
+ \ endcode
+
+ \sa QtMsgType, qInstallMsgHandler()
+ * /
+ \endcode
+
+ QDoc includes this in \c {qtglobal.html} as:
+
+ \quotation
+ \raw HTML
+ <h3>typedef QtMsgHandler</h3>
+ \endraw
+
+ This is a typedef for a pointer to a function with the
+ following signature:
+
+ \raw HTML
+ <tt>
+ <pre> void myMsgHandler(QtMsgType, const char *);</pre>
+ </tt>
+ \endraw
+
+ See also QtMsgType and qInstallMsgHandler().
+ \endquotation
+
+ Other typedefs are located on the reference page for the class
+ that defines them.
+
+ \code
+ / *!
+ \typedef QLinkedList::Iterator
+
+ Qt-style synonym for QList::iterator.
+ * /
+ \endcode
+
+ QDoc includes this one on the reference page for class QLinkedList as:
+
+ \quotation
+ \raw HTML
+ <h3>typedef QLinkedList::Iterator</h3>
+ \endraw
+
+ Qt-style synonym for QList::iterator.
+ \endquotation
+
+ \target variable-command
+ \section1 \\variable
+
+ The \\variable command is for documenting a class member variable
+ or a constant. The argument is the variable or constant name. The
+ \\variable command comment includes a \l {brief-command} {\\brief}
+ command. QDoc generates the documentation based on the text from
+ \\brief command.
+
+ The documentation will be located in the in the associated class,
+ header file, or namespace documentation.
+
+ In case of a member variable:
+
+ \code
+ / *!
+ \variable QStyleOption::palette
+ \brief The palette that should be used when painting
+ the control
+ * /
+ \endcode
+
+ QDoc includes this in qstyleoption.html as:
+
+ \quotation
+ \raw HTML
+ <h3>
+ <a href="http://qt-project.org/doc/qt-5.0/qtgui/qpalette.html">
+ QPalette
+ </a>
+ QStyleOption::palette
+ </h3>
+ \endraw
+
+ This variable holds the palette that should be used
+ when painting the control.
+ \endquotation
+
+ You can also document constants with the \\variable command. For
+ example, suppose you have the \c Type and \c UserType constants in
+ the QTreeWidgetItem class:
+
+ \code
+ enum { Type = 0, UserType = 1000 };
+ \endcode
+
+ For these, the \\variable command can be used this way:
+
+ \code
+ / *!
+ \variable QTreeWidgetItem::Type
+
+ The default type for tree widget items.
+
+ \sa UserType, type()
+ * /
+ \endcode
+ \code
+ / *!
+ \variable QTreeWidgetItem::UserType
+
+ The minimum value for custom types. Values below
+ UserType are reserved by Qt.
+
+ \sa Type, type()
+ * /
+ \endcode
+
+ QDoc includes these in qtreewidget.html as:
+
+ \quotation
+ \raw HTML
+ <h3>
+ const int QTreeWidgetItem::Type
+ </h3>
+ \endraw
+
+ The default type for tree widget items.
+
+ See also \l {QTreeWidgetItem::UserType} {UserType} and \l
+ {QTreeWidgetItem::type()} {type()}.
+
+ \raw HTML
+ <h3>
+ const int QTreeWidgetItem::UserType
+ </h3>
+ \endraw
+
+ The minimum value for custom types. Values below
+ UserType are reserved by Qt.
+
+ See also \l {QTreeWidgetItem::Type} {Type} and
+ \l{QTreeWidgetItem::type()} {type()}.
+
+ \endquotation
+*/
diff --git a/src/tools/qdoc/doc/qdoc-manual.qdoc b/src/tools/qdoc/doc/qdoc-manual.qdoc
index 010b2f79ec..485faba70f 100644
--- a/src/tools/qdoc/doc/qdoc-manual.qdoc
+++ b/src/tools/qdoc/doc/qdoc-manual.qdoc
@@ -74,8723 +74,4 @@
*/
-/*!
- \page 01-qdoc-manual.html
- \contentspage QDoc Manual
- \previouspage QDoc Manual
- \nextpage Command Index
-
- \title Introduction to QDoc
-
- QDoc is a tool used by Qt Developers to generate documentation for
- software projects. It works by extracting \e {QDoc comments} from
- project source files and then formatting these comments as HTML
- pages or DITA XML documents. QDoc finds QDoc comments in \c
- {.cpp} files and in \c {.qdoc} files. QDoc does not look for QDoc
- comments in \c {.h} files. A QDoc comment always begins with an
- exclamation mark (\b{!})). For example:
-
- \code
- / *!
- \class QObject
- \brief The QObject class is the base class of all Qt objects.
-
- \ingroup objectmodel
-
- \reentrant
-
- QObject is the heart of the Qt \l{Object Model}. The
- central feature in this model is a very powerful mechanism
- for seamless object communication called \l{signals and
- slots}. You can connect a signal to a slot with connect()
- and destroy the connection with disconnect(). To avoid
- never ending notification loops you can temporarily block
- signals with blockSignals(). The protected functions
- connectNotify() and disconnectNotify() make it possible to
- track connections.
-
- QObjects organize themselves in \l {Object Trees &
- Ownership} {object trees}. When you create a QObject with
- another object as parent, the object will automatically
- add itself to the parent's \c children() list. The parent
- takes ownership of the object. It will automatically
- delete its children in its destructor. You can look for an
- object by name and optionally type using findChild() or
- findChildren().
-
- Every object has an objectName() and its class name can be
- found via the corresponding metaObject() (see
- QMetaObject::className()). You can determine whether the
- object's class inherits another class in the QObject
- inheritance hierarchy by using the \c inherits() function.
-
- ....
- * /
- \endcode
-
- From the QDoc comment above, QDoc generates the HTML page
- \l {http://qt-project.org/doc/qt-5.0/qtcore/qobject.html#details}
- {QObject Class Reference}.
-
- 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 current name of the QDoc program is \c {qdoc}. To run qdoc
- from the command line, give it the name of a configuration file:
-
- \quotation
- \c {$ ../../bin/qdoc ./config.qdocconf}
- \endquotation
-
- QDoc recognizes the \c {.qdocconf} suffix as a \l{The QDoc
- Configuration File} {QDoc configuration file}. The configuration
- file is where you tell QDoc where to find the project source
- files, header files, and \c {.qdoc} files. It is also where you
- tell QDoc what kind of output to generate (HTML, DITA XML,...),
- and where to put the generated documentation. The configuration
- file also contains other information for QDoc.
-
- See \l{The QDoc Configuration File} for instructions on how to
- set up a QDoc configuration file.
-
- \section1 How QDoc works
-
- QDoc begins by reading the configuration file you specified on the
- command line. It stores all the variables from the configuration
- file for later use. One of the first variables it uses is \c
- {outputformats}. This variable tells QDoc which output generators
- it will run. The default value is \e {HTML}, so if you don't set
- \c {outputformats} in your configuration file, QDoc will generate
- HTML output. That's usually what you will want anyway, but you can
- also specify \e {DITAXML} to get DITA XML output instead.
-
- Next, QDoc uses the values of the
- \l {22-qdoc-configuration-generalvariables.html#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.
-*/
-
-/*!
- \page 03-qdoc-commands-markup.html
- \contentspage QDoc Manual
- \previouspage Naming Things
- \nextpage Text Markup
-
- \title Markup Commands
-
- The markup commands indicate the generated documentation's visual
- appearance and logical structure.
-
- \list
- \li \l {04-qdoc-commands-textmarkup.html#a-command} {\\a}
- \li \l {11-qdoc-commands-specialcontent.html#abstract-command} {\\abstract}
- \li \l {12-0-qdoc-commands-miscellaneous.html#annotatedlist-command} {\\annotatedlist}
- \li \l {04-qdoc-commands-textmarkup.html#b-command} {\\b} \span {class="newStuff"} {(new 5/3/2012)}
- \li \l {04-qdoc-commands-textmarkup.html#b-command} {\\bold} {(deprecated, use \\b)}
- \li \l {11-qdoc-commands-specialcontent.html#brief-command} {\\brief}
- \li \l {04-qdoc-commands-textmarkup.html#c-command} {\\c}
- \li \l {09-qdoc-commands-includingimages.html#caption-command} {\\caption}
- \li \l {05-qdoc-commands-documentstructure.html#chapter-command} {\\chapter}
- \li \l {06-qdoc-commands-includecodeinline.html#code-command} {\\code}
- \li \l {07-0-qdoc-commands-includingexternalcode.html#codeline-command} {\\codeline}
- \li \l {04-qdoc-commands-textmarkup.html#div-command} {\\div}
- \li \l {07-0-qdoc-commands-includingexternalcode.html#dots-command} {\\dots}
- \li \l {04-qdoc-commands-textmarkup.html#e-command} {\\e} \span {class="newStuff"} {(new 5/3/2012)}
- \li \l {12-0-qdoc-commands-miscellaneous.html#else-command} {\\else}
- \li \l {12-0-qdoc-commands-miscellaneous.html#endif-command} {\\endif}
- \li \l {11-qdoc-commands-specialcontent.html#footnote-command} {\\footnote}
- \li \l {12-0-qdoc-commands-miscellaneous.html#generatelist-command} {\\generatelist}
- \li \l {10-qdoc-commands-tablesandlists.html#header-command} {\\header}
- \li \l {04-qdoc-commands-textmarkup.html#e-command} {\\i} \span {class="newStuff"} {(deprecated, use \\e)}
- \li \l {12-0-qdoc-commands-miscellaneous.html#if-command} {\\if}
- \li \l {09-qdoc-commands-includingimages.html#image-command} {\\image}
- \li \l {12-0-qdoc-commands-miscellaneous.html#include-command} {\\include}
- \li \l {12-0-qdoc-commands-miscellaneous.html#include-command} {\\input}
- \li \l {09-qdoc-commands-includingimages.html#inlineimage-command} {\\inlineimage}
- \li \l {08-qdoc-commands-creatinglinks.html#keyword-command} {\\keyword}
- \li \l {08-qdoc-commands-creatinglinks.html#l-command} {\\l}
- \li \l {11-qdoc-commands-specialcontent.html#legalese-command} {\\legalese}
- \li \l {10-qdoc-commands-tablesandlists.html#li-command} {\\li} \span {class="newStuff"} {(new 5/3/2012)}
- \li \l {10-qdoc-commands-tablesandlists.html#list-command} {\\list}
- \li \l {12-0-qdoc-commands-miscellaneous.html#meta-command} {\\meta}
- \li \l {06-qdoc-commands-includecodeinline.html#newcode-command} {\\newcode}
- \li \l {10-qdoc-commands-tablesandlists.html#li-command} {\\o} \span {class="newStuff"} {(deprecated, use \\li)}
- \li \l {11-qdoc-commands-specialcontent.html#note-command} {\\note}
- \li \l {06-qdoc-commands-includecodeinline.html#oldcode-command} {\\oldcode}
- \li \l {12-0-qdoc-commands-miscellaneous.html#omit-command} {\\omit}
- \li \l {05-qdoc-commands-documentstructure.html#part-command} {\\part}
- \li \l {07-0-qdoc-commands-includingexternalcode.html#printline-command} {\\printline}
- \li \l {07-0-qdoc-commands-includingexternalcode.html#printto-command} {\\printto}
- \li \l {07-0-qdoc-commands-includingexternalcode.html#printuntil-command} {\\printuntil}
- \li \l {11-qdoc-commands-specialcontent.html#quotation-command} {\\quotation}
- \li \l {07-0-qdoc-commands-includingexternalcode.html#quotefile-command} {\\quotefile}
- \li \l {07-0-qdoc-commands-includingexternalcode.html#quotefromfile-command} {\\quotefromfile}
- \li \l {12-0-qdoc-commands-miscellaneous.html#raw-command} {\\raw}
- \li \l {10-qdoc-commands-tablesandlists.html#row-command} {\\row}
- \li \l {08-qdoc-commands-creatinglinks.html#sa-command} {\\sa}
- \li \l {05-qdoc-commands-documentstructure.html#sectionOne-command} {\\section1}
- \li \l {05-qdoc-commands-documentstructure.html#sectionTwo-command} {\\section2}
- \li \l {05-qdoc-commands-documentstructure.html#sectionThree-command} {\\section3}
- \li \l {05-qdoc-commands-documentstructure.html#sectionFour-command} {\\section4}
- \li \l {07-0-qdoc-commands-includingexternalcode.html#skipline-command} {\\skipline}
- \li \l {07-0-qdoc-commands-includingexternalcode.html#skipto-command} {\\skipto}
- \li \l {07-0-qdoc-commands-includingexternalcode.html#skipuntil-command} {\\skipuntil}
- \li \l {07-0-qdoc-commands-includingexternalcode.html#snippet-command} {\\snippet}
- \li \l {04-qdoc-commands-textmarkup.html#span-command} {\\span}
- \li \l {04-qdoc-commands-textmarkup.html#sub-command} {\\sub}
- \li \l {04-qdoc-commands-textmarkup.html#sup-command} {\\sup}
- \li \l {10-qdoc-commands-tablesandlists.html#table-command} {\\table}
- \li \l {11-qdoc-commands-specialcontent.html#tableofcontents-command} {\\tableofcontents}
- \li \l {08-qdoc-commands-creatinglinks.html#target-command} {\\target}
- \li \l {04-qdoc-commands-textmarkup.html#tt-command} {\\tt}
- \li \l {04-qdoc-commands-textmarkup.html#uicontrol-command} {\\uicontrol} {(new 25/3/2012)}
- \li \l {04-qdoc-commands-textmarkup.html#underline-command} {\\underline}
- \li \l {12-0-qdoc-commands-miscellaneous.html#raw-command} {\\unicode}
- \li \l {11-qdoc-commands-specialcontent.html#warning-command} {\\warning}
- \li \l {04-qdoc-commands-textmarkup.html#backslash-command} {\\\\}
- \endlist
-*/
-
-/*!
- \page 04-qdoc-commands-textmarkup.html
- \contentspage QDoc Manual
- \previouspage Markup Commands
- \nextpage Document Structure
-
- \title Text Markup
-
- The text formatting commands indicate how text is to be rendered.
-
- \target a-command
- \section1 \\a (parameter marker)
-
- The \\a command tells QDoc the next word is a formal parameter name.
-
- A warning is emitted when a formal parameter is not documented or
- is misspelled, so when you document a function you should mention
- each formal parameter by name in the function description,
- preceded by the \\a command. The parameter name is then rendered
- in italics.
-
- \code
- / *!
- Constructs a line edit containing the text
- \a contents. The \a parent parameter is sent
- to the QWidget constructor.
- * /
-
- QLineEdit::QLineEdit(const QString &contents, QWidget *parent) :QWidget(parent)
- {
- ...
- }
-
- \endcode
-
- QDoc renders this as:
-
- \quotation
- \b {QLineEdit::QLineEdit ( const QString &
- contents, QWidget *parent )}
-
- Constructs a line edit containing the text \a contents.
- The \a parent parameter is sent to the QWidget constructor.
- \endquotation
-
- The formal parameter name may be enclosed between curly brackets,
- but that isn't required.
-
- \target c-command
- \section1 \\c (code font)
-
- The \\c command is used for rendering variable names, user-defined
- class names, and C++ keywords (for example, \c int and \c for) in the code
- font.
-
- The command renders its argument using a monospace font. For
- example:
-
- \code
- / *!
- The \c AnalogClock class provides a clock widget with hour
- and minute hands that is automatically updated every
- few seconds.
- * /
- \endcode
-
- QDoc renders this as:
-
- \quotation
- The \c AnalogClock class provides a clock widget with hour
- and minute hands, which are automatically updated every
- few seconds.
- \endquotation
-
- If the text to be rendered in the code font contains spaces, enclose the
- entire text in curly brackets.
-
- \code
- \c {QLineEdit::QLineEdit(const QString &contents, QWidget *parent) :QWidget(parent)}
- \endcode
-
- QDoc renders this as:
-
- \quotation
- \c {QLineEdit::QLineEdit(const QString &contents, QWidget *parent) :QWidget(parent)}
- \endquotation
-
- The \\c command accepts the special character \c \ within its
- argument, which renders it as a normal character. So if you want
- to use nested commands, you must use the \l {tt-command} {teletype
- (\\tt)} command instead.
-
- See also \l {tt-command} {\\tt} and \l {code-command} {\\code}.
-
- \target div-command
- \section1 \\div
-
- The \\div and \\enddiv commands delimit a large or small block of
- text (which may include other QDoc commands) to which special
- formatting attributes should be applied.
-
- An argument must be provided in curly braces, as in the qdoc
- comment shown below. The argument is not interpreted but is used
- as attribute(s) of the tag that is output by qdoc.
-
- For example, we might want to render an inline image so that it
- floats to the right of the current block of text:
-
- \code
- / *!
- \div {class="float-right"}
- \inlineimage qml-column.png
- \enddiv
-
- * /
- \endcode
-
- If qdoc is generating HTML, it will translate these commands to:
-
- \code
- <div class="float-right"><p><img src="images/qml-column.png" /></p></div>
- \endcode
-
- For HTML, the attribute value \e {float-right} then will refer to
- a clause in the style.css file, which in this case could be:
-
- \code
- div.float-right
- {
- float: right; margin-left: 2em
- }
- \endcode
-
- If qdoc is generating DITA XML, it will translate the commands to:
-
- \code
- <sectiondiv outputclass="float-right">
- <p>
- <fig>
- <image href="images/qml-column.png" placement="inline"/>
- </fig>
- </p>
- </sectiondiv>
- \endcode
-
- Your DITA XML publishing program must then recognize the \e
- {outputclass} attribute value.
-
- \note Note that the \b {\\div} command can be nested.
-
- Below you can find an example taken from the index.qdoc file used to
- generate index.html for Qt 4.7:
-
- \code
- \div {class="indexbox guide"}
- \div {class="heading"}
- Qt Developer Guide
- \enddiv
- \div {class="indexboxcont indexboxbar"}
- \div {class="section indexIcon"} \emptyspan
- \enddiv
- \div {class="section"}
- Qt is a cross-platform application and UI
- framework. Using Qt, you can write web-enabled
- applications once and deploy them across desktop,
- mobile and embedded operating systems without
- rewriting the source code.
- \enddiv
- \div {class="section sectionlist"}
- \list
- \li \l{Getting Started Guides} {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 \l{Getting Started Guides} {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
-
- When generating DITA XML, qdoc outputs the nested \e {div} commands as:
-
- \code
- <sectiondiv outputclass="indexbox guide">
- <sectiondiv outputclass="heading">
- <p>Qt Developer Guide</p>
- </sectiondiv>
- <sectiondiv outputclass="indexboxcont indexboxbar">
- <sectiondiv outputclass="section indexIcon"/>
- <sectiondiv outputclass="section">
- <p>Qt is a cross-platform application and UI
- framework. Using Qt, you can write
- web-enabled applications once and deploy
- them across desktop, mobile and embedded
- operating systems without rewriting the
- source code.
- </p>
- </sectiondiv>
- <sectiondiv outputclass="section sectionlist">
- <ul>
- <li>
- <xref href="gettingstarted.xml#id-606ee7a8-219b-47b7-8f94-91bc8c76e54c">Getting started</xref>
- </li>
- <li>
- <xref href="installation.xml#id-075c20e2-aa1e-4f88-a316-a46517e50443">Installation</xref>
- </li>
- <li>
- <xref href="how-to-learn-qt.xml#id-49f509b5-52f9-4cd9-9921-74217b9a5182">How to learn Qt</xref>
- </li>
- <li>
- <xref href="tutorials.xml#id-a737f955-a904-455f-b4aa-0dc69ed5a64f">Tutorials</xref>
- </li>
- <li>
- <xref href="all-examples.xml#id-98d95159-d65b-4706-b08f-13d80080448d">Examples</xref>
- </li>
- <li>
- <xref href="qt4-7-intro.xml#id-519ae0e3-4242-4c2a-b2be-e05d1e95f177">What's new in Qt 4.7</xref>
- </li>
- </ul>
- </sectiondiv>
- </sectiondiv>
- </sectiondiv>
- \endcode
-
- Your DITA XML publishing program must recognize the values of the
- \e {outputclass} attribute.
-
- See also \l {span-command} {\\span}.
-
- \target span -command
- \section1 \\span
-
- The \\span command applies special formatting to a small block of text.
-
- Two arguments must be provided, each argument in curly braces, as
- shown in the QDoc comment below. The first argument is not
- interpreted, but specifies the formatting attribute(s) of the tag
- output by QDoc. The second argument is the text to be rendered with
- the special formatting attributes.
-
- For example, we might want to render the first word of each
- element in a numeric list in blue.
-
- \code
- / *!
- Global variables with complex types:
- \list 1
- \li \span {class="variableName"} {mutableComplex1} in globals.cpp at line 14
- \li \span {class="variableName"} {mutableComplex2} in globals.cpp at line 15
- \li \span {class="variableName"} {constComplex1} in globals.cpp at line 16
- \li \span {class="variableName"} {constComplex2} in globals.cpp at line 17
- \endlist
- * /
- \endcode
-
- Class \e {variableName} refers to a clause in your style.css.
-
- \code
- .variableName
- {
- font-family: courier;
- color: blue
- }
- \endcode
-
- Using the \e {variableName} clause shown above, the example is rendered as:
-
- Global variables with complex types:
- \list 1
- \li \span {class="variableName"} {mutableComplex1} in globals.cpp at line 14
- \li \span {class="variableName"} {mutableComplex2} in globals.cpp at line 15
- \li \span {class="variableName"} {constComplex1} in globals.cpp at line 16
- \li \span {class="variableName"} {constComplex2} in globals.cpp at line 17
- \endlist
-
- \note The \b span command does not cause a new paragraph to be
- started.
-
- See also \l {div-command} {\\div}.
-
- \target tt-command
- \section1 \\tt (teletype font)
-
- The \\tt command renders its argument in a monospace font. This
- command behaves just like the \l {c-command} {\\c} command, except
- that \\tt allows you to nest QDoc commands within the argument
- (e.g. \l {e-command} {\\e}, \l {b-command} {\\b} and \l
- {underline-command} {\\underline}).
-
- \code
- / *!
- After having populated the main container with
- child widgets, \c setupUi() scans the main container's list of
- slots for names with the form
- \tt{on_\e{objectName}_\e{signalName}().}
- * /
- \endcode
-
- QDoc renders this as:
-
- \quotation
- After having populated the main container with
- child widgets, \c setupUi() scans the main container's list of
- slots for names with the form
- \tt{on_\e{objectName}_\e{signalName}().}
- \endquotation
-
- If the text to be rendered in the code font contains spaces, enclose the
- entire text in curly brackets.
-
- \code
- \tt {QLineEdit::QLineEdit(const QString &contents, QWidget *parent) :QWidget(parent)}
- \endcode
-
- QDoc renders this as:
-
- \quotation
- \tt {QLineEdit::QLineEdit(const QString &contents, QWidget *parent) :QWidget(parent)}
- \endquotation
-
- See also \l {c-command} {\\c}.
-
- \target b-command
- \section1 \\b
-
- The \\b command renders its argument in bold font. This command used
- to be called \\bold.
-
- \code
- / *!
- This is regular text; \b {this text is
- rendered using the \\b command}.
- * /
- \endcode
-
- QDoc renders this as:
-
- \quotation
- This is regular text; \b {this text is rendered using
- the \\b command}.
- \endquotation
-
- \target e-command
- \section1 \\e (emphasis, italics) \span {class="newStuff"} {(new 5/3/2012)}
-
- The \\e command renders its argument in a special font, normally italics. This
- command used to be called \\i, which is now deprecated. Use \e for italics.
-
- If the argument contains spaces or other punctuation, enclose the
- argument in curly brackets.
-
- \code
- / *!
- Here, we render \e {a few words} in italics.
- * /
- \endcode
-
- QDoc renders this as:
-
- \quotation
- Here, we render \e {a few words} in italics.
- \endquotation
-
- If you want to use other QDoc commands within an argument that
- contains spaces, you always need to enclose the argument in
- braces. But QDoc is smart enough to count parentheses [3], so you
- don't need braces in cases like this:
-
- \code
- / *!
- An argument can sometimes contain whitespaces,
- for example: \e QPushButton(tr("A Brand New Button"))
- * /
- \endcode
-
- QDoc renders this as:
-
- \quotation
- An argument can sometimes contain whitespaces,
- for example: \e QPushButton(tr("A Brand New Button"))
- \endquotation
-
- Finally, trailing punctuation is not included in an argument [4],
- nor is "'s" [5]
-
- \raw HTML
- <table align="center" cellpadding="2"
- cellspacing="1" border="0">
- <tr valign="top" bgcolor="#a2c511">
- <th></th>
- <th>QDoc Syntax</th>
- <th>Generated Documentation</th>
- </tr>
-
- <tr valign="top" bgcolor="#d0d0d0">
- <td>1</td>
- <td>A variation of a command button is a \e menu
- button.</td>
- <td>A variation of a command button is a <i>menu</i>
- button.</td>
- </tr>
-
- <tr valign="top" bgcolor="#c0c0c0">
- <td>2</td>
- <td>The QPushButton widget provides a
- \e {command button}.</td>
- <td>The QPushButton widget provides a
- <i>command button</i>.</td>
- </tr>
-
- <tr valign="top" bgcolor="#d0d0d0">
- <td>3</td>
- <td>Another class of buttons are option buttons
- \e (see QRadioButton).</td>
- <td>Another class of buttons are option buttons
- <i> (see QRadioButton)</i>.</td>
- </tr>
-
- <tr valign="top" bgcolor="#c0c0c0">
- <td>4</td>
- <td>A push button emits the signal \e clicked().</td>
- <td>A push button emits the signal <i>clicked</i>().</td>
- </tr>
-
- <tr valign="top" bgcolor="#d0d0d0">
- <td>5</td>
- <td>The \e QPushButton's checked property is
- false by default.</td>
- <td>The <i>QPushButton</i>'s checked property is
- false by default.</td>
- </tr>
-
- </table>
- \endraw
-
- \target sub-command
- \section1 \\sub
-
- The \\sub command renders its argument lower than the baseline of
- the regular text, using a smaller font.
-
- \code
- / *!
- Definition (Range): Consider the sequence
- {x\sub n}\sub {n > 1} . The set
-
- {x\sub 2, x\sub 3, x\sub 4, ...} = {x\sub n ; n = 2, 3, 4, ...}
-
- is called the range of the sequence.
- * /
- \endcode
-
- QDoc renders this as:
-
- \quotation
- Definition (Range): Consider the sequence
- {x\sub n}\sub {n > 1} . The set
-
- {x\sub 2, x\sub 3, x\sub 4, ...} = {x\sub n ; n = 2, 3, 4, ...}
-
- is called the range of the sequence.
- \endquotation
-
- If the argument contains spaces or other punctuation, enclose the
- argument in curly brackets.
-
- \target sup-command
- \section1 \\sup
-
- The \\sup command renders its argument higher than
- the baseline of the regular text, using a smaller font.
-
- \code
- / *!
- The series
-
- 1 + a + a\sup 2 + a\sup 3 + a\sup 4 + ...
-
- is called the \i {geometric series}.
- * /
- \endcode
-
- QDoc renders this as:
-
- \quotation
- The series
-
- 1 + a + a\sup 2 + a\sup 3 + a\sup 4 + ...
-
- is called the \e {geometric series}.
- \endquotation
-
- If the argument contains spaces or other punctuation, enclose the
- argument in curly brackets.
-
- \target uicontrol-command
- \section1 \\uicontrol
-
- The \\uicontrol command is used to mark content as being used for UI
- control elements. When using HTML, the output is rendered in bold.
- When using DITA XML the content is enclosed in a \c{uicontrol} tag.
-
- \sa \\b
-
- \target underline-command
- \section1 \\underline
-
- The \\underline command renders its argument underlined.
-
- \code
- / *!
- The \underline {F}ile menu gives the users the possibility
- to edit an existing file, or save a new or modified
- file, and exit the application.
- * /
- \endcode
-
- QDoc renders this as:
-
- \quotation
- The \underline {F}ile menu gives the users the possibility
- to edit an existing file, or save a new or modified
- file, and exit the application.
- \endquotation
-
- If the argument contains spaces or other punctuation, enclose the
- argument in curly brackets.
-
- \target backslash-command
- \section1 \\\\ (double backslash)
-
- The \\\\ command expands to a double backslash.
-
- QDoc commands always start with a single backslash. To display a
- single backslash in the text you need to type two backslashes. If
- you want to display two backslashes, you need to type four.
-
- \code
- / *!
- The \\\\ command is useful if you want a
- backslash to appear verbatim, for example,
- writing C:\\windows\\home\\.
- * /
- \endcode
-
- QDoc renders this as:
-
- \quotation
- The \\\\ command is useful if you want a
- backslash to appear verbatim, for example,
- writing C:\\windows\\home\\.
- \endquotation
-
- However, if you want your text to appear in a monospace font as
- well, you can use the \l {c-command} {\\c} command instead, which
- accepts and renders the backslash as any other character. For
- example:
-
- \code
- / *!
- The \\c command is useful if you want a
- backslash to appear verbatim, and the word
- that contains it written in a monospace font,
- like this: \c {C:\windows\home\}.
- * /
- \endcode
-
- QDoc renders this as:
-
- \quotation
- The \\c command is useful if you want a
- backslash to appear verbatim, and the word
- that contains it written in a monospace font,
- like this: \c {C:\windows\home\}.
- \endquotation
-
-*/
-
-/*!
- \page 05-qdoc-commands-documentstructure.html
- \previouspage Text Markup
- \contentspage QDoc Manual
- \nextpage Including Code Inline
-
- \title Document Structure
-
- The document structuring commands are for dividing your document
- into sections. QDoc supports six kinds of sections: \c \part, \c
- \chapter, \c \section1, \c \section2, \c \section3, and \c
- \section4. The \c \section1..4 commands are the most useful. They
- correspond to the traditional section, subsection, etc used in
- outlining.
-
- \target part-command
- \section1 \\part
-
- The \\part command is intended for use in a large document, like a
- book.
-
- In general a document structuring command considers everything
- that follows it until the first line break as its argument. The
- argument is rendered as the unit's title. If the title needs to be
- spanned over several lines, make sure that each line (except the
- last one) is ended with a backslash.
-
- In total, there are six levels of sections in QDoc: \c \part, \c
- \chapter, \c \section1, \c \section2, \c \section3 and \c
- \section4. \c \section1 to \c \section4 correspond to the
- traditional section, subsection, subsubsection and
- subsubsubsection.
-
- There is a strict ordering of the section units:
-
- \code
- part
- |
- chapter
- |
- section1
- |
- section2
- |
- section3
- |
- section4
- \endcode
-
- For example, a \c section1 unit can only appear as the top level
- section or inside a \c chapter unit. Skipping a section unit, for
- example from \c part to \c section1, is not allowed.
-
- You can \e begin with either of the three: \c part, \c chapter or
- \c section1.
-
-
- \code
- / *!
- \part Basic Qt
-
- This is the first part.
-
-
- \chapter Getting Started
-
- This is the first part's first chapter.
-
-
- \section1 Hello Qt
-
- This is the first chapter's first section.
-
-
- \section1 Making Connections
-
- This is the first chapter's second section.
-
-
- \section1 Using the Reference Documentation
-
- This is the first chapter's third section.
-
-
- \chapter Creating Dialogs
-
- This is the first part's second chapter.
-
-
- \section1 Subclassing QDialog
-
- This is the second chapter's first section.
-
- ...
-
-
- \part Intermediate Qt
-
- This is the second part.
-
-
- \chapter Layout Management
-
- This is the second part's first chapter.
-
-
- \section1 Basic Layouts
-
- This is the first chapter's first section.
-
- ...
- * /
- \endcode
-
- QDoc renders this as:
-
- \quotation
- \raw HTML
- <a name="Basic Qt">
- <h1>Basic Qt</h1>
- </a>
- <p>This is the first part.</p>
-
- <a name="Getting started">
- <h2>Getting Started</h2>
- </a>
- This is the first part's first chapter.</p>
-
- <a name="Hello Qt">
- <h3>Hello Qt</h3>
- </a>
- <p>This is the first chapter's first section.</p>
-
- <a name="Making Connections">
- <h3>Making Connections</h3>
- </a>
- <p>This is the first chapter's second section.</p>
-
- <a name="Using the Reference Documentation">
- <h3>Using the Reference Documentation</h3>
- </a>
- <p>This is the first chapter's third section.</p>
-
- <a name="Creating Dialogs">
- <h2>Creating Dialogs</h2>
- </a>
- <p>This is the first part's second chapter.</p>
-
- <a name="Subclassing QDialog">
- <h3>Subclassing QDialog</h3>
- </a>
- <p>This is the second chapter's first section.</p>
-
- ...
-
- <a name="Intermediate Qt">
- <h1>Intermediate Qt</h1>
- </a>
- <p>This is the second part.</p>
-
- <a name="Layout Management">
- <h2>Layout Management</h2>
- </a>
- <p>This is the second part's first chapter.</p>
-
- <a name="Basic Layouts">
- <h3>Basic Layouts</h3>
- </a>
- <p>This is the first chapter's first section.</p>
-
- ...
-
- \endraw
- \endquotation
-
- Each section is a logical unit in the document. The section
- heading appears in the automatically generated table of contents
- that normally appears in the upper right-hand corner of the page.
-
- \target chapter-command
- \section1 \\chapter
-
- The \\chapter command is intended for use in
- larger documents, and divides the document into chapters.
-
- See \l{part} {\\part} for an explanation of the various
- section units, command argument, and rendering.
-
- \target sectionOne-command
- \section1 \\section1
-
- The \\section1 command starts a new section.
-
- See \l{part} {\\part} for an explanation of the various
- section units, command argument, and rendering.
-
- \target sectionTwo-command
- \section1 \\section2
-
- The \\section2 command starts a new section.
-
- See \l{part} {\\part} for an explanation of the various
- section units, command argument, and rendering.
-
- \target sectionThree-command
- \section1 \\section3
-
- The \\section3 command starts a new section.
-
- See \l{part} {\\part} for an explanation of the various
- section units, command argument, and rendering.
-
- \target sectionFour-command
- \section1 \\section4
-
- The \\section4 command starts a new section.
-
- See \l{part} {\\part} for an explanation of the various
- section units, command argument, and rendering.
-
-*/
-
-/*!
- \page 06-qdoc-commands-includecodeinline.html
- \previouspage Document Structure
- \contentspage QDoc Manual
- \nextpage Including External Code
-
- \title Including Code Inline
-
- The following commands are used to render source code without
- formatting. The source code begins on a new line, rendered in the
- code.
-
- \b{Note:} Although all these commands are for rendering C++
- code, the
- \l{07-0-qdoc-commands-includingexternalcode.html#snippet-command}
- {\\snippet} and
- \l{07-0-qdoc-commands-includingexternalcode.html#codeline-command}
- {\\codeline} commands are preferred over the others. These
- commands allow equivalent code snippets for other Qt language
- bindings to be substituted for the C++ snippets in the
- documentation.
-
- \target code-command
- \section1 \\code
-
- The \\code and \\endcode commands enclose a snippet of source code.
-
- \note The \l {c-command} {\\c} command can be used for short code
- fragments within a sentence. The \\code command is for longer code
- snippets. It renders the code verbatim in a separate paragraph in
- the code font.
-
- When processing any of the \\code, \l {newcode-command} {\\newcode} or \l
- {oldcode-command} {\\oldcode} commands, QDoc removes all
- indentation that is common for the verbatim code blocks within a
- \c{/}\c{*!} ... \c{*}\c{/} comment before it adds the standard
- indentation. For that reason the recommended style is to use 8
- spaces for the verbatim code contained within these commands
-
- \note This doesn't apply to externally quoted code using the \l
- {quotefromfile-command} {\\quotefromfile} or \l
- {quotefile-command} {\\quotefile} command.
-
- \code
- / *!
- \code
- #include <QApplication>
- #include <QPushButton>
-
- int main(int argc, char *argv[])
- {
- ...
- }
- \ endcode
- * /
- \endcode
-
- QDoc renders this as:
-
- \code
- #include <QApplication>
- #include <QPushButton>
-
- int main(int argc, char *argv[])
- {
- ...
- }
- \endcode
-
- Other QDoc commands are disabled within \\code... \\endcode, and
- the special character '\\' is accepted and rendered like the rest
- of the code.
-
- To include code snippets from an external file, use the
- \l{07-0-qdoc-commands-includingexternalcode.html#snippet-command}
- {\\snippet} and
- \l{07-0-qdoc-commands-includingexternalcode.html#codeline-command}
- {\\codeline} commands.
-
- See also \l {c-command} {\\c}, \l
- {07-0-qdoc-commands-includingexternalcode.html#quotefromfile-command}
- {\\quotefromfile}, \l{newcode-command} {\\newcode}, and \l {oldcode-command}
- {\\oldcode}.
-
- \target newcode-command
- \section1 \\newcode
-
- The \\newcode, \\oldcode, and \\endcode commands enable you to
- show how to port a snippet of code to a new version of an API.
-
- The \\newcode command and its companion the \\oldcode command are
- a convenience combination of the \l {code-command} {\\code} commands:
- this combination provides a text relating the two code snippets to each
- other.
-
- The \\newcode command requires a preceding \\oldcode statement.
-
- Like the \l{code-command}{\\code} command, the \\newcode command renders its
- code on a new line in the documentation using a monospace font and the
- standard indentation.
-
- \code
- / *!
- \oldcode
- if (printer->setup(parent))
- ...
- \newcode
- QPrintDialog dialog(printer, parent);
- if (dialog.exec())
- ...
- \ endcode
- * /
- \endcode
-
- QDoc renders this as:
-
- \quotation
- \oldcode
- if (printer->setup(parent))
- ...
- \newcode
- QPrintDialog dialog(printer, parent);
- if (dialog.exec())
- ...
- \endcode
- \endquotation
-
- Other QDoc commands are disabled within \\oldcode ... \\endcode,
- and the '\\' character doesn't need to be escaped.
-
- \target oldcode-command
- \section1 \\oldcode
-
- The \\oldcode command requires a corresponding
- \\newcode statement; otherwise QDoc fails to parse the command
- and emits a warning.
-
- See also \l {newcode-command} {\\newcode}.
-
- \target qml-command
- \section1 \\qml
-
- The \\qml and \\endqml commands enclose a snippet of QML source
- code. Currently, QDoc handles \\qml and \\endqml in exactly the same
- way as \\code and \\endcode.
-
- \code
- / *!
- \qml
- import QtQuick 1.0
-
- Row {
- Rectangle {
- width: 100; height: 100
- color: "blue"
- transform: Translate { y: 20 }
- }
- Rectangle {
- width: 100; height: 100
- color: "red"
- transform: Translate { y: -20 }
- }
- }
- \endqml
- * /
- \endcode
-
- QDoc renders this as:
-
- \qml
- import QtQuick 1.0
-
- Row {
- Rectangle {
- width: 100; height: 100
- color: "blue"
- transform: Translate { y: 20 }
- }
- Rectangle {
- width: 100; height: 100
- color: "red"
- transform: Translate { y: -20 }
- }
- }
- \endqml
-*/
-
-/*!
- \page 07-0-qdoc-commands-includingexternalcode.html
- \previouspage Including Code Inline
- \contentspage QDoc Manual
- \nextpage Creating Links
-
- \title Including External Code
-
- The following commands enable you to include code snippets from
- external files. You can make QDoc include the complete contents of
- a file, or you can quote specific parts of the file and skip
- others. The typical use of the latter is to quote a file chunk by
- chunk.
-
- \b{Note:} Although all these commands are for rendering C++
- code, the
- \l{07-0-qdoc-commands-includingexternalcode.html#snippet-command}
- {\\snippet} and
- \l{07-0-qdoc-commands-includingexternalcode.html#codeline-command}
- {\\codeline} commands are preferred over the others. These
- commands allow equivalent code snippets for other Qt language
- bindings to be substituted for the C++ snippets in the
- documentation.
-
- \target quotefile-command
- \section1 \\quotefile
-
- The \\quotefile command expands to the complete contents of the
- file given as argument.
-
- The command considers the rest of the line as part of its
- argument, make sure to follow the file name with a line break.
-
- The file's contents is rendered in a separate paragraph, using a
- monospace font and the standard indentation. The code is shown
- verbatim.
-
- \code
- / *!
- This is a simple "Hello world" example:
-
- \quotefile examples/main.cpp
-
- It contains only the bare minimum you need
- to get a Qt application up and running.
- * /
- \endcode
-
- QDoc renders this as:
-
- \quotation
- This is a simple "Hello world" example:
-
- \quotefile examples/main.cpp
-
- It contains only the bare minimum you need to get a Qt
- application up and running.
- \endquotation
-
- See also \l {quotefromfile-command} {\\quotefromfile} and
- \l {code-command} {\\code}.
-
-
- \target quotefromfile-command
- \section1 \\quotefromfile
-
- The \\quotefromfile command opens the file given as argument for
- quoting.
-
- The command considers the rest of the line as part of its
- argument, make sure to follow the file name with a line break.
-
- The command is intended for use when quoting parts from file with
- the walkthrough commands: \l {printline-command} {\\printline}, \l
- {printto-command} {\\printto}, \l {printuntil-command}
- {\\printuntil}, \l {skipline-command} {\\skipline}, \l
- {skipto-command} {\\skipto}, \l {skipuntil-command}
- {\\skipuntil}. This enables you to quote specific portions of a
- file.
-
- \code
- / *!
- The whole application is contained within
- the \c main() function:
-
- \quotefromfile examples/main.cpp
-
- \skipto main
- \printuntil app(argc, argv)
-
- First we create a QApplication object using
- the \c argc and \c argv parameters.
-
- \skipto QPushButton
- \printuntil resize
-
- Then we create a QPushButton, and give it a reasonable
- size using the QWidget::resize() function.
-
- ...
- * /
- \endcode
-
- QDoc renders this as:
-
- \quotation
- The whole application is contained within
- the \c main() function:
-
- \quotefromfile examples/main.cpp
-
- \skipto main
- \printuntil app(argc, argv)
-
- First we create a QApplication object using the \c argc
- and \c argv parameters.
-
- \skipto QPushButton
- \printuntil resize
-
- Then we create a QPushButton, and give it a reasonable
- size using the QWidget::resize() function.
-
- ...
- \endquotation
-
- (\l {Example File} {The complete example file...})
-
- QDoc remembers which file it is quoting from, and the current
- position in that file (see \l {file} {\\printline} for more
- information). There is no need to "close" the file.
-
- See also \l {quotefile-command} {\\quotefile}, \l {code-command}
- {\\code} and \l {dots} {\\dots}.
-
- \target printline-command
- \section1 \\printline
-
- The \\printline command expands to the line from the current
- position to the next non-blank line of the current source file.
-
- To ensure that the documentation remains synchronized with the
- source file, a substring of the line must be specified as an
- argument to the command. Note that the command considers the rest
- of the line as part of its argument, make sure to follow the
- substring with a line break.
-
- The line from the source file is rendered as a separate paragraph,
- using a monospace font and the standard indentation. The code is
- shown verbatim.
-
- \code
- / *!
- There has to be exactly one QApplication object
- in every GUI application that uses Qt.
-
- \quotefromfile examples/main.cpp
-
- \printline QApplication
-
- This line includes the QApplication class
- definition. QApplication manages various
- application-wide resources, such as the
- default font and cursor.
-
- \printline QPushButton
-
- This line includes the QPushButton class
- definition. The QPushButton widget provides a command
- button.
-
- \printline main
-
- The main function...
- * /
- \endcode
-
- QDoc renders this as:
-
- \quotation
- There has to be exactly one QApplication object
- in every GUI application that uses Qt.
-
- \quotefromfile examples/main.cpp
-
- \skipto QApplication
- \printline QApplication
-
- This line includes the QApplication class
- definition. QApplication manages various
- application-wide resources, such as the
- default font and cursor.
-
- \printline QPushButton
-
- This line includes the QPushButton class
- definition. The QPushButton widget provides a command
- button.
-
- \printline main
-
- The main function...
- \endquotation
-
- (\l {Example File} {The complete example file...})
-
- \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 {regular expression}.
-
- \code
- / *!
- \quotefromfile examples/mainwindow.cpp
-
- \skipto closeEvent
- \printuntil /^\}/
-
- Close events are sent to widgets that the users want to
- close, usually by clicking \c File|Exit or by clicking
- the \c X title bar button. By reimplementing the event
- handler, we can intercept attempts to close the
- application.
- * /
- \endcode
-
- QDoc renders this as:
-
- \quotation
- \quotefromfile examples/mainwindow.cpp
-
- \skipto closeEvent
- \printuntil /^\}/
-
- Close events are sent to widgets that the users want to
- close, usually by clicking \c File|Exit or by clicking
- the \c X title bar button. By reimplementing the event
- handler, we can intercept attempts to close the
- application.
- \endquotation
-
- (\l {widgets/scribble} {The complete example file...})
-
- The regular expression \c /^\}/ makes QDoc print until the first
- '}' character occurring at the beginning of the line without
- indentation. /.../ encloses the regular expression, and '^' means
- the beginning of the line. The '}' character must be escaped since
- it is a special character in regular expressions.
-
- QDoc will emit a warning if the specified substring or regular
- expression cannot be located, i.e. if the source code has changed.
-
- See also \l {printto-command} {\\printto} and \l
- {printuntil-command} {\\printuntil}.
-
- \target printto-command
- \section1 \\printto
-
- The \\printto command expands to all the lines from the current
- position up to and \e excluding the next line containing a given
- substring.
-
- The command considers the rest of the line as part of its
- argument, make sure to follow the substring with a line break. The
- command also follows the same conventions for \l {file}
- {positioning} and \l {substring} {argument} as the \l
- {printline-command} {\\printline} command.
-
- The lines from the source file are rendered in a separate
- paragraph, using a monospace font and the standard
- indentation. The code is shown verbatim.
-
- \code
- / *!
- The whole application is contained within the
- \c main() function:
-
- \quotefromfile examples/main.cpp
- \printto hello
-
- First we create a QApplication object using the \c argc and
- \c argv parameters...
- * /
- \endcode
-
- QDoc renders this as:
-
- \quotation
- The whole application is contained within the
- \c main() function:
-
- \quotefromfile examples/main.cpp
- \skipto main
- \printto hello
-
- First we create a QApplication object using the \c argc
- and \c argv parameters...
- \endquotation
-
- (\l {Example File} {The complete example file...})
-
- See also \l {printline-command} {\\printline} and \l
- {printuntil-command} {\\printuntil}.
-
- \target printuntil-command
- \section1 \\printuntil
-
- The \\printuntil command expands to all the lines from the current
- position up to and \e including the next line containing a given
- substring.
-
- The command considers the rest of the line as part of its
- argument, make sure to follow the substring with a line break. The
- command also follows the same conventions for \l {file}
- {positioning} and \l {substring} {argument} as the \l
- {printline-command} {\\printline} command.
-
- The lines from the source file are rendered in a separate
- paragraph, using a monospace font and the standard
- indentation. The code is shown verbatim.
-
- \code
- / *!
- The whole application is contained within the
- \c main() function:
-
- \quotefromfile examples/main.cpp
- \skipto main
- \printuntil hello
-
- First we create a QApplication object using the
- \c argc and \c argv parameters, then we create
- a QPushButton.
- * /
- \endcode
-
- QDoc renders this as:
-
- \quotation
- The whole application is contained within the
- \c main() function:
-
- \quotefromfile examples/main.cpp
- \skipto main
- \printuntil hello
-
- First we create a \l
- {http://qt-project.org/doc/qt-5.0/qtwidgets/qapplication.html} {QApplication}
- object using the \c argc and \c argv parameters, then we
- create a \l
- {http://qt-project.org/doc/qt-5.0/qtwidgets/qpushbutton.html} {QPushButton}.
- \endquotation
-
- (\l {Example File} {The complete example file...})
-
- See also \l {printline-command} {\\printline} and \l
- {printto-command} {\\printto}.
-
- \target skipline-command
- \section1 \\skipline
-
- The \\skipline command ignores the next non-blank line in the
- current source file.
-
- Doc reads the file sequentially, and the \\skipline command is
- used to move the current position (omitting a line of the source
- file). See the remark about \l {file} {file positioning} above.
-
- The command considers the rest of the line as part of its
- argument, make sure to follow the substring with a line break. The
- command also follows the same conventions for \l {substring}
- {argument} as the \l {printline-command} {\\printline} command,
- and it is used in conjunction with the \l {quotefromfile-command}
- {\\quotefromfile} command.
-
- \code
- / *!
- QPushButton is a GUI push button that the user
- can press and release.
-
- \quotefromfile examples/main.cpp
- \skipline QApplication
- \printline QPushButton
-
- This line includes the QPushButton class
- definition. For each class that is part of the
- public Qt API, there exists a header file of
- the same name that contains its definition.
- * /
- \endcode
-
- QDoc renders this as:
-
- \quotation
- \l
- QPushButton is a GUI push button that the user
- can press and release.
-
- \quotefromfile examples/main.cpp
- \skipto QApplication
- \skipline QApplication
- \printline QPushButton
-
- This line includes the QPushButton class
- definition. For each class that is part of the public
- Qt API, there exists a header file of the same name
- that contains its definition.
- \endquotation
-
- (\l {Example File} {The complete example file...})
-
- See also \l {skipto-command} {\\skipto}, \l {skipuntil-command}
- {\\skipuntil} and \l {dots} {\\dots}.
-
- \target skipto-command
- \section1 \\skipto
-
- The \\skipto command ignores all the lines from the current
- position up to and \e excluding the next line containing a given
- substring.
-
- QDoc reads the file sequentially, and the \\skipto command is used
- to move the current position (omitting one or several lines of the
- source file). See the remark about \l {file} {file positioning}
- above.
-
- The command considers the rest of the line as part of its
- argument, make sure to follow the substring with a line break.
-
- The command also follows the same conventions for \l {substring}
- {argument} as the \l {printline-command} {\\printline} command,
- and it is used in conjunction with the \l {quotefromfile-command}
- {\\quotefromfile} command.
-
- \code
- / *!
- The whole application is contained within
- the \c main() function:
-
- \quotefromfile examples/main.cpp
- \skipto main
- \printuntil }
-
- First we create a QApplication object. There
- has to be exactly one such object in
- every GUI application that uses Qt. Then
- we create a QPushButton, resize it to a reasonable
- size...
- * /
- \endcode
-
- QDoc renders this as:
-
- \quotation
- The whole application is contained within
- the \c main() function:
-
- \quotefromfile examples/main.cpp
- \skipto main
- \printuntil }
-
- First we create a QApplication object. There has to be
- exactly one such object in every GUI application that
- uses Qt. Then we create a QPushButton, resize it to a
- reasonable size ...
- \endquotation
-
- (\l {Example File} {The complete example file...})
-
- See also \l {skipline-command} {\\skipline}, \l
- {skipuntil-command} {\\skipuntil} and \l {dots} {\\dots}.
-
- \target skipuntil-command
- \section1 \\skipuntil
-
- The \\skipuntil command ignores all the lines from the current
- position up to and \e including the next line containing a given
- substring.
-
- QDoc reads the file sequentially, and the \\skipuntil command is
- used to move the current position (omitting one or several lines
- of the source file). See the remark about \l {file} {file
- positioning} above.
-
- The command considers the rest of the line as part of its
- argument, make sure to follow the substring with a line break.
-
- The command also follows the same conventions for \l {substring}
- {argument} as the \l {printline-command} {\\printline} command,
- and it is used in conjunction with the \l {quotefromfile-command}
- {\\quotefromfile} command.
-
- \code
- / *!
- The first thing we did in the \c main() function
- was to create a QApplication object \c app.
-
- \quotefromfile examples/main.cpp
- \skipuntil show
- \dots
- \printuntil }
-
- In the end we must remember to make \c main() pass the
- control to Qt. QCoreApplication::exec() will return when
- the application exits...
- * /
- \endcode
-
- QDoc renders this as:
-
- \quotation
- The first thing we did in the \c main() function was to
- create a QApplication object \c app.
-
- \quotefromfile examples/main.cpp
- \skipuntil show
- \dots
- \printuntil }
-
- In the end we must remember to make \c main() pass the
- control to Qt. QCoreApplication::exec()
- will return when the application exits...
- \endquotation
-
- (\l {Example File} {The complete example file...})
-
- See also \l {skipline-command} {\\skipline}, \l {skipto-command}
- {\\skipto} and \l {dots} {\\dots}.
-
- \target dots-command
- \section1 \\dots
-
- The \\dots command indicates that parts of the source file have
- been omitted when quoting a file.
-
- The command is used in conjunction with the \l
- {quotefromfile-command} {\\quotefromfile} command, and should be
- stated on its own line. The dots are rendered on a new line, using
- a monospace font.
-
- \code
- / *!
- \quotefromfile examples/main.cpp
- \skipto main
- \printuntil {
- \dots
- \skipuntil exec
- \printline }
- * /
- \endcode
-
- QDoc renders this as:
-
- \quotefromfile examples/main.cpp
- \skipto main
- \printuntil {
- \dots
- \skipuntil exec
- \printline }
-
- (\l {Example File} {The complete example file...})
-
- The default indentation is 4 spaces, but this can be adjusted
- using the command's optional argument.
-
- \code
- / *!
- \dots 0
- \dots
- \dots 8
- \dots 12
- \dots 16
- * /
- \endcode
-
- QDoc renders this as:
-
- \dots 0
- \dots
- \dots 8
- \dots 12
- \dots 16
-
- See also \l {skipline-command} {\\skipline}, \l {skipto-command}
- {\\skipto} and \l {skipuntil-command} {\\skipuntil}.
-
- \target snippet-command
- \section1 \\snippet
-
- The \\snippet command causes a code snippet to be included
- verbatim as preformatted text, which may be syntax highlighted.
-
- Each code snippet is referenced by the file that holds it and by
- a unique identifier for that file. Snippet files are typically
- stored in a \c{snippets} directory inside the documentation
- directory (for example, \c{$QTDIR/doc/src/snippets}).
-
- For example, the following documentation references a snippet in a
- file residing in a subdirectory of the documentation directory:
-
- \code
- \snippet snippets/textdocument-resources/main.cpp Adding a resource
- \endcode
-
- The text following the file name is the unique identifier for the
- snippet. This is used to delimit the quoted code in the relevant
- snippet file, as shown in the following example that corresponds to
- the above \c{\\snippet} command:
-
- \dots
- \code
- QImage image(64, 64, QImage::Format_RGB32);
- image.fill(qRgb(255, 160, 128));
-
- //! [Adding a resource]
- document->addResource(QTextDocument::ImageResource,
- QUrl("mydata://image.png"), QVariant(image));
- //! [Adding a resource]
- \endcode
- \dots
-
- \target codeline-command
- \section1 \\codeline
-
- The \\codeline command inserts a blank line of preformatted
- text. It is used to insert gaps between snippets without closing
- the current preformatted text area and opening a new one.
-
-*/
-
-/*!
- \page 07-1-example.html
- \previouspage Including External Code
- \contentspage QDoc Manual
-
- \title Example File
-
- \quotefile examples/main.cpp
-*/
-
-/*!
- \page 08-qdoc-commands-creatinglinks.html
- \previouspage Including External Code
- \contentspage QDoc Manual
- \nextpage Including Images
-
- \title Creating Links
-
- These commands are for creating hyperlinks to classes, functions,
- examples, and other targets.
-
- \target l-command
- \section1 \\l (link)
-
- The \\l link command is used to create a hyperlink to many
- different kinds of targets. The command's general syntax is:
-
- \code
- \l {link target} {link text}
- \endcode
-
- \code
- / *!
- Read the \l {http://qt-project.org/doc/qt-5.0/}
- {Qt 5.0 Documentation} carefully.
- * /
- \endcode
-
- QDoc renders this as:
-
- \quotation
- Read the \l {http://qt-project.org/doc/qt-5.0/}
- {Qt 5.0 Documentation} carefully.
- \endquotation
-
- If the link target is equivalent to the link text, the second
- argument can be omitted.
-
- For example, if you have documentation like:
-
- \code
- / *!
- \target assertions
-
- Assertions make some statement about the text at the
- point where they occur in the regexp, but they do not
- match any characters.
-
- ...
-
- Regexps are built up from expressions, quantifiers, and
- \l {assertions} {assertions}.
- * /
- \endcode
-
- You can simplify this as follows:
-
- \code
- / *!
- \target assertions
-
- Assertions make some statement about the text at the
- point where they occur in the regexp, but they do not
- match any characters.
-
- ...
-
- Regexps are built up from expressions, quantifiers, and
- \l assertions.
- * /
- \endcode
-
- For the one-parameter version, the braces can often be omitted.
- The \\l command supports several kinds of links:
-
- \list
-
- \li \c {\l QWidget} - The name of a class documented with the \l
- {class-command} {\\class} command.
-
- \li \c {\l QWidget::sizeHint()} - The name of a member function,
- documented with or without an \l {fn-command} {\\fn} command.
-
- \li \c {\l <QtGlobal>} - The subject of a \l {headerfile-command}
- {\\headerfile} command.
-
- \li \c {\l widgets/wiggly} - The relative path used in an \l
- {example-command} {\\example} command.
-
- \li \c {\l {QWidget Class Reference}} - The title used in a
- \l {title-command} {\\title} command.
-
- \li \c {\l {Introduction to QDoc}}- The text from one of the
- \l{part-command} {\\part}, \l{chapter} {\\chapter}, or \l
- {sectionOne-command} {\\section} commands.
-
- \li \c {\l fontmatching} - The argument of a \l {target-command}
- {\\target} command.
-
- \li \c {\l {Shared Classes}} - A keyword named in a \l
- {keyword-command} {\\keyword} command.
-
- \li \c {\l network.html} - The file name used in a \l
- {page-command} {\\page} command.
-
- \li \c {\l http://qt-project.org/} - A URL.
-
- \endlist
-
- QDoc also tries to make a link out of any word that doesn't
- resemble a normal English word, for example, Qt class names or
- functions, like QWidget or QWidget::sizeHint(). In these cases,
- the \\l command can actually be omitted, but by using the command,
- you ensure that QDoc will emit a warning if it cannot find the
- link target. In addition, if you only want the function name to
- appear in the link, you can use the following syntax:
-
- \list
- \li \c {\l {QWidget::} {sizeHint()}}
- \endlist
-
- QDoc renders this as:
-
- \quotation
- \l {QWidget::} {sizeHint()}
- \endquotation
-
- See also \l {sa-command} {\\sa}, \l {target-command} {\\target},
- and \l {keyword-command} {\\keyword}.
-
-
- \target sa-command
- \section1 \\sa (see also)
-
- The \\sa command defines a list of links that will be rendered in
- a separate "See also" section at the bottom of the documentation
- unit.
-
- The command takes a comma-separated list of links as its
- argument. If the line ends with a comma, you can continue
- the list on the next line. The general syntax is:
-
- \code
- \sa {the first link}, {the second link},
- {the third link}, ...
- \endcode
-
- QDoc will automatically try to generate "See also" links
- interconnecting a property's various functions. For example, a
- setVisible() function will automatically get a link to visible()
- and vice versa.
-
- In general, QDoc will generate "See also" links that interconnect
- the functions that access the same property. It recognizes four
- different syntax versions:
-
- \list
- \li \c property()
- \li \c setProperty()
- \li \c isProperty()
- \li \c hasProperty()
- \endlist
-
- The \\sa command supports the same kind of links as the \l
- {l-command} {\\l} command.
-
- \code
- / *!
- Appends the actions \a actions to this widget's
- list of actions.
-
- \sa removeAction(), QMenu, addAction()
- * /
- void QWidget::addActions(QList<QAction *> actions)
- {
- ...
- }
- \endcode
-
- QDoc renders this as:
-
- \quotation
- \b {void QWidget::addActions ( QList<QAction*>
- \e actions )}
-
- Appends the actions \e actions to this widget's list of
- actions.
-
- See also \l {QWidget::removeAction()} {removeAction()},
- \l QMenu, and \l {QWidget::addAction()} {addAction()}.
- \endquotation
-
- See also \l {l-command} {\\l}, \l {target-command} {\\target} and
- \l {keyword-command} {\\keyword}.
-
-
- \target target-command
- \section1 \\target
-
- The \\target command names a place in the documentation that you
- can link to using the \l {l-command} {\\l (link)} and \l
- {sa-command} {\\sa (see also)} commands.
-
- The text up to the line break becomes the target name. Be sure to
- follow the target name with a line break. Curly brackets are not
- required around the target name, but they may be required when the
- target name is used in a link command. See below.
-
- \code
- / *!
- \target capturing parentheses
- \section1 Capturing Text
-
- Parentheses allow us to group elements together so that
- we can quantify and capture them.
-
- ...
- * /
- \endcode
-
- The target name \e{capturing parentheses} can be linked from
- within the same document containing the target in two ways:
-
- \list
- \li \c {\l {capturing parentheses}} (from within the same QDoc comment)
- \li \c {\l qregexp.html#capturing-parentheses} (from elsewhere in the same document)
- \endlist
-
- \note The brackets in the link example are required because the
- target name contains spaces.
-
- The target name can be linked to in the following way from other documents:
-
- \list
- \li \c {\l http://qt-project.org/doc/qt-5.0/qtcore/qregexp.html#capturing-parentheses}
- \endlist
-
- 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, but stronger. A keyword can be linked from anywhere using
- a simple syntax.
-
- Keywords must be unique over all the documents processed during
- the QDoc run. The command uses the rest of the line as its
- argument. Be sure to follow the keyword with a line break.
-
-
- \code
- / *!
- \class QRegExp
- \reentrant
- \brief The QRegExp class provides pattern
- matching using regular expressions.
- \ingroup tools
- \ingroup misc
- \ingroup shared
- \mainclass
-
- \keyword regular expression
-
- Regular expressions, or "regexps", provide a way to
- find patterns within text.
-
- ...
- * /
- \endcode
-
- The location marked with the keyword can be linked to with:
-
- \code
- / *!
- When a string is surrounded by slashes, it is
- interpreted as a \l {regular expression}.
- * /
- \endcode
-
- QDoc renders this as:
-
- \quotation
- When a string is surrounded by slashes, it is
- interpreted as a \l {regular expression}.
- \endquotation
-
- If the keyword text contains spaces, the brackets are required.
-
- See also \l {l-command} {\\l (link)}, \l {sa-command} {\\sa (see
- also)} and \l {target-command} {\\target}.
-
-*/
-
-/*!
- \page 09-qdoc-commands-includingimages.html
- \previouspage Creating Links
- \contentspage QDoc Manual
- \nextpage Tables and Lists
-
- \title Including Images
-
- The graphic commands makes it possible to include images in the
- documentation. The images can be rendered as separate paragraphs,
- or within running text.
-
- \target image-command
- \section1 \\image
-
- The \\image command expands to the image specified by its first
- argument, and renders it centered as a separate paragraph.
-
- The command takes two arguments. The first argument is the name of
- the image file. The second argument is optional and is a simple
- description of the image, equivalent to the HTML alt="" in an image
- tag. The description is used for tooltips and for browsers that don't
- support images, like the Lynx text browser.
-
- The remaining text \e{after} the file name is the optional,
- description argument. Be sure to follow the file name or the
- description with a line break. Curly brackets are required if the
- description argument spans multiple lines.
-
- \code
- / *!
- Qt is a C++ toolkit for cross-platform GUI application development.
-
- \image happyguy.jpg "Happy guy"
-
- Qt provides single-source portability across Microsoft
- Windows, Mac OS X, Linux, and all major commercial Unix
- variants. It is also available for embedded devices.
- * /
- \endcode
-
- QDoc renders this as:
-
- \quotation
- Qt is a C++ toolkit for cross-platform GUI application development.
-
- \image happyguy.jpg image "Happy guy"
-
- Qt provides single-source portability across Microsoft
- Windows, Mac OS X, Linux, and all major commercial Unix
- variants. It is also available for embedded devices.
- \endquotation
-
- See also \l {inlineimage-command} {\\inlineimage} and \l
- {caption-command} {\\caption}.
-
- \target inlineimage-command
- \section1 \\inlineimage
-
- The \\inlineimage command expands to the image specified by its
- argument. The image is rendered inline with the rest of the text.
-
- The command takes two arguments. The first argument is the name of
- the image file. The second argument is optional and is a simple
- description of the image, equivalent to the HTML alt="" in an image
- tag. The description is used for tooltips, and for when a browser
- doesn't support images, like the Lynx text browser.
-
- The most common use of the \\inlineimage command is in lists and
- tables. Here is an example of including inline images in a list:
-
- \code
- / *!
- \list 1
- \li \inlineimage happy.gif Oh so happy!
- \li \inlineimage happy.gif Oh so happy!
- \li \inlineimage happy.gif Oh so happy!
- \endlist
- * /
- \endcode
-
- QDoc renders this as:
-
- \list 1
- \li \inlineimage happy.gif Oh so happy!
- \li \inlineimage happy.gif Oh so happy!
- \li \inlineimage happy.gif Oh so happy!
- \endlist
-
- Here is an example of including inline images in a table:
-
- \code
- / *!
- \table
- \header
- \li Qt
- \li Qt Creator
- \row
- \li \inlineimage happy.gif Oh so happy!
- \li \inlineimage happy.gif Oh so happy!
- \row
- \li \inlineimage happy.gif Oh so happy!
- \li \inlineimage happy.gif Oh so happy!
- \endtable
- * /
- \endcode
-
- QDoc renders this as:
-
- \raw HTML
- <table align="center" cellpadding="2"
- cellspacing="1" border="0">
- <tr valign="top" bgcolor="#a2c511">
- <th>Qt</th>
- <th>Qt Creator</th>
- </tr>
- <tr valign="top" bgcolor="#f0f0f0">
- <td><img src="images/happy.gif" alt="Oh so happy!" />
- </td>
- <td><img src="images/happy.gif" alt="Oh so happy!" />
- </td>
- </tr>
- <tr valign="top" bgcolor="#f0f0f0">
- <td><img src="images/happy.gif" alt="Oh so happy!"/>
- </td>
- <td><img src="images/happy.gif" alt="Oh so happy!" />
- </td>
- </tr>
- </table>
- \endraw
-
- The command can also be used to insert an image inline with the
- text.
-
- \code
- / *!
- \inlineimage training.jpg Qt Training
- The Qt Programming course is offered as a
- five day Open Enrollment Course. The classes
- are open to the public. Although the course is open
- to anyone who wants to learn, attendees should
- have significant experience in C++ development
- to derive maximum benefit from the course.
- * /
- \endcode
-
- QDoc renders this as:
-
- \quotation
- \inlineimage training.jpg Qt Training
- The Qt Programming course is offered as a
- five day Open Enrollment Course. The classes
- are open to the public. Although the course is open
- to anyone who wants to learn, attendees should
- have significant experience in C++ development
- to derive maximum benefit from the course.
- \endquotation
-
- See also \l {image-command} {\\image} and \l {caption-command} {\\caption}.
-
- \target caption-command
- \section1 \\caption
-
- The \\caption command provides a caption for an image.
-
- The command takes all the text up to the end of the paragraph to
- be the caption. Experiment until you get the effect you want.
-
- \code
- / *!
- \table 100%
- \row
- \li \image windowsvista-pushbutton.png
- \caption The QPushButton widget provides a command button.
- \li \image windowsvista-toolbutton.png
- \caption The QToolButton class provides a quick-access button to commands
- or options, usually used inside a QToolBar.
- \endtable
- * /
- \endcode
-
- QDoc renders this as:
-
- \table 100%
- \row
- \li \image windowsvista-pushbutton.png
- \caption The QPushButton widget provides a command button.
- \li \image windowsvista-toolbutton.png
- \caption The QToolButton class provides a quick-access button to commands
- or options, usually used inside a QToolBar.
- \endtable
-
- See also \l {image-command} {\\image} and \l {inlineimage-command}
- {\\inlineimage}
-*/
-
-/*!
- \page 10-qdoc-commands-tablesandlists.html
- \previouspage Including Images
- \contentspage QDoc Manual
- \nextpage Special Content
-
- \title Tables and Lists
-
- These commands enable creating lists and tables. A list is
- rendered left aligned as a separate paragraph. A table is rendered
- centered as a separate paragraph. The table width depends on the
- width of its contents.
-
- \target table-command
- \section1 \\table
-
- The \\table and \\endtable commands delimit the contents of a
- table.
-
- The command accepts a single argument specifying the table's width
- as a percentage of the page width:
-
- \code
- / *!
- \table 100 %
-
- ...
-
- \endtable
- * /
- \endcode
-
- The code above ensures that the table will fill all available
- space. If the table's width is smaller than 100 %, the table will
- be centered in the generated documentation.
-
- A table can contain headers, rows and columns. A row starts with a
- \l {row-command} {\\row} command and consists of cells, each of which
- starts with an \l {li-command} {\\li} command. There is also a \l
- {header-command} {\\header} command which is a special kind of row
- that has a special format.
-
- \code
- / *!
- \table
- \header
- \li Qt Core Feature
- \li Brief Description
- \row
- \li \l {Signal and Slots}
- \li Signals and slots are used for communication
- between objects.
- \row
- \li \l {Layout Management}
- \li The Qt layout system provides a simple
- and powerful way of specifying the layout
- of child widgets.
- \row
- \li \l {Drag and Drop}
- \li Drag and drop provides a simple visual
- mechanism which users can use to transfer
- information between and within applications.
- \endtable
- * /
- \endcode
-
- QDoc renders this as:
-
- \raw HTML
- <table align="center" cellpadding="2"
- cellspacing="1" border="0">
- <tr valign="top" bgcolor="#a2c511">
- <th>Qt Core Feature</th>
- <th>Brief Description</th>
- </tr>
-
- <tr valign="top" bgcolor="#d0d0d0">
- <td>
- <a href="http://qt-project.org/doc/qt-5.0/qtcore/signalsandslots.html">
- Signals and Slots</a>
- </td>
- <td>Signals and slots are used for communication
- between objects.</td>
- </tr>
-
- <tr valign="top" bgcolor="#c0c0c0">
- <td>
- <a href="http://qt-project.org/doc/qt-5.0/qtwidgets/layout.html">
- Layout Management</a></td>
- <td>The Qt layout system provides a simple
- and powerful way of specifying the layout
- of child widgets.</td>
- </tr>
-
- <tr valign="top" bgcolor="#d0d0d0">
- <td>
- <a href="http://qt-project.org/doc/qt-5.0/qtgui/dnd.html">
- Drag and Drop</a></td>
- <td>Drag and drop provides a simple visual
- mechanism which users can use to transfer
- information between and within applications.</td>
- </tr>
-
- </table>
- \endraw
-
- You can also make cells span several rows and columns. For
- example:
-
- \code
- / *!
- \table
- \header
- \li {3,1} This header cell spans three columns,
- but only one row.
- \row
- \li {2, 1} This table cell spans two columns,
- but only one row
- \li {1, 2} This table cell spans only one column,
- but two rows.
- \row
- \li A regular table cell
- \li A regular table cell
- \endtable
- * /
- \endcode
-
- QDoc renders this as:
-
- \raw HTML
- <table align="center" cellpadding="2" cellspacing="1"
- border="0">
-
- <tr valign="top" bgcolor="#a2c511">
- <th colspan="3" rowspan=" 1">
- This header cell spans three columns, but only one row.
- </th>
- </tr>
-
- <tr valign="top" bgcolor="#d0d0d0">
- <td colspan="2" rowspan=" 1">
- This table cell spans two columns, but only one row.
- </td>
- <td rowspan=" 2">
- This table cell spans only one column, but two rows.
- </td>
- </tr>
-
- <tr valign="top" bgcolor="#c0c0c0">
- <td>A regular table cell</td>
- <td>A regular table cell</td>
- </tr>
-
- </table>
- \endraw
-
- See also \l {header-command} {\\header}, \l {row-command} {\\row} and \l {li-command} {\\li}.
-
- \target header-command
- \section1 \\header
-
- The \\header command indicates that the following table cells are
- the current table's column headers.
-
- The command can only be used within the \l{table-command}
- {\\table...\\endtable} commands. A header can contain several
- cells. A cell is created with the \l {li-command} {\\li} command.
-
- A header cell's text is centered within the table cell and
- rendered using a bold font.
-
- \code
- / *!
- \table
- \header
- \li Qt Core Feature
- \li Brief Description
- \row
- \li \l {Signal and Slots}
- \li Signals and slots are used for communication
- between objects.
- \endtable
- * /
- \endcode
-
- QDoc renders this as:
-
- \raw HTML
- <table align="center" cellpadding="2"
- cellspacing="1" border="0">
- <tr valign="top" bgcolor="#a2c511">
- <th>Qt Core Feature</th>
- <th>Brief Description</th>
- </tr>
-
- <tr valign="top" bgcolor="#d0d0d0">
- <td>
- <a href="http://qt-project.org/doc/qt-5.0/qtcore/signalsandslots.html">
- Signals and Slots</a>
- </td>
- <td>Signals and slots are used for communication
- between objects.</td>
- </tr>
- </table>
- \endraw
-
- See also \l {table-command} {\\table}, \l {row-command} {\\row} and \l {li-command} {\\li}.
-
- \target row-command
- \section1 \\row
-
- The \\row command begins a new row in a table. The \l {li-command}
- {\\li items} that belong in the new row will immediately follow the
- \\row.
-
- The command can only be used within the \l{table-command}
- {\\table...\\endtable} commands. A row can contain several
- cells. A cell is created with the \l {li-command} {\\li} command.
-
- The background cell color of each row alternates between two
- shades of grey, making it easier to distinguish the rows from each
- other. The cells' contents is left aligned.
-
- \code
- / *!
- \table
- \header
- \li Qt Core Feature
- \li Brief Description
- \row
- \li \l {Signal and Slots}
- \li Signals and slots are used for communication
- between objects.
- \row
- \li \l {Layout Management}
- \li The Qt layout system provides a simple
- and powerful way of specifying the layout
- of child widgets.
- \row
- \li \l {Drag and Drop}
- \li Drag and drop provides a simple visual
- mechanism which users can use to transfer
- information between and within applications.
- \endtable
- * /
- \endcode
-
- QDoc renders this as:
-
- \raw HTML
- <table align="center" cellpadding="2"
- cellspacing="1" border="0">
- <tr valign="top" bgcolor="#a2c511">
- <th>Qt Core Feature</th>
- <th>Brief Description</th>
- </tr>
-
- <tr valign="top" bgcolor="#d0d0d0">
- <td>
- <a href="http://qt-project.org/doc/qt-5.0/qtcore/signalsandslots.html">
- Signals and Slots</a>
- </td>
- <td>Signals and slots are used for communication
- between objects.</td>
- </tr>
-
- <tr valign="top" bgcolor="#c0c0c0">
- <td>
- <a href="http://qt-project.org/doc/qt-5.0/qtwidgets/layout.html">
- Layout Management</a></td>
- <td>The Qt layout system provides a simple
- and powerful way of specifying the layout
- of child widgets.</td>
- </tr>
-
- <tr valign="top" bgcolor="#d0d0d0">
- <td>
- <a href="http://qt-project.org/doc/qt-5.0/qtgui/dnd.html">
- Drag and Drop</a></td>
- <td>Drag and drop provides a simple visual
- mechanism which users can use to transfer
- information between and within applications.</td>
- </tr>
-
- </table>
- \endraw
-
- See also \l {table-command} {\\table}, \l {header-command}
- {\\header}, and \l {li-command} {\\li}.
-
- \target value-command
- \section1 \\value
-
- The \\value command starts the documentation of a C++ enum item.
-
- The command's first argument is the enum item. Then follows its
- associated description. The description argument ends at the next
- blank line or \\value. The arguments are rendered within a table.
-
- The documentation will be located in the associated class, header
- file or namespace documentation. See the \l {enum-command}
- {\\enum} documentation for an example.
-
- See also \l {enum-command} {\\enum} and \l {omitvalue-command} {\\omitvalue}.
-
- \target omitvalue-command
- \section1 \\omitvalue
-
- The \\omitvalue command excludes a C++ enum item from the
- documentation.
-
- The command's only argument is the name of the enum item that will
- be omitted. See the \l {enum-command} {\\enum} documentation for
- an example.
-
- See also \l {enum-command} {\\enum} and \l {value-command}
- {\\value}.
-
- \target list-command
- \section1 \\list
-
- The \\list and \\endlist commands delimit a list of items.
-
- Create each list item with the \l {li-command} {\\li} command. A
- list always contains one or more items. Lists can be nested. For
- example:
-
- \code
- / *!
- \list
- \li Qt Reference Documentation: Getting Started
- \list
- \li How to Learn Qt
- \li Installation
- \list
- \li Qt/X11
- \li Qt/Windows
- \li Qt/Mac
- \li Qt/Embedded
- \endlist
- \li Tutorial and Examples
- \endlist
- \endlist
- * /
- \endcode
-
- QDoc renders this as:
-
- \list
- \li Qt Reference Documentation: Getting Started
- \list
- \li How to Learn Qt
- \li Installation
- \list
- \li Qt/X11
- \li Qt/Windows
- \li Qt/Mac
- \li Qt/Embedded
- \endlist
- \li Tutorial and Examples
- \endlist
- \endlist
-
- The \\list command takes an optional argument providing
- alternative appearances for the list items.
-
- \code
- / *!
- \list
- \li How to Learn Qt
- \li Installation
- \li Tutorial and Examples
- \endlist
- * /
- \endcode
-
- QDoc renders the list items with bullets (the default):
-
- \list
- \li How to Learn Qt
- \li Installation
- \li Tutorial and Examples
- \endlist
-
- \warning There appears to be a bug in qdoc here. If you include
- any of the argument types, you get a numeric list. We're looking
- into it.
-
- If you provide 'A' as an argument to the \\list command, the
- bullets are replaced with characters in alphabetical order:
-
- \list A
- \li How to Learn Qt
- \li Installation
- \li Tutorial and Examples
- \endlist
-
- If you replace 'A' with '1', the list items are numbered in
- ascending order:
-
- \list 1
- \li How to Learn Qt
- \li Installation
- \li Tutorial and Examples
-
- \endlist
-
- If you provide 'i' as the argument, the bullets are replaced with
- roman numerals:
-
- \list i
- \li How to Learn Qt
- \li Installation
- \li Tutorial and Examples
- \endlist
-
- Finally, you can make the list items appear with roman numbers
- following in ascending order if you provide 'I' as the optional
- argument:
-
- \list I
- \li How to Learn Qt
- \li Installation
- \li Tutorial and Examples
- \endlist
-
- You can also make the listing start at any character or number by
- simply provide the number or character you want to start at. For
- example:
-
- \code
- / *!
- \list G
- \li How to Learn Qt
- \li Installation
- \li Tutorial and Examples
- \endlist
- * /
- \endcode
-
- \note This doesn't work in DITA XML, so don't use it because it
- produces a DITA XML file that doesn't validate. There probably is
- a way to do this in DITA, so if we figure it out, we will put it
- in. But this capability is not used anywhere other than right
- here, so it probably isn't important. For now, if you use this
- option, qdoc will ignore it and produce a list without it.
-
- QDoc renders this as:
-
- \list G
- \li How to Learn Qt
- \li Installation
- \li Tutorial and Examples
- \endlist
-
- See also \l {li-command} {\\li}.
-
- \target li-command
- \section1 \\li (table cell, list item)
-
- The \\li command marks a table cell or a list item. This command
- is only used in \l{table-command} {tables} and \l{list-command}
- {lists}.
-
- It considers everything as its argument until the next \\li command, until the
- next \l {table-command} {\\endtable}, or \l {list-command} {\\endlist}
- command. See \l {table-command} {\\table} and \l {list-command} {\\list}
- for examples.
-
- If the command is used within a table, you can also specify
- how many rows or columns the item should span.
-
- \code
- / *!
- \table
- \header
- \li {3,1} This header cell spans three columns
- but only one row.
- \row
- \li {2, 1} This table item spans two columns
- but only one row
- \li {1, 2} This table item spans only one column,
- but two rows.
- \row
- \li A regular table item
- \li A regular table item
- \endtable
- * /
- \endcode
-
- QDoc renders this as:
-
- \raw HTML
- <table align="center" cellpadding="2" cellspacing="1"
- border="0">
-
- <tr valign="top" bgcolor="#a2c511">
- <th colspan="3" rowspan=" 1">
- This header cell spans three columns, but only one row.
- </th>
- </tr>
-
- <tr valign="top" bgcolor="#d0d0d0">
- <td colspan="2" rowspan=" 1">
- This table item spans two columns, but only one row.
- </td>
- <td rowspan=" 2">
- This table item spans only one column, but two rows.
- </td>
- </tr>
-
- <tr valign="top" bgcolor="#c0c0c0">
- <td>A regular table item</td>
- <td>A regular table item</td>
- </tr>
-
- </table>
- \endraw
-
- If not specified, the item will span one column and one row.
-
- See also \l {table-command} {\\table}, \l {header-command}
- {\\header}, and \l {list-command} {\\list}.
-
-*/
-
-/*!
- \page 11-qdoc-commands-specialcontent.html
- \previouspage Tables and Lists
- \contentspage QDoc Manual
- \nextpage Miscellaneous
-
- \title Special Content
-
- The document contents commands identify parts of the documentation,
- parts with a special rendering, conceptual meaning or
- function.
-
- \target abstract-command
- \section1 \\abstract
-
- The \\abstract and \\endabstract commands delimit a
- document's abstract section.
-
- The abstract section is rendered as an indented italicized
- paragraph.
-
- \warning The \b{\\abstract} and \b{\\endabstract} commands
- have not been implemented. The abstract section is rendered as a
- regular HTML paragraph.
-
- \target quotation-command
- \section1 \\quotation
-
- The \\quotation and \\endquotation commands delimit a long quotation.
-
- The text in the delimited block is surrounded by
- \b{<blockquote>} and \b{</blockquote>} in the html output,
- e.g.:
-
- \code
- / *!
- Although the prospect of a significantly broader market is
- good news for Firstlogic, the notion also posed some
- challenges. Dave Dobson, director of technology for the La
- Crosse, Wisconsin-based company, said:
-
- \quotation
- As our solutions were being adopted into new
- environments, we saw an escalating need for easier
- integration with a wider range of enterprise
- applications.
- \endquotation
- * /
- \endcode
-
- The text in the \b{\\quotation} block will appear in the generated HTML as:
-
- \code
- <blockquote>
- <p>As our solutions were being adopted into new environments,
- we saw an escalating need for easier integration with a wider
- range of enterprise applications.</p>
- </blockquote>
- \endcode
-
- The built-in style sheet for most browsers will render the
- contents of the <blockquote> tag with left and right
- indentations. The example above would be rendered as:
-
- \quotation
- As our solutions were being adopted into new
- environments, we saw an escalating need for easier
- integration with a wider range of enterprise
- applications.
- \endquotation
-
- But you can redefine the \b{<blockquote>} tag in your style.css file.
-
- \target footnote-command
- \section1 \\footnote
-
- The \\footnote and \\endfootnote commands delimit a footnote.
-
- The footnote is rendered at the bottom of the page.
-
- \warning The \b{\\footnote} and \b{\\endfootnote} commands
- have not been implemented. The footnote is rendered as a regular
- HTML paragraph.
-
- \target note-command
- \section1 \\note
-
- The \\note command defines a new paragraph preceded by "Note:"
- in bold.
-
- \target tableofcontents-command
- \section1 \\tableofcontents
-
- The \\tableofcontents command has been disabled because QDoc
- now generates a table of contents automatically.
-
- The automatically generated table of contents appears in the upper
- righthand corner of the page.
-
- \target brief-command
- \section1 \\brief
-
- The \\brief command introduces a one-sentence description of a
- class, namespace, header file, property, or variable.
-
- The brief text is used to introduce the documentation of the
- associated object, and in lists generated using the \l
- {generatelist-command} {\\generatelist} command and the \l
- {annotatedlist-command} {\\annotatedlist} command.
-
- The \\brief command can be used in two significant different ways:
- \l {brief class} {One for classes, namespaces and header files},
- and \l {brief-property} {one for properties and variables}.
-
- \target brief-property
-
- When the \\brief command is used to describe a property or a
- variable, the brief text must be a sentence fragment starting with
- "whether" (for a boolean property or variable) or starting with
- "the" (for any other property or variable).
-
- For example the boolean QWidget::isWindow property:
-
- \code
- / *!
- \property QWidget::isActiveWindow
- \brief Whether this widget's window is the active window
-
- The active window is the window that contains the widget that
- has keyboard focus.
-
- When popup windows are visible, this property is true
- for both the active window \e and the popup.
-
- \sa activateWindow(), QApplication::activeWindow()
- * /
- \endcode
-
- and the QWidget::geometry property
-
- \code
- / *!
- \property QWidget::geometry
- \brief The geometry of the widget relative to its parent and
- excluding the window frame
-
- When changing the geometry, the widget, if visible,
- receives a move event (moveEvent()) and/or a resize
- event (resizeEvent()) immediately.
-
- ...
-
- \sa frameGeometry(), rect(), ...
- * /
- \endcode
-
- QDoc renders this as:
-
- \quotation
- \raw HTML
- <h3>geometry :
- <a href="http://qt-project.org/doc/qt-5.0/qtcore/qrect.html">QRect</a>
- </h3>
- \endraw
-
- This property holds the geometry of the widget relative
- to its parent and excluding the window frame.
-
- ...
-
- Access functions:
- \list
- \li \b {const QRect & geometry () const}
- \li \b {void setGeometry ( int x, int y, int w, int h )}
- \li \b {void setGeometry ( const QRect & )}
- \endlist
-
- See also \l
- {QWidget::frameGeometry()} {frameGeometry()}, \l
- {QWidget::rect()} {rect()}, ...
- \endquotation
-
- \target brief class
-
- When the \\brief command is used to describe a class, the brief
- text should be a complete sentence and must start like this:
-
- \code
- The <classname> class is|provides|contains|specifies...
- \endcode
-
- \warning The brief statement is used as the first paragraph of the
- detailed description. Do not repeat the sentence.
-
- \code
- / *!
- \class PreviewWindow
- \brief The PreviewWindow class is a custom widget
- displaying the names of its currently set
- window flags in a read-only text editor.
-
- The PreviewWindow class inherits QWidget. The widget
- displays the names of its window flags set with the
- setWindowFlags() function. It is also provided with a
- QPushButton that closes the window.
-
- ...
-
- \sa QWidget
- * /
- \endcode
-
- QDoc renders this as:
-
- \quotation
- \raw HTML
- <h1>PreviewWindow Class Reference</h1>
- \endraw
-
- The PreviewWindow class is a custom widget displaying
- the names of its currently set window flags in a
- read-only text editor. \l {preview window} {More...}
-
- \raw HTML
- <h3>Properties</h3>
- \endraw
-
- \list
- \li 52 properties inherited from QWidget
- \li 1 property inherited from QObject
- \endlist
-
- \raw HTML
- <h3>Public Functions</h3>
- \endraw
-
- \list
- \li \l {constructor} {PreviewWindow}(QWidget *parent = 0)
- \li void \l {function} {setWindowFlags}(Qt::WindowFlags flags)
- \endlist
-
- \list
- \li 183 public functions inherited from QWidget
- \li 28 public functions inherited from QObject
- \endlist
-
- \raw HTML
- <h3>Public Slots</h3>
- \endraw
-
- \list
- \li 17 public slots inherited from QWidget
- \li 1 public slot inherited from QObject
- \endlist
-
- \raw HTML
- <h3>Additional Inherited Members</h3>
- \endraw
-
- \list
- \li 1 signal inherited from QWidget
- \li 1 signal inherited from QObject
- \li 4 static public members inherited from QWidget
- \li 4 static public members inherited from QObject
- \li 39 protected functions inherited from QWidget
- \li 7 protected functions inherited from QObject
- \endlist
-
- \target preview window
-
- \raw HTML
- <hr />
- <h2>Detailed Description</h2>
- \endraw
-
- The PreviewWindow class is a custom widget displaying
- the names of its currently set window flags in a
- read-only text editor.
-
- The PreviewWindow class inherits QWidget. The widget
- displays the names of its window flags set with the \l
- {function} {setWindowFlags()} function. It is also
- provided with a QPushButton that closes the window.
-
- ...
-
- See also QWidget.
-
- \raw HTML
- <hr />
- <h2>Member Function Documentation</h2>
- \endraw
-
- \target constructor
- \raw HTML
- <h3>PreviewWindow(QWidget *parent = 0)</h3>
- \endraw
-
- Constructs a preview window widget with \e parent.
-
- \target function
- \raw HTML
- <h3>setWindowFlags(Qt::WindowFlags flags)</h3>
- \endraw
-
- Sets the widgets flags using the
- QWidget::setWindowFlags() function.
-
- Then runs through the available window flags,
- creating a text that contains the names of the flags
- that matches the flags parameter, displaying
- the text in the widgets text editor.
- \endquotation
-
- Using \\brief in a \l{namespace-command}{\\namespace}:
-
- \code
- / *!
- \namespace Qt
-
- \brief The Qt namespace contains miscellaneous identifiers
- used throughout the Qt library.
- * /
- \endcode
-
- Using \\brief in a \l{headerfile-command}{\\headerfile}:
-
- \code
- / *!
- \headerfile <QtGlobal>
- \title Global Qt Declarations
-
- \brief The <QtGlobal> header file provides basic
- declarations and is included by all other Qt headers.
-
- \sa <QtAlgorithms>
- * /
- \endcode
-
- See also \l{property-command} {\\property}, \l{class-command}
- {\\class}, \l{namespace-command} {\\namespace} and
- \l{headerfile-command} {\\headerfile}.
-
- \target legalese-command
- \section1 \\legalese
-
- The \\legalese and \\endlegalese commands delimit a license agreement.
-
- In the generated HTML, the delimited text is surrounded by a \b
- {<div class="LegaleseLeft">} and \b {</div>} tags.
-
- An example of a license agreement enclosed in \\legalese
- and \\endlegalese:
-
- \code
- / *!
- \legalese
- Copyright 1996 Daniel Dardailler.
-
- Permission to use, copy, modify, distribute, and sell this
- software for any purpose is hereby granted without fee,
- provided that the above copyright notice appear in all
- copies and that both that copyright notice and this
- permission notice appear in supporting documentation, and
- that the name of Daniel Dardailler not be used in
- advertising or publicity pertaining to distribution of the
- software without specific, written prior permission. Daniel
- Dardailler makes no representations about the suitability of
- this software for any purpose. It is provided "as is"
- without express or implied warranty.
-
- Modifications Copyright 1999 Matt Koss, under the same
- license as above.
- \endlegalese
- * /
- \endcode
-
- It will appear in the generated HTML as:
-
- \code
- <div class="LegaleseLeft">
- <p>Copyright 1996 Daniel Dardailler.</p>
- <p>Permission to use, copy, modify, distribute, and sell
- this software for any purpose is hereby granted without fee,
- provided that the above copyright notice appear in all
- copies and that both that copyright notice and this
- permission notice appear in supporting documentation, and
- that the name of Daniel Dardailler not be used in
- advertising or publicity pertaining to distribution of the
- software without specific, written prior permission. Daniel
- Dardailler makes no representations about the suitability of
- this software for any purpose. It is provided "as is"
- without express or implied warranty.</p>
-
- <p>Modifications Copyright 1999 Matt Koss, under the same
- license as above.</p>
- </div>
- \endcode
-
- If the \\endlegalese command is omitted, QDoc will process the
- \\legalese command but considers the rest of the documentation
- page as the license agreement.
-
- Ideally, the license text is located with the licensed code.
-
- Elsewhere, the documentation identified as \e{\\legalese} command
- can be accumulated using \l {generatelist-command} {\\generatelist}
- with \c {legalese-command} as the argument. This is useful for
- generating an overview of the license agreements associated with
- the source code.
-
- \target warning-command
- \section1 \\warning
-
- The \\warning command prepends "Warning:" to the command's
- argument, in bold font.
-
- \code
- / *!
- Qt::HANDLE is a platform-specific handle type
- for system objects. This is equivalent to
- \c{void *} on Windows and Mac OS X, and to
- \c{unsigned long} on X11.
-
- \warning Using this type is not portable.
- * /
- \endcode
-
- QDoc renders this as:
-
- \quotation
- Qt::HANDLE is a platform-specific handle type
- for system objects. This is equivalent to
- \c{void *} on Windows and Mac OS X, and to
- \c{unsigned long} on X11.
-
- \warning Using this type is not portable.
- \endquotation
-
-*/
-
-/*!
- \page 12-0-qdoc-commands-miscellaneous.html
- \previouspage Special Content
- \contentspage QDoc Manual
- \nextpage Creating DITA Maps
-
- \title Miscellaneous
-
- These commands provide miscellaneous functions connected to the
- visual appearance of the documentation, and to the process of
- generating the documentation.
-
- \target annotatedlist-command
- \section1 \\annotatedlist
-
- The \\annotatedlist command expands to a list of the members of a
- group, each member listed with its \e {brief} text. Below is an
- example from the Qt Reference Documentation:
-
- \code
- / *!
- ...
- \section1 Drag and Drop Classes
-
- These classes deal with drag and drop and the necessary mime type
- encoding and decoding.
-
- \annotatedlist draganddrop
-
- * /
- \endcode
-
- This generates a list of all the C++ classes and/or QML types in
- the \e{draganddrop} group. A C++ class or QML type in the
- \e{draganddrop} group will have \e{\\ingroup draganddrop} in its
- \e{\\class} or \e{\\qmltype} comment.
-
-
- \target generatelist-command
- \section1 \\generatelist
-
- The \\generatelist command expands to a list of various
- documentation or links to documentation. Below is an example from
- the Qt Reference Documentation:
-
- \code
- / *!
- \page classes.html
- \title All Classes
-
- For a shorter list that only includes the most
- frequently used classes, see \l{Qt's Main Classes}.
-
- \generatelist classes
- * /
- \endcode
-
- This generates the \l {All Classes} page. The command accepts the
- following arguments:
-
- \target table example
- \section2 \c annotatedclasses
-
- The \c annotatedclasses argument provides a table containing the
- names of all the classes, and a description of each class. Each
- class name is a link to the class's reference documentation. For
- example:
-
- \table
- \row
- \li QDial
- \li Rounded range control (like a speedometer or potentiometer)
- \row
- \li QDialog
- \li The base class of dialog windows
- \row
- \li QDir
- \li Access to directory structures and their contents
- \endtable
-
- A C++ class is documented with the \l {class-command} {\\class}
- command. The annotation for the class is taken from the argument
- of the class comment's \l {brief-command} {\\brief} command.
-
- \target list example
- \section2 \c classes
-
- The \c classes argument provides a complete alphabetical list of
- the classes. Each class name is a link to the class's reference
- documentation. This command is used to generate the \l
- {classes.html} {All Classes} page this way:
-
- \code
- / *!
- \page classes.html
- \title All Classes
- \ingroup classlists
-
- \brief Alphabetical list of classes.
-
- This is a list of all Qt classes. For a list of the classes
- provided for compatibility with Qt3, see \l{Qt3 Support
- Classes}. For classes that have been deprecated, see the
- \l{Obsolete Classes} list.
-
- \generatelist classes
- * /
- \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.
-
- This command is used to generate the \l {phonon-module.html}
- {Phonon Module} page this way.
-
- \code
- / *!
- \page phonon-module.html
- \module Phonon
- \title Phonon Module
- \ingroup modules
-
- \brief Contains namespaces and classes for multimedia functionality.
-
- \generatelist{classesbymodule Phonon}
-
- ...
-
- * /
- \endcode
-
- Each class that is a member of the specified module must be marked
- with the \l {inmodule-command} {\\inmodule} command in its \\class
- comment.
-
- \section2 \c compatclasses
-
- The \c compatclasses argument generates a list in alphabetical
- order of the support classes. It is normally used only to
- generate the \l {compatclasses.html} {Qt3 Support Classes} page
- this way:
-
- \code
- / *!
- \page compatclasses.html
- \title Qt3 Support Classes
- \ingroup classlists
-
- \brief Enable porting of code from Qt 3 to Qt 4.
-
- These are the classes that Qt provides for compatibility with Qt
- 3. Most of these are provided by the Qt3Support module.
-
- \generatelist compatclasses
- * /
- \endcode
-
- A support class is identified in the \\class comment with the \l
- {compat-command} {\\compat} command.
-
- \section2 \c functionindex
-
- The \c functionindex argument provides a complete alphabetical
- list of all the documented member functions. It is normally used
- only to generate the \l {functions.html} {Qt function index} page
- this way:
-
- \code
- / *!
- \page functions.html
- \title All Functions
- \ingroup funclists
-
- \brief All documented Qt functions listed alphabetically with a
- link to where each one is declared.
-
- This is the list of all documented member functions and global
- functions in the Qt API. Each function has a link to the
- class or header file where it is declared and documented.
-
- \generatelist functionindex
- * /
- \endcode
-
- \section2 \c legalese
-
- The \c legalese argument tells QDoc to generate a complete list of
- licenses in the documentation. Each license is identified using
- the \l {legalese-command} {\\legalese} command. This command is
- used to generate the \l {licenses.html} {Qt license information}
- page this way:
-
- \code
- / *!
- \page licenses.html
- \title Other Licenses Used in Qt
- \ingroup licensing
- \brief Information about other licenses used for Qt components and third-party code.
-
- Qt contains some code that is not provided under the
- \l{GNU General Public License (GPL)},
- \l{GNU Lesser General Public License (LGPL)} or the
- \l{Qt Commercial Edition}{Qt Commercial License Agreement}, but rather under
- specific licenses from the original authors. Some pieces of code were developed
- by Digia and others originated from third parties.
- This page lists the licenses used, names the authors, and links
- to the places where it is used.
-
- Digia gratefully acknowledges these and other contributions
- to Qt. We recommend that programs that use Qt also acknowledge
- these contributions, and quote these license statements in an
- appendix to the documentation.
-
- See also: \l{Licenses for Fonts Used in Qt for Embedded Linux}
-
- \generatelist legalese
- * /
- \endcode
-
- \section2 \c mainclasses
-
- The \c mainclasses argument tells QDoc to generate an alphabetical
- list of the main classes. A class is marked as a main class by
- including a \l {mainclass-command} {\\mainclass} command in the
- \\class comment.
-
- \note The Qt documentation no longer includes a main classes page,
- but you can generate one for your main classes if you want it.
-
- \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 \l {overviews.html}
- {overviews} page this way:
-
- \code
- / *!
- \page overviews.html
-
- \title All Overviews and HOWTOs
-
- \generatelist overviews
- * /
- \endcode
-
- \section2 \c related
-
- The \c related argument is used in combination with the \l
- {group-command} {\\group} and \l {ingroup-command} {\\ingroup}
- commands to list all the overviews related to a specified
- group. For example, the page for the \l {Programming with Qt}
- {Programming with Qt} page is generated this way:
-
- \code
- / *!
- \group qt-basic-concepts
- \title Programming with Qt
-
- \brief The basic architecture of the Qt cross-platform application and UI framework.
-
- Qt is a cross-platform application and UI framework for
- writing web-enabled applications for desktop, mobile, and
- embedded operating systems. This page contains links to
- articles and overviews explaining key components and
- techniuqes used in Qt development.
-
- \generatelist {related}
- * /
- \endcode
-
- Each page listed on this group page contains the command:
-
- \code
- \ingroup qt-basic-concepts
- \endcode
-
- \section2 \c service
-
- The \c service argument tells QDoc to generate an alphabetical
- list of the services. Each service name is a link to the service's
- reference documentation.
-
- A service is identified with the \l {service-command} {\\service}
- command.
-
- \note This command and the \l {service-command} {\\service}
- command are not used in the Qt documentation.
-
- \target if-command
- \section1 \\if
-
- The \\if command and the corresponding \\endif command
- enclose parts of a QDoc comment that only will be included if
- the condition specified by the command's argument is true.
-
- The command reads the rest of the line and parses it as an C++ #if
- statement.
-
- \code
- / *!
- \if defined(opensourceedition)
-
- \b{Note:} This edition is for the development of
- \l{Qt Open Source Edition} {Free and Open Source}
- software only; see \l{Qt Commercial Editions}.
-
- \endif
- * /
- \endcode
-
- This QDoc comment will only be rendered if the \c
- opensourceedition preprocessor symbol is defined, and specified in
- the \l {defines-variable} {defines} variable in the configuration
- file to make QDoc process the code within #ifdef and #endif:
-
- \code
- defines = opensourceedition
- \endcode
-
- You can also define the preprocessor symbol manually on the
- command line. For more information see the documentation of the \l
- {defines-variable} {defines} variable.
-
- See also \l{endif-command} {\\endif}, \l{else-command} {\\else},
- \l {defines-variable} {defines} and \l {falsehoods-variable}
- {falsehoods}.
-
- \target endif-command
- \section1 \\endif
-
- The \\endif command and the corresponding \\if command
- enclose parts of a QDoc comment that will be included if
- the condition specified by the \l {if-command} {\\if} command's
- argument is true.
-
- For more information, see the documentation of the \l {if-command}
- {\\if} command.
-
- See also \l{if-command} {\\if}, \l{else-command} {\\else}, \l
- {defines-variable} {defines} and \l {falsehoods-variable}
- {falsehoods}.
-
- \target else-command
- \section1 \\else
-
- The \\else command specifies an alternative if the
- condition in the \l {if-command} {\\if} command is false.
-
- The \\else command can only be used within \l {if-command}
- {\\if...\\endif} commands, but is useful when there is only two
- alternatives.
-
- \code
- / *!
- The Qt 3 support library is provided to keep old
- source code working.
-
- In addition to the \c Qt3Support classes, Qt 4 provides
- compatibility functions when it's possible for an old
- API to cohabit with the new one.
-
- \if !defined(QT3_SUPPORT)
- \if defined(QT3_SUPPORTWARNINGS)
- The compiler emits a warning when a
- compatibility function is called. (This works
- only with GCC 3.2+ and MSVC 7.)
- \else
- To use the Qt 3 support library, you need to
- have the line QT += qt3support in your .pro
- file (qmake automatically define the
- QT3_SUPPORT symbol, turning on compatibility
- function support).
-
- You can also define the symbol manually (for example,
- if you don't want to link against the \c
- Qt3Support library), or you can define \c
- QT3_SUPPORT_WARNINGS instead, telling the
- compiler to emit a warning when a compatibility
- function is called. (This works only with GCC
- 3.2+ and MSVC 7.)
- \endif
- \endif
- * /
- \endcode
-
- If the \c QT3_SUPPORT is defined, the comment will be rendered
- like this:
-
- \quotation
- The Qt 3 support library is provided to keep old source
- code working.
-
- In addition to the Qt3Support classes, Qt 4 provides
- compatibility functions when it's possible for an old
- API to cohabit with the new one.
- \endquotation
-
- If \c QT3_SUPPORT is not defined but \c QT3_SUPPORT_WARNINGS is
- defined, the comment will be rendered like this:
-
- \quotation
- The Qt 3 support library is provided to keep old source
- code working.
-
- In addition to the Qt3Support classes, Qt 4 provides
- compatibility functions when it's possible for an old
- API to cohabit with the new one.
-
- The compiler emits a warning when a compatibility
- function is called. (This works only with GCC 3.2+ and
- MSVC 7.)
- \endquotation
-
- If none of the symbols are defined, the comment will be
- rendered as
-
- \quotation
- The Qt 3 support library is provided to keep old
- source code working.
-
- In addition to the \c Qt3Support classes, Qt 4 provides
- compatibility functions when it's possible for an old
- API to cohabit with the new one.
-
- To use the Qt 3 support library, you need to have the
- line QT += qt3support in your .pro file (qmake
- automatically define the QT3_SUPPORT symbol, turning on
- compatibility function support).
-
- You can also define the symbol manually (e.g., if you
- don't want to link against the \c Qt3Support library),
- or you can define \c QT3_SUPPORT_WARNINGS instead,
- telling the compiler to emit a warning when a
- compatibility function is called. (This works only with
- GCC 3.2+ and MSVC 7.)
- \endquotation
-
- See also \l{if-command} {\\if}, \l{endif-command} {\\endif}, \l
- {defines-variable} {defines} and \l {falsehoods-variable}
- {falsehoods}.
-
- \target include-command
- \section1 \\include
-
- The \\include command sends all or part of the file specified by
- its first argument to the QDoc input stream to be processed as a
- QDoc comment snippet. This command is often assigned the alias,
- \e {input}, in the QDoc configuration file, for example \e {alias.include
- = input}.
-
- The command is useful when some snippet of commands and text is to
- be used in multiple places in the documentation. In that case,
- move the snippet into a separate file and use the \\include
- command wherever you want to insert the snippet into the
- documentation. To prevent QDoc from reading the file as a
- stand-alone page of documentation, we recommend that you use the
- \c .qdocinc extension for these \e {include} files.
-
- The command can have either one or two arguments. The first
- argument is always a file name. The contents of the file must be
- QDoc input, in other words, a sequence of QDoc commands and text, but
- without the enclosing QDoc comment \c{/}\c{*!} ... \c{*}\c{/} delimiters.
- If you want to include the entire named file, don't use the second
- argument. If you want to include only part of the file, see the
- \l{2-argument-form}{two argument form} below. Here is an example
- of the one argument form:
-
- \code
- / *!
- \page corefeatures.html
- \title Core Features
-
- \include examples/signalandslots.qdocinc
- \include examples/objectmodel.qdocinc
- \include examples/layoutmanagement.qdocinc
- * /
- \endcode
-
- Here are links to the \c .qdocinc files used above:
- \l{signalandslots.qdocinc}, \l{objectmodel.qdocinc},
- \l{layoutmanagement.qdocinc}. QDoc renders this page
- \l{corefeatures.html} {as shown here}.
-
- \target 2-argument-form}
- \section2 \\include filename snippet-identifier
-
- It is a waste of time to make a separate \c .qdocinc file for every
- QDoc include snippet you want to use in multiple places in the
- documentation, especially given that you probably have to put the
- copyright/license notice in every one of these files. So if you
- have a large number of snippets to be included, you can put them all in a
- single file if you want, and surround each one with:
- \code
- //! [snippet-id1]
-
- QDoc commands and text...
-
- //! [snippet-id1]
-
- //! [snippet-id2]
-
- More QDoc commands and text...
-
- //! [snippet-id2]
- \endcode
-
- Then you can use the two-argument form of the command:
-
- \code
- \input examples/signalandslots.qdocinc snippet-id2
- \input examples/objectmodel.qdocinc another-snippet-id
- \endcode
-
- It works as expected. The sequence of QDoc commands and text found
- between the two tags with the same name as the second argument is
- sent to the QDoc input stream. You can even nest these snippets,
- although it's not clear why you would want to do that.
-
- \target meta-command
- \section1 \\meta
-
- The \\meta command is mainly used for including metadata in DITA
- XML files. It is also used when generating HTML output for specifying
- the \e maintainer(s) of a C++ class.
-
- The command has two arguments: the first argument is the name of the
- metadata attribute, and the second argument is the
- value for the attribute. Each argument should be enclosed in curly
- brackets, as shown in this example:
-
- \code
- / *!
- \class QWidget
- \brief The QWidget class is the base class of all user interface objects.
-
- \ingroup basicwidgets
-
- \meta {technology} {User Interface}
- \meta {platform} {OS X 10.6}
- \meta {platform} {Symbian}
- \meta {platform} {MeeGo}
- \meta {audience} {user}
- \meta {audience} {programmer}
- \meta {audience} {designer}
- * /
- \endcode
-
- When running QDoc to generate HTML, the example above will have no
- effect on the generated output, but if you run QDoc to generate
- DITA XML, the example will generate the following:
-
- \code
- <?xml version="1.0" encoding="UTF-8"?>
- <!DOCTYPE cxxClass PUBLIC "-//NOKIA//DTD DITA C++ API Class Reference Type v0.6.0//EN" "dtd/cxxClass.dtd">
- <!--qwidget.cpp-->
- <cxxClass id="id-9a14268e-6b09-4eee-b940-21a00a0961df">
- <apiName>QWidget</apiName>
- <shortdesc>the QWidget class is the base class of all user interface objects.</shortdesc>
- <prolog>
- <author>Qt Development Frameworks</author>
- <publisher>Qt Project</publisher>
- <copyright>
- <copyryear year="2013"/>
- <copyrholder>Qt Project</copyrholder>
- </copyright>
- <permissions view="all"/>
- <metadata>
- <audience type="designer"/>
- <audience type="programmer"/>
- <audience type="user"/>
- <category>Class reference</category>
- <prodinfo>
- <prodname>Qt Reference Documentation</prodname>
- <vrmlist>
- <vrm version="4" release="7" modification="3"/>
- </vrmlist>
- <component>QtGui</component>
- </prodinfo>
- <othermeta name="platform" content="MeeGo"/>
- <othermeta name="platform" content="Symbian"/>
- <othermeta name="platform" content="OS X 10.6"/>
- <othermeta name="technology" content="User Interface"/>
- </metadata>
- </prolog>
- \endcode
-
- In the example output, several values have been set using default
- values obtained from the QDoc configuration file. See \l
- {Generating DITA XML Output} for details.
-
- \target omit-command
- \section1 \\omit
-
- The \\omit command and the corresponding \\endomit command
- delimit parts of the documentation that you want QDoc to skip. For
- example:
-
- \code
- / *!
- \table
- \row
- \li Basic Widgets
- \li Basic GUI widgets such as buttons, comboboxes
- and scrollbars.
-
- \omit
- \row
- \li Component Model
- \li Interfaces and helper classes for the Qt
- Component Model.
- \endomit
-
- \row
- \li Database Classes
- \li Database related classes, e.g. for SQL databases.
- \endtable
- * /
- \endcode
-
- QDoc renders this as:
-
- \raw HTML
- <table align="center" cellpadding="2"
- cellspacing="1" border="0">
-
- <tr valign="top" bgcolor="#d0d0d0">
- <td>Basic Widgets</td>
- <td>Basic GUI widgets such as buttons, comboboxes
- and scrollbars.</td>
- </tr>
-
- <tr valign="top" bgcolor="#c0c0c0">
- <td>Database Classes</td>
- <td>Database related classes, e.g. for SQL databases.</td>
- </tr>
- </table>
- \endraw
-
- \target raw-command
- \section1 \\raw \span {class="newStuff"} {(avoid)}
-
- The \\raw command and the corresponding
- \\endraw command delimit a block of raw mark-up language code.
-
- \note Avoid using this command if possible, because it generates
- DITA XML code that causes problems. If you are trying to generate
- special table or list behavior, try to get the behavior you want
- using the \l {span-command} {\\span} and \l {div-command} {\\div}
- commands in your \l {table-command} {\\table} or \l {list-command}
- {\\list}.
-
- The command takes an argument specifying the code's format.
- Currently, the only supported format is HTML.
-
- The \\raw command is useful if you want some special HTML effects
- in your documentation.
-
- \code
- / *!
- Qt has some predefined QColor objects.
-
- \raw HTML
- <style type="text/css" id="colorstyles">
- #color-blue { background-color: #0000ff; color: #ffffff }
- #color-darkBlue { background-color: #000080; color: #ffffff }
- #color-cyan { background-color: #00ffff; color: #000000 }
- </style>
-
- <p>
- <tt id="color-blue">Blue(#0000ff)</tt>,
- <tt id="color-darkBlue">dark blue(#000080)</tt> and
- <tt id="color-cyan">cyan(#00ffff)</tt>.
- </p>
- \endraw
- * /
- \endcode
-
- QDoc renders this as:
-
- \quotation
- Qt has some predefined QColor objects.
-
- \raw HTML
- <style type="text/css" id="colorstyles">
- #color-blue { background-color: #0000ff; color: #ffffff }
- #color-darkBlue { background-color: #000080; color: #ffffff }
- #color-cyan { background-color: #00ffff; color: #000000 }
- </style>
-
- <p>
- <tt id="color-blue">Blue(#0000ff)</tt>,
- <tt id="color-darkBlue">dark blue(#000080)</tt> and
- <tt id="color-cyan">cyan(#00ffff)</tt>.
- </p>
- \endraw
- \endquotation
-
- \note But you can achieve the exact same thing using qdoc
- commands. In this case, all you have to do is include the color
- styles in your style.css file. Then you can write:
-
- \code
- \tt {\span {id="color-blue"} {Blue(#0000ff)}},
- \tt {\span {id="color-darkBlue"} {dark blue(#000080)}} and
- \tt {\span {id="color-cyan"} {cyan(#00ffff)}}.
- \endcode
-
- ...which is rendered as:
-
- \tt {\span {id="color-blue"} {Blue(#0000ff)}},
- \tt {\span {id="color-darkBlue"} {dark blue(#000080)}} and
- \tt {\span {id="color-cyan"} {cyan(#00ffff)}}.
-
- \target unicode-command
- \section1 \\unicode
-
- The \\unicode command allows you to insert an arbitrary Unicode
- character in the document.
-
- The command takes an argument specifying the character as an
- integer. By default, base 10 is assumed, unless a '0x' or '0'
- prefix is specified (for base 16 and 8, respectively). For
- example:
-
- \code
- O G\unicode{0xEA}nio e as Rosas
-
- \unicode 0xC0 table en famille avec 15 \unicode 0x20AC par jour
-
- \unicode 0x3A3 \e{a}\sub{\e{i}}
- \endcode
-
- QDoc renders this as:
-
- \quotation
- O G\unicode{0xEA}nio e as Rosas
-
- \unicode 0xC0 table en famille avec 15 \unicode 0x20AC par jour
-
- \unicode 0x3A3 \e{a}\sub{\e{i}}
- \endquotation
-*/
-
-/*!
- \page 12-1-signalandslots.html
- \previouspage Miscellaneous
- \contentspage QDoc Manual
-
- \title signalandslots.qdocinc
-
- \quotefile examples/signalandslots.qdocinc
-*/
-
-/*!
- \page 12-2-objectmodel.html
- \previouspage Miscellaneous
- \contentspage QDoc Manual
-
- \title objectmodel.qdocinc
-
- \quotefile examples/objectmodel.qdocinc
-*/
-
-/*!
- \page 12-3-layoutmanagement.html
- \previouspage Miscellaneous
- \contentspage QDoc Manual
-
- \title layoutmanagement.qdocinc
-
- \quotefile examples/layoutmanagement.qdocinc
-*/
-
-/*!
- \page 13-qdoc-commands-topics.html
- \previouspage Command Index
- \contentspage QDoc Manual
- \nextpage Context Commands
-
- \title Topic Commands
-
- A topic command tells QDoc which source code element is being
- documented. Some topic commands allow you to create documentation
- pages that aren't tied to any underlying source code element.
-
- When QDoc processes a QDoc comment, it tries to connect the
- comment to an element in the source code by first looking for a
- topic command that names the source code element. If there is no
- topic command, QDoc tries to connect the comment to the source
- code element that immediately follows the comment. If it can't do
- either of these and if there is no topic command that indicates
- the comment does not have an underlying source code element (e.g.
- \l{page-command} {\\page}), then the comment is discarded.
-
- \target topic argument
-
- The name of the entity being documented is usually the only
- argument for a topic command. Use the complete name. Sometimes
- there can be a second parameter in the argument. See e.g. \l
- {page-command} {\\page}.
-
- \code
- \enum QComboBox::InsertPolicy
- \endcode
-
- The \l {fn-command} {\\fn} command is a special case. For the \l
- {fn-command} {\\fn} command, use the function's signature
- including the class qualifier.
-
- \code
- \fn void QGraphicsWidget::setWindowFlags(Qt::WindowFlags wFlags)
- \endcode
-
- A topic command can appear anywhere in a comment but must stand
- alone on its own line. It is good practice is to let the topic command
- be the first line of the comment. If the argument spans several
- lines, make sure that each line (except the last one) is ended
- with a backslash. Moreover, QDoc counts parentheses, which means
- that if it encounters a '(' it considers everything until the
- closing ')' as its argument.
-
- If a topic command is repeated with different arguments, the
- same documentation will appear for both the units.
-
- \code
- / *!
- \fn void PreviewWindow::setWindowFlags()
- \fn void ControllerWindow::setWindowFlags()
-
- Sets the widgets flags using the QWidget::setWindowFlags()
- function.
-
- Then runs through the available window flags, creating a text
- that contains the names of the flags that matches the flags
- parameter, displaying the text in the widgets text editor.
- * /
- \endcode
-
- The \c PreviewWindow::setWindowFlags() and \c
- ControllerWindow::setWindowFlags() functions will get the same
- documentation.
-
- \target class-command
- \section1 \\class
-
- The \\class command is for documenting a C++ class. The argument
- is the complete name of the class. The command tells QDoc that a
- class is part of the public API, and lets you enter a detailed
- description.
-
- \code
- / *!
- \class QMap::iterator
-
- \brief The QMap::iterator class provides an STL-style
- non-const iterator for QMap and QMultiMap.
-
- QMap features both \l{STL-style iterators} and
- \l{Java-style iterators}. The STL-style iterators ...
- * /
- \endcode
-
- The HTML documentation for the named class is written to a
- \c{.html} file named from the class name, in lower case, and with
- the double colon qualifier(s) replaced with '-'. For example, the
- documentation for the \c QMap::Iterator class is written to \c
- qmap-iterator.html.
-
- \target framework
-
- The file contains the class description from the \\class comment,
- plus the documentation generated from QDoc comments for all the
- class members: a list of the class's types, properties,
- functions, signals, and slots.
-
- In addition to the detailed description of the class, the \\class
- comment typically contains a \l {brief-command} {\\brief} command
- and one or more \l{Markup Commands}. See the \\class command for
- any of the Qt class for examples. Here is a very simple example:
-
- \code
- / *!
- \class PreviewWindow
- \brief The PreviewWindow class is a custom widget.
- displaying the names of its currently set
- window flags in a read-only text editor.
-
- \ingroup miscellaneous
-
- The PreviewWindow class inherits QWidget. The widget
- displays the names of its window flags set with the \l
- {function} {setWindowFlags()} function. It is also
- provided with a QPushButton that closes the window.
-
- ...
-
- \sa QWidget
- * /
- \endcode
-
- The way QDoc renders this \\class will depend a lot on your \c
- {style.css} file, but the general outline of the class reference
- page will look like this:
-
- \quotation
- \raw HTML
- <h1>PreviewWindow Class Reference</h1>
- \endraw
-
- The PreviewWindow class is a custom widget displaying
- the names of its currently set window flags in a
- read-only text editor. \l {preview window} {More...}
-
- \raw HTML
- <h3>Properties</h3>
- \endraw
-
- \list
- \li 52 properties inherited from QWidget
- \li 1 property inherited from QObject
- \endlist
-
- \raw HTML
- <h3>Public Functions</h3>
- \endraw
-
- \list
- \li \l {constructor} {PreviewWindow}(QWidget *parent = 0)
- \li void \l {function} {setWindowFlags}(Qt::WindowFlags flags)
- \endlist
-
- \list
- \li 183 public functions inherited from QWidget
- \li 28 public functions inherited from QObject
- \endlist
-
- \raw HTML
- <h3>Public Slots</h3>
- \endraw
-
- \list
- \li 17 public slots inherited from QWidget
- \li 1 public slot inherited from QObject
- \endlist
-
- \raw HTML
- <h3>Additional Inherited Members</h3>
- \endraw
-
- \list
- \li 1 signal inherited from QWidget
- \li 1 signal inherited from QObject
- \li 4 static public members inherited from QWidget
- \li 4 static public members inherited from QObject
- \li 39 protected functions inherited from QWidget
- \li 7 protected functions inherited from QObject
- \endlist
-
- \target preview window
-
- \raw HTML
- <hr />
- <h2>Detailed Description</h2>
- \endraw
-
- The PreviewWindow class is a custom widget displaying
- the names of its currently set window flags in a
- read-only text editor.
-
- The PreviewWindow class inherits QWidget. The widget
- displays the names of its window flags set with the \l
- {function} {setWindowFlags()} function. It is also
- provided with a QPushButton that closes the window.
-
- ...
-
- See also QWidget.
-
- \raw HTML
- <hr />
- <h2>Member Function Documentation</h2>
- \endraw
-
- \target constructor
- \raw HTML
- <h3>PreviewWindow(QWidget *parent = 0)</h3>
- \endraw
-
- Constructs a preview window widget with \e parent.
-
- \target function
- \raw HTML
- <h3>setWindowFlags(Qt::WindowFlags flags)</h3>
- \endraw
-
- Sets the widgets flags using the
- QWidget::setWindowFlags() function.
-
- Then runs through the available window flags,
- creating a text that contains the names of the flags
- that matches the flags parameter, displaying
- the text in the widgets text editor.
- \endquotation
-
- \target enum-command
- \section1 \\enum
-
- The \\enum command is for documenting a C++ enum type. The
- argument is the full name of the enum type.
-
- The enum values are documented in the \\enum comment using the \l
- {value-command} {\\value} command. If an enum value is not
- documented with \\value, QDoc emits a warning. These warnings can
- be avoided using the \l {omitvalue-command} {\\omitvalue} command
- to tell QDoc that an enum value should not be documented. The enum
- documentation will be included on the class reference page, header
- file page, or namespace page where the enum type is defined. For
- example, consider the enum type \c {Corner} in the Qt namespace:
-
- \code
- enum Corner {
- TopLeftCorner = 0x00000,
- TopRightCorner = 0x00001,
- BottomLeftCorner = 0x00002,
- BottomRightCorner = 0x00003
- #if defined(QT3_SUPPORT) && !defined(Q_MOC_RUN)
- ,TopLeft = TopLeftCorner,
- TopRight = TopRightCorner,
- BottomLeft = BottomLeftCorner,
- BottomRight = BottomRightCorner
- #endif
- };
- \endcode
-
- This enum can be cocumented this way:
-
- \code
- / *!
- \enum Qt::Corner
-
- This enum type specifies a corner in a rectangle:
-
- \value TopLeftCorner
- The top-left corner of the rectangle.
- \value TopRightCorner
- The top-right corner of the rectangle.
- \value BottomLeftCorner
- The bottom-left corner of the rectangle.
- \value BottomRightCorner
- The bottom-right corner of the rectangle.
-
- \omitvalue TopLeft
- \omitvalue TopRight
- \omitvalue BottomLeft
- \omitvalue BottomRight
- * /
- \endcode
-
- Note the inclusion of the namespace qualifier. QDoc will render
- this enum type in \c {qt.html} like this:
-
- \quotation
- \raw HTML
- <h3 class="fn"><a name="Corner-enum"></a>enum Qt::Corner</h3>
- <p>This enum type specifies a corner in a rectangle:</p>
-
- <table border="1" cellpadding="2" cellspacing="1" width="100%">
- <tr>
- <th width="25%">Constant</th>
- <th width="15%">Value</th>
- <th width="60%">Description</th>
- </tr>
-
- <tr>
- <td valign="top"><tt>Qt::TopLeftCorner</tt></td>
- <td align="center" valign="top"><tt>0x00000</tt></td>
- <td valign="top">The top-left corner of the rectangle.</td>
- </tr>
-
- <tr>
- <td valign="top"><tt>Qt::TopRightCorner</tt></td>
- <td align="center" valign="top"><tt>0x00001</tt></td>
- <td valign="top">The top-right corner of the rectangle.</td>
- </tr>
-
- <tr>
- <td valign="top"><tt>Qt::BottomLeftCorner</tt></td>
- <td align="center" valign="top"><tt>0x00002</tt></td>
- <td valign="top">The bottom-left corner of the rectangle.</td>
- </tr>
-
- <tr>
- <td valign="top"><tt>Qt::BottomRightCorner</tt></td>
- <td align="center" valign="top"><tt>0x00003</tt></td>
- <td valign="top">The bottom-right corner of the rectangle.</td>
- </tr>
-
- </table>
- \endraw
- \endquotation
-
- See also \l {value-command} {\\value} and \l {omitvalue-command} {\\omitvalue}.
-
- \target example-command
- \section1 \\example
-
- The \\example command is for documenting an example. The argument
- is the example's path relative to omne of the paths listed in the
- \l {exampledirs-variable} {exampledirs} variable in the QDoc
- configuration file.
-
- The documentation page will be output to \c {path-to-example}.html.
- QDoc will add a list of all the example's source files at the top
- of the page.
-
- For example, if \l {exampledirs-variable} {exampledirs} contains
- \c $QTDIR/examples/widgets/imageviewer, then
-
- \code
- / *!
- \example widgets/imageviewer
- \title ImageViewer Example
- \subtitle
-
- The example shows how to combine QLabel and QScrollArea
- to display an image.
-
- ...
- * /
- \endcode
-
- QDoc renders this example in widgets-imageviewer.html:
-
- \quotation
- \raw HTML
- <center><h1>Image Viewer Example</h1></center>
- \endraw
-
- Files:
- \list
- \li \l{http://qt-project.org/doc/qt-5.0/qtwidgets/widgets-imageviewer-imageviewer-cpp.html}
- {widgets/imageviewer/imageviewer.cpp}
- \li \l{http://qt-project.org/doc/qt-5.0/qtwidgets/widgets-imageviewer-imageviewer-h.html}
- {widgets/imageviewer/imageviewer.h}
- \li \l{http://qt-project.org/doc/qt-5.0/qtwidgets/widgets-imageviewer-main-cpp.html}
- {widgets/imageviewer/main.cpp}
- \endlist
-
- The example shows how to combine QLabel and QScrollArea
- to display an image.
-
- ...
- \endquotation
-
- \target externalpage-command
- \section1 \\externalpage
-
- The \\externalpage command assigns a title to an external URL.
-
- \code
- / *!
- \externalpage http://qt-project.org/doc/
- \title Qt Documentation Site
- * /
- \endcode
-
- This allows you to include a link to the external page in your
- documentation this way:
-
- \code
- / *!
- At the \l {Qt Documentation Site} you can find the latest
- documentation for Qt, Qt Creator, the Qt SDK and much more.
- * /
- \endcode
-
- QDoc renders this as:
-
- \quotation
- At the \l {http://qt-project.org/doc/}{Qt Documentation Site}
- you can find the latest documentation for Qt, Qt Creator, the Qt SDK
- and much more.
- \endquotation
-
- To achieve the same result without using the \\externalpage
- command, you would have to hard-code the address into your
- documentation:
-
- \code
- / *!
- At the \l {http://qt-project.org/doc/}{Qt Documentation Site}
- you can find the latest documentation for Qt, Qt Creator, the Qt SDK
- and much more.
- * /
- \endcode
-
- The \\externalpage command makes it easier to maintain the
- documentation. If the address changes, you only need to change the
- argument of the \\externalpage command.
-
- \target fn-command
- \section1 \\fn (function)
-
- The \\fn command is for documenting a function. The argument is
- the function's signature, including its return type, const-ness,
- and list of formal arguments with types. If the named function
- doesn't exist, QDoc emits a warning.
-
- \note The \\fn command is QDoc's default command: when no
- topic command can be found in a QDoc comment, QDoc tries to tie
- the documentation to the following code as if it is the
- documentation for a function. Hence, it is normally not necessary
- to include this command when documenting a function, if the
- function's QDoc comment is written immediately above the function
- implementation in the \c .cpp file. But it must be present when
- documenting an inline function in the \c .cpp file that is
- implemented in the \c .h file.
-
- \code
- / *!
- \fn bool QToolBar::isAreaAllowed(Qt::ToolBarArea area) const
-
- Returns true if this toolbar is dockable in the given
- \a area; otherwise returns false.
- * /
- \endcode
-
- QDoc renders this as:
-
- \quotation
- \raw HTML
- <h3>bool QToolBar::isAreaAllowed(Qt::ToolBarArea area) const
- </h3>
- \endraw
-
- Returns true if this toolbar is dockable in the given
- \a area; otherwise returns false.
- \endquotation
-
- See also \l {overload-command} {\\overload}.
-
- \target group-command
- \section1 \\group
-
- The \\group command creates a separate page that lists the classes
- belonging to the group. The argument is the group name.
-
- A class is included in a group by using the \l {ingroup-command}
- {\\ingroup} command. Overview pages can also be related to a group
- using the same command, but the list of overview pages must be
- requested explicitly using the \l {generatelist-command}
- {\\generatelist} command (see example below).
-
- The \\group command is typically followed by a \l {title-command}
- {\\title} command and a short introduction to the group. The
- HTML page for the group is written to a \c {.html} file put in
- <lower-case>\e{group}.html.
-
- Each class name is listed as a link to the class reference page
- followed by the text from the class's \l {brief-command} {\\brief}
- texts.
-
- \code
- / *!
- \group io
-
- \title Input/Output and Networking
-
- These classes are used to handle input and output to
- and from external devices, processes, files etc., as
- well as manipulating files and directories.
- * /
- \endcode
-
- QDoc generates a group page in \c{io.html} that will look
- like this:
-
- \quotation
- \raw HTML
-
- <h1>Input/Output and Networking</h1>
-
- <p>These classes are used to handle input and output
- to and from external devices, processes, files etc., as
- well as manipulating files and directories.</p>
-
- <p>
- <table width="100%">
- <tr valign="top" bgcolor="#e0e0e0">
- <td><b>
- <a href="http://qt-project.org/doc/qt-5.0/qtnetwork/qabstractsocket.html">QAbstractSocket</a>
- </b></td>
- <td>
- The base functionality common to all socket types
- </td></tr>
-
- <tr valign="top" bgcolor="#e0e0e0">
- <td><b>
- <a href="http://qt-project.org/doc/qt-5.0/qtcore/qbuffer.html">QBuffer</a>
- </b></td>
- <td>
- QIODevice interface for a QByteArray
- </td></tr>
-
- <tr valign="top" bgcolor="#e0e0e0">
- <td><b>
- <a href="http://qt-project.org/doc/qt-5.0/qtgui/qclipboard.html">QClipboard</a>
- </b></td>
- <td>
- Access to the window system clipboard
- </td></tr>
- </table>
- \endraw
- \endquotation
-
- Note that overview pages related to the group, must be listed
- explicitly using the \l {generatelist-command} {\\generatelist}
- command with the \c related argument.
-
- \code
- / *!
- \group architecture
-
- \title Architecture
-
- These documents describe aspects of Qt's architecture
- and design, including overviews of core Qt features and
- technologies.
-
- \generatelist{related}
- * /
- \endcode
-
- See also \l {ingroup-command} {\\ingroup} and \l
- {generatelist-command} {\\generatelist}.
-
- \target headerfile-command
- \section1 \\headerfile
-
- The \\headerfile command is for documenting the global functions,
- types and macros that are declared in a header file, but not in a
- namespace. The argument is the name of the header file. The HTML
- page is written to a \c {.html} file constructed from the header
- file argument.
-
- The documentation for a function, type, or macro that is declared
- in the header file being documented, is included in the header file
- page using the \l {relates-command} {\\relates} command.
-
- If the argument doesn't exist as a header file, the \\headerfile
- command creates a documentation page for the header file anyway.
-
- \code
- / *!
- \headerfile <QtAlgorithms>
-
- \title Generic Algorithms
-
- \brief The <QtAlgorithms> header file provides
- generic template-based algorithms.
-
- Qt provides a number of global template functions in \c
- <QtAlgorithms> that work on containers and perform
- well-know algorithms.
- * /
- \endcode
-
- QDoc generates a header file page \c{qtalgorithms.html} that looks
- like this:
-
- \quotation
- \raw HTML
- <center><h1>&lt;QtAlgorithms&gt; -
- Generic Algorithms</h1></center>
- <p>The <QtAlgorithms> header file provides generic
- template-based algorithms.
- <a href="13-qdoc-commands-topics.html#header-command">More...</a>
- </p>
-
- <h3>Functions</h3>
- <ul>
- <li>RandomAccessIterator
- <a href="http://qt-project.org/doc/qt-5.0/qtcore/qtalgorithms.html#qBinaryFind">qBinaryFind</a></b>
- (RandomAccessIterator begin, RandomAccessIterator end,
- const T & value)</li>
- <li>...</li></ul>
- <hr />
- \endraw
-
- \target header
-
- \raw HTML
- <h2>Detailed Description</h2>
- <p>The <QtAlgorithms> header file provides generic
- template-based algorithms. </p>
- \endraw
-
- Qt provides a number of global template functions in \c
- <QtAlgorithms> that work on containers and perform
- well-know algorithms.
-
- ...
- \endquotation
-
- \target macro-command
- \section1 \\macro
-
- The \\macro command is for documenting a C++ macro. The argument
- is the macro in one of three styles: function-like macros like
- Q_ASSERT(), declaration-style macros like Q_PROPERTY(), and macros
- without parentheses like Q_OBJECT.
-
- The \\macro comment must contain a \l {relates-command}
- {\\relates} command that attaches the macro comment to a class,
- header file, or namespace. Otherwise, the documentation will be
- lost. Here are three example macro comments followed by what they
- might look like in \c {qtglobal.html} or \c {qobject.html}:
-
- \code
- / *!
- \macro void Q_ASSERT(bool test)
- \relates <QtGlobal>
-
- Prints a warning message containing the source code
- file name and line number if \a test is false.
-
- ...
-
- \sa Q_ASSERT_X(), qFatal(), {Debugging Techniques}
- * /
- \endcode
-
- \quotation
- \raw HTML
- <h3>void Q_ASSERT ( bool <i>test</i> )</h3>
- \endraw
-
- Prints a warning message containing the source code
- file name and line number if \a test is false.
-
- ...
-
- See also Q_ASSERT_X(), qFatal() and \l {Debugging Techniques}.
-
- \endquotation
-
- \code
- / *!
- \macro Q_PROPERTY(...)
- \relates QObject
-
- This macro declares a QObject property. The syntax is:
-
- ...
-
- \sa {Qt's Property System}
- * /
- \endcode
-
- \quotation
- \raw HTML
- <h3>Q_PROPERTY ( ... )</h3>
- \endraw
-
- This macro declares a QObject property. The syntax is:
-
- ...
-
- See also \l {Qt's Property System}.
- \endquotation
-
- \code
- / *!
- \macro Q_OBJECT
- \relates QObject
-
- The Q_OBJECT macro must appear in the private section
- of a class definition that declares its own signals and
- slots, or that uses other services provided by Qt's
- meta-object system.
-
- ...
-
- \sa {Meta-Object System}, {Signals and Slots}, {Qt's
- Property System}
- * /
- \endcode
-
- \quotation
- \raw HTML
- <h3>Q_OBJECT</h3>
- \endraw
-
- The Q_OBJECT macro must appear in the private section
- of a class definition that declares its own signals and
- slots or that uses other services provided by Qt's
- meta-object system.
-
- ...
-
- See also \l {Meta-Object System}, \l {Signals &
- Slots} and \l {Qt's Property System}.
- \endquotation
-
- \target module-command
- \section1 \\module
-
- The \\module creates a page that lists the classes belonging to
- the module specified by the command's argument. A class included
- in the module by including the \l {inmodule-command} {\\inmodule}
- command in the \\class comment.
-
- The \\module command is typically followed by a \l {title-command}
- {\\title} and a \l {brief-command} {\\brief} command. Each class
- is listed as a link to the class reference page followed by the
- text from the class's \l {brief-command} {\\brief} command. For
- example:
-
- \code
- / *!
- \module QtNetwork
-
- \title Qt Network Module
-
- \brief Contains classes for writing TCP/IP clients and servers.
-
- The network module provides classes to make network
- programming easier and portable. It offers both
- high-level classes such as QNetworkAccessManager that
- implements application-level protocols, and
- lower-level classes such as QTcpSocket, QTcpServer, and
- QUdpSocket.
- * /
- \endcode
-
- QDoc renders this in \c {qtnetwork.html} like this:
-
- \quotation
- \raw HTML
- <h1><center>Qt Network Module</center></h1>
- \endraw
-
- The Qt Network module offers classes that allow you to
- write TCP/IP clients and servers.\l {module
- details} {More...}
-
- \raw HTML
- <p>
- <table width="100%">
- <tr valign="top" bgcolor="#d0d0d0">
- <td><b>
- <a href="http://qt-project.org/doc/qt-5.0/qtnetwork/qabstractsocket.html">QAbstractSocket</a>
- </b></td>
- <td>
- The base functionality common to all socket types
- </td></tr>
-
- <tr valign="top" bgcolor="#d0d0d0">
- <td><b>
- <a href="http://doc.qt.digia.com/4.0/qftp.html">QFtp</a>
- </b></td>
- <td>
- Implementation of the FTP protocol
- </td></tr>
-
- <tr valign="top" bgcolor="#d0d0d0">
- <td>...</td>
- <td>...</td>
- </tr>
- </table>
-
- <p><hr /></p>
- \endraw
-
- \target module details
-
- \raw HTML
- <h2>Detailed Description</h2>
-
- <p>
- The Qt Network module offers classes that allow you to
- write TCP/IP clients and servers.
- </p>
-
- <p>
- The network module provides classes to make network
- programming easier and portable. It offers both
- high-level classes such as QNetworkAccessManager that
- implements application-level protocols, and
- lower-level classes such as QTcpSocket, QTcpServer, and
- QUdpSocket.
- </p>
- \endraw
-
- ...
-
- \endquotation
-
- See also \l {inmodule-command} {\\inmodule}
-
- \target namespace-command
- \section1 \\namespace
-
- The \\namespace command is for documenting the contents of the C++
- namespace named as its argument. The documentation outline QDoc
- generates for a namespace is similar to the outline it generates
- for a C++ class.
-
- \code
- / *!
- \namespace Qt
-
- \brief Contains miscellaneous identifiers used throughout the Qt library.
- * /
- \endcode
-
- QDoc renders this in \c{qt.html} like this:
-
- \quotation
- \raw HTML
- <center><h1>Qt Namespace Reference</h1></center>
- <p>The Qt namespace contains miscellaneous
- identifiers used throughout the Qt library.
- <a href="13-qdoc-commands-topics.html#name">More...</a>
- </p>
-
- <pre>#include &lt;Qt&gt;</pre>
- <ul>
- <li>
- <a href="http://doc.qt.digia.com/4.0/qt-qt3.html">
- Qt 3 support members</a></li>
- </ul>
-
-
- <h3>Types</h3>
- <ul>
- <li>flags
- <a href="http://doc.qt.digia.com/4.0/qt.html#AlignmentFlag-enum">Alignment</a></b></li>
- <li>...</li></ul>
- <hr />
- \endraw
-
- \target name
-
- \raw HTML
- <h2>Detailed Description</h2>
- <p>Contains miscellaneous identifiers
- used throughout the Qt library.</p>
- \endraw
-
- ...
- \endquotation
-
- \target page-command
- \section1 \\page
-
- The \\page command is for creating a stand-alone documentation
- page. The argument can consist of two parts separated by a
- space. The first part is the name of the file where QDoc should
- store the page. The second part, if present, is a word that
- specifies the page type. Currently, the second part can be one of
- the following list of words:
-
- \list
-
- \li faq - A frequently asked question.
-
- \li howto - A user guide on how to use some components of the
- software.
-
- \li example - A page that describes a working example.
-
- \li overview - For text pages that provide an overview of some
- important subject.
-
- \li tutorial - For text pages that are part of a tutorial.
-
- \li api - This is the type of page used for C++ class references and
- QML type references. You should never use this one for the pages
- you write, because this one is reserved for qdoc.
-
- \endlist
-
- The page title is set using the \l {title-command} {\\title}
- command.
-
- \code
- / *!
- \page aboutqt.html
-
- \title About Qt
-
- Qt is a C++ toolkit for cross-platform GUI
- application development. Qt provides single-source
- portability across Microsoft Windows, Mac OS X, Linux,
- and all major commercial Unix variants.
-
- Qt provides application developers with all the
- functionality needed to build applications with
- state-of-the-art graphical user interfaces. Qt is fully
- object-oriented, easily extensible, and allows true
- component programming.
-
- ...
- * /
- \endcode
-
- QDoc renders this page in \c {aboutqt.html}.
-
- \target property-command
- \section1 \\property
-
- The \\property command is for documenting a Qt property. The
- argument is the full property name.
-
- A property is defined using the Q_PROPERTY() macro. The macro
- takes as arguments the property's name and its set, reset and get
- functions.
-
- \code
- Q_PROPERTY(QString state READ state WRITE setState)
- \endcode
-
- The set, reset and get functions don't need to be documented,
- documenting the property is sufficient. QDoc will generate a list
- of the access function that will appear in the property
- documentation which in turn will be located in the documentation
- of the class that defines the property.
-
- The \\property command comment typically includes a \l
- {brief-command} {\\brief} command. For properties the \l
- {brief-command} {\\brief} command's argument is a sentence
- fragment that will be included in a one line description of the
- property. The command follows the same rules for the \l
- {brief-property} {description} as the \l {variable-command}
- {\\variable} command.
-
- \code
- / *!
- \property QPushButton::flat
- \brief Whether the border is disabled.
-
- This property's default is false.
- * /
- \endcode
-
- QDoc includes this in \c {qpushbutton.html} like this:
-
- \quotation
- \raw HTML
- <h3>flat : bool</h3>
- \endraw
-
- This property holds whether the border is disabled.
-
- This property's default is false.
-
- Access functions:
-
- \list
- \li \b { bool isFlat () const}
- \li \b { void setFlat ( bool )}
- \endlist
-
- \endquotation
-
- \code
- / *!
- \property QWidget::width
- \brief The width of the widget excluding any window frame.
-
- See the \l {Window Geometry} documentation for an
- overview of window geometry.
-
- \sa geometry, height, size
- * /
- \endcode
-
- QDoc includes this in \c {qwidget.html} like this:
-
- \quotation
- \raw HTML
- <h3>width : const int</h3>
- \endraw
-
- This property holds the width of the widget excluding
- any window frame.
-
- See the \l {Window Geometry} documentation for an
- overview of window geometry.
-
- Access functions:
-
- \list
- \li \b { int width () const}
- \endlist
-
- See also \l{QWidget::geometry} {geometry},
- \l{QWidget::height} {height}, and \l{QWidget::size} {size}.
- \endquotation
-
- \target service-command
- \section1 \\service
-
- The \\service command tells QDoc that a class is a service class
- and names the service. The command takes two arguments, the name
- of the class and the name of the service. Currently, this command
- is not used in the Qt documentation.
-
- \code
- / *!
- \service TimeService Time
- ...
- * /
- class TimeService : public QCopObjectService
- {
- ...
- }
- \endcode
-
- See also \l {class-command} {\\class} and \l
- {generatelist-command} {\\generatelist}.
-
- \target qmlattachedproperty-command
- \section1 \\qmlattachedproperty
-
- The \\qmlattachedproperty command is for documenting a QML
- property that will be attached to some QML type. See
- \l{http://qt-project.org/doc/qt-4.7/qdeclarativeintroduction.html#attached-properties}
- {Attached Properties}. The argument is the rest of the line. The
- argument text should be the property type, followed by the QML
- element name where the property is being declared, the \c{::}
- qualifier, and finally the property name. If we have a QML
- attached property named \c isCurrentItem in QML \c ListView,
- and the property has type \c {bool}, the \\qmlattachedproperty for
- it would look like this:
-
- \code
- / *!
- \qmlattachedproperty bool ListView::isCurrentItem
- This attached property is true if this delegate is the current
- item; otherwise false.
-
- It is attached to each instance of the delegate.
-
- This property may be used to adjust the appearance of the current
- item, for example:
-
- \snippet doc/src/snippets/declarative/listview/listview.qml isCurrentItem
- * /
- \endcode
-
- QDoc includes this attached property on the QML reference page for the
- \l{http://qt-project.org/doc/qt-4.7/qml-listview.html#isCurrentItem-prop}
- {ListView} element.
-
- \target qmlattachedsignal-command
- \section1 \\qmlattachedsignal
-
- The \\qmlattachedsignal command is for documenting an attachable
- \l{http://qt-project.org/doc/qt-4.7/qdeclarativeintroduction.html#signal-handlers}
- {signal handler}. 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 handler is declared, the \c{::}
- qualifier, and finally the signal handler name. If we have a QML
- attached signal handler named \c onAdd() in the \c GridView
- element, the \\qmlattachedsignal for it would look like this:
-
- \code
- / *!
- \qmlattachedsignal GridView::onAdd()
- This attached handler is called immediately after an item is
- added to the view.
- * /
- \endcode
-
- QDoc includes this documentation on the QML reference page for the
- \l{http://qt-project.org/doc/qt-4.7/qml-gridview.html#onAdd-signal}
- {GridView} element.
-
- \target qmlbasictype-command
- \section1 \\qmlbasictype
-
- The \\qmlbasictype command is for documenting a basic type for QML.
- The argument is the type name. The type must be included in the
- QML basic types group using the \l{ingroup-command}{\\ingroup}
- command as shown below. This will cause QDoc to include the
- documentation for the type on the
- \l{http://qt-project.org/doc/qt-4.7/qdeclarativebasictypes.html}
- {QML Basic Types} page. The \l{brief-command} {\\brief} command
- is also required, because it appears on the
- \l{http://qt-project.org/doc/qt-4.7/qdeclarativebasictypes.html}
- {QML Basic Types} page as well.
-
- \code
- / *!
- \qmlbasictype int
- \ingroup qmlbasictypes
-
- \brief An integer is a whole number, for example 0, 10, or -20.
-
- An integer is a whole number, e.g. 0, 10, or -20. The possible
- \c int values range from around -2000000000 to around
- 2000000000, although most elements will only accept a reduced
- range (which they mention in their documentation).
-
- Example:
- \qml
- Item { width: 100; height: 200 }
- \endqml
-
- \sa {QML Basic Types}
- * /
- \endcode
-
- QDoc outputs this as \l{http://qt-project.org/doc/qt-4.7/qml-int.html}
- {qml-int.html}.
-
- \target qmlclass-command
- \section1 \\qmlclass
-
- This command is deprecated. Use \l{qmltype-command} {\\qmltype}
- instead.
-
- The \\qmlclass command is for documenting a QML type that is
- instantiated by a C++ class. The command has two arguments. The
- first argument is the name of the QML type. The second argument
- is the name of the C++ class that instantiates the QML type.
-
- \code
- / *!
- \qmlclass Transform QGraphicsTransform
- \ingroup qml-transform-elements
- \since 4.7
- \brief Provides a way of building advanced transformations on Items.
-
- The Transform element is a base type which cannot be
- instantiated directly. The following concrete Transform types
- are available:
-
- \list
- \li \l Rotation
- \li \l Scale
- \li \l Translate
- \endlist
-
- The Transform elements let you create and control advanced
- transformations that can be configured independently using
- specialized properties.
-
- You can assign any number of Transform elements to an \l
- Item. Each Transform is applied in order, one at a time.
-
- * /
- \endcode
-
- This example generates the
- \l {http://qt-project.org/doc/qt-4.7/qml-transform.html} {QML Transform}
- page. The \\qmlclass comment should include the \l
- {since-command} {\\since} command, because all QML types are
- new. It should also include the \l{brief-command} {\\brief}
- command. If a type is a member of a group of QML
- types, it should also include one or more \l{ingroup-command}
- {\\ingroup} commands.
-
- \target qmlmethod-command
- \section1 \\qmlmethod
-
- The \\qmlmethod command is for documenting a QML method. The
- argument is the complete method signature, including return
- type and parameter names and types.
-
- \code
- / *!
- \qmlmethod void TextInput::select(int start, int end)
-
- Causes the text from \a start to \a end to be selected.
-
- If either start or end is out of range, the selection is not changed.
-
- After having called this, selectionStart will become the lesser, and
- selectionEnd the greater (regardless of the order passed to this method).
-
- \sa selectionStart, selectionEnd
- * /
- \endcode
-
- QDoc includes this documentation on the element refence page for the
- \l{http://qt-project.org/doc/qt-4.7/qml-textinput.html#select-method}
- {TextInput} element.
-
- \target qmltype-command
- \section1 \\qmltype
-
- The \\qmltype command is for documenting a QML type. The command
- has one argument, which is the name of the QML type.
-
- If the QML type is instantiated by a C++ class, that class must be
- specified using the \l{instantiates-command} {\\instantiates}
- context command.
-
- \code
- / *!
- \qmltype Transform
- \instantiates QGraphicsTransform
- \ingroup qml-transform-elements
- \since 4.7
- \brief The Transform elements provide a way to build
- advanced transformations on Items.
-
- The Transform element is a base type which cannot be
- instantiated directly. The concrete Transform types are:
-
- \list
- \li \l Rotation
- \li \l Scale
- \li \l Translate
- \endlist
-
- The Transform elements let you create and control advanced
- transformations that can be configured independently using
- specialized properties.
-
- You can assign any number of Transform elements to an \l
- Item. Each Transform is applied in order, one at a time.
-
- * /
- \endcode
-
- The example generates the \l
- {http://qt-project.org/doc/qt-4.7/qml-transform.html} {QML Transform}
- page. The \e{\\qmltype} comment includes \l{instantiates-command}
- {\\instantiates} to specify that a Transform is instantiated by
- the C++ class QGraphicsTransform. A \\qmltype comment should
- always include a \l {since-command} {\\since} command, because all
- QML types are new. It should also include a \l{brief-command}
- {\\brief} description. If a QML type is a member of a QML type group,
- the \\qmltype comment should include one or more \l{ingroup-command}
- {\\ingroup} commands.
-
- \target qmlmethod-command
- \section1 \\qmlmethod
-
- The \\qmlmethod command is for documenting a QML method. The
- argument is the complete method signature, including return
- type and parameter names and types.
-
- \code
- / *!
- \qmlmethod void TextInput::select(int start, int end)
-
- Causes the text from \a start to \a end to be selected.
-
- If either start or end is out of range, the selection is not changed.
-
- After having called this, selectionStart will become the lesser and
- selectionEnd the greater (regardless of the order passed to this method).
-
- \sa selectionStart, selectionEnd
- * /
- \endcode
-
- QDoc includes this documentation on the element refence page for the
- \l{http://qt-project.org/doc/qt-4.7/qml-textinput.html#select-method}
- {TextInput} element.
-
- \target qmlproperty-command
- \section1 \\qmlproperty
-
- The \\qmlproperty command is for documenting a QML property. The
- argument is the rest of the line. The argument text should be the
- property type, followed by the QML type name, the \c{::}
- qualifier, and finally the property name. If we have a QML
- property named \c x in QML type \c Translate, and the property
- has type \c {real}, the \\qmlproperty for it would look like this:
-
- \code
- / *!
- \qmlproperty real Translate::x
-
- The translation along the X axis.
- * /
- \endcode
-
- QDoc includes this QML property on the QML reference page for the
- \l {http://qt-project.org/doc/qt-4.7/qml-translate.html} {Translate}
- element.
-
- \target qmlsignal-command
- \section1 \\qmlsignal
-
- The \\qmlsignal command is for documenting a QML signal.
- The argument is the rest of the line. The arguments should be: the QML type
- where the signal is declared, the \c{::} qualifier, and finally the signal
- name. If we have a QML signal named \c clicked(), the documentation for it
- would look like this:
-
- \code
- / *!
- \qmlsignal UIComponents::Button::clicked()
- This signal is emitted when the user clicks the button. A click is defined
- as a press followed by a release. The corresponding handler is
- \c onClicked.
- * /
- \endcode
-
- QDoc includes this documentation on the QML reference page for the
- \l{http://qt-project.org/doc/qt-4.7/qml-mousearea.html#onEntered-signal}
- {MouseArea} element.
-
- \target qmlmodule-command
- \section1 \\qmlmodule
-
- Insert the \c{\\qmlmodule} command to create a \c QML module page. A QML
- module is a collection of QML types or any related material. This
- command is similar to the \l{group-command}.
-
- A QML class may belong to a module by inserting the
- \l{inqmlmodule-command}{\\inqmlmodule} command as a topic command.
- Every member of a group must be linked to using the module name and two
- colons (\c{::}).
-
- \code
- A link to the UI Component's TabWidget is \l {UIComponent::TabWidget}.
- \endcode
-
- QDoc will generate a page for the module with a listing of the members
- of the module.
-
- \code
- \qmlmodule ClickableComponents
-
- This is a list of the Clickable Components set. A Clickable component
- responds to a \c clicked() event.
- \endcode
-
- The \l{componentset}{UIComponents} example demonstrates proper usage of
- QDoc commands to document QML types and QML modules.
-
- \target inqmlmodule-command
- \section1 \\inqmlmodule
-
- A QML class may belong to a \l{qmlmodule-command}{QML module} by inserting
- the \l{inqmlmodule-command}{\\inqmlmodule} command as a topic command.
- Every member of a group must be linked to using the module name and two
- colons (\c{::}).
-
- \code
- \qmltype ClickableButton
- \inqmlmodule ClickableComponents
-
- A clickable button that responds to the \c click() event.
- \endcode
-
- To link to the \c ClickableButton, use the
- \c{\l ClickableComponents::ClickableButton} format.
-
- The \l{componentset}{UIComponents} example demonstrates proper usage of
- QDoc commands to document QML types and QML modules.
-
- \target instantiates-command
- \section1 \\instantiates
-
- The \\instantiates command is used in the \l{qmltype-command} {QML
- type} comment of an elemental QML type to specify the name of the
- C++ class that instantiates the QML type.
-
- If the QML type is not instantiated by a C++ class, this command
- is not used.
-
- \code
- / *!
- \qmltype Transform
- \instantiates QGraphicsTransform
- \ingroup qml-transform-elements
- \since 4.7
- \brief Provides elements provide a way to build
- advanced transformations on Items.
-
- The Transform element is a base type which cannot be
- instantiated directly.
- * /
- \endcode
-
- The example generates the \l
- {http://qt-project.org/doc/qt-4.7/qml-transform.html} {QML Transform}
- page. The \e{\\qmltype} comment includes \l{instantiates-command}
- {\\instantiates} to specify that a Transform is instantiated by
- the C++ class QGraphicsTransform. A \\qmltype comment should
-
- \target typedef-command
- \section1 \\typedef
-
- The \\typedef command is for documenting a C++ typedef. The
- argument is the name of the typedef. The documentation for
- the typedef will be included in the reference documentation
- for the class, namespace, or header file in which the typedef
- is declared. To relate the \\typedef to a class, namespace, or
- header file, the \\typedef comment must contain a
- \l {relates-command} {\\relates} command.
-
- \code
- / *!
- \typedef QObjectList
- \relates QObject
-
- Synonym for QList<QObject>.
- * /
- \endcode
-
- QDoc includes this in \c {qobject.html} as:
-
- \quotation
- \raw HTML
- <h3>typedef QObjectList</h3>
- \endraw
-
- Synonym for QList<QObject>.
- \endquotation
-
- Another, although more rare, example:
-
- \code
- / *!
- \typedef QMsgHandler
- \relates QtGlobal
-
- This is a typedef for a pointer to a function with the
- following signature:
-
- \code
- void myMsgHandler(QtMsgType, const char *);
- \ endcode
-
- \sa QtMsgType, qInstallMsgHandler()
- * /
- \endcode
-
- QDoc includes this in \c {qtglobal.html} as:
-
- \quotation
- \raw HTML
- <h3>typedef QtMsgHandler</h3>
- \endraw
-
- This is a typedef for a pointer to a function with the
- following signature:
-
- \raw HTML
- <tt>
- <pre> void myMsgHandler(QtMsgType, const char *);</pre>
- </tt>
- \endraw
-
- See also QtMsgType and qInstallMsgHandler().
- \endquotation
-
- Other typedefs are located on the reference page for the class
- that defines them.
-
- \code
- / *!
- \typedef QLinkedList::Iterator
-
- Qt-style synonym for QList::iterator.
- * /
- \endcode
-
- QDoc includes this one on the reference page for class QLinkedList as:
-
- \quotation
- \raw HTML
- <h3>typedef QLinkedList::Iterator</h3>
- \endraw
-
- Qt-style synonym for QList::iterator.
- \endquotation
-
- \target variable-command
- \section1 \\variable
-
- The \\variable command is for documenting a class member variable
- or a constant. The argument is the variable or constant name. The
- \\variable command comment includes a \l {brief-command} {\\brief}
- command. QDoc generates the documentation based on the text from
- \\brief command.
-
- The documentation will be located in the in the associated class,
- header file, or namespace documentation.
-
- In case of a member variable:
-
- \code
- / *!
- \variable QStyleOption::palette
- \brief The palette that should be used when painting
- the control
- * /
- \endcode
-
- QDoc includes this in qstyleoption.html as:
-
- \quotation
- \raw HTML
- <h3>
- <a href="http://qt-project.org/doc/qt-5.0/qtgui/qpalette.html">
- QPalette
- </a>
- QStyleOption::palette
- </h3>
- \endraw
-
- This variable holds the palette that should be used
- when painting the control.
- \endquotation
-
- You can also document constants with the \\variable command. For
- example, suppose you have the \c Type and \c UserType constants in
- the QTreeWidgetItem class:
-
- \code
- enum { Type = 0, UserType = 1000 };
- \endcode
-
- For these, the \\variable command can be used this way:
-
- \code
- / *!
- \variable QTreeWidgetItem::Type
-
- The default type for tree widget items.
-
- \sa UserType, type()
- * /
- \endcode
- \code
- / *!
- \variable QTreeWidgetItem::UserType
-
- The minimum value for custom types. Values below
- UserType are reserved by Qt.
-
- \sa Type, type()
- * /
- \endcode
-
- QDoc includes these in qtreewidget.html as:
-
- \quotation
- \raw HTML
- <h3>
- const int QTreeWidgetItem::Type
- </h3>
- \endraw
-
- The default type for tree widget items.
-
- See also \l {QTreeWidgetItem::UserType} {UserType} and \l
- {QTreeWidgetItem::type()} {type()}.
-
- \raw HTML
- <h3>
- const int QTreeWidgetItem::UserType
- </h3>
- \endraw
-
- The minimum value for custom types. Values below
- UserType are reserved by Qt.
-
- See also \l {QTreeWidgetItem::Type} {Type} and
- \l{QTreeWidgetItem::type()} {type()}.
-
- \endquotation
-*/
-
-/*!
- \page 14-qdoc-commands-contextcommands.html
- \previouspage Topic Commands
- \contentspage QDoc Manual
- \nextpage Document Navigation
-
- \title Context Commands
-
- The context commands provide information about the element being
- documented that QDoc can't deduce on its own. For example:
- \list
- \li Is this class thread-safe?
- \li Is this function reentrant?
- \li Of which module is this class a member ?
- \endlist
-
- Context commands can appear anywhere in a QDoc comment,
- but they are normally placed near the top of the comment, just
- below the \l {Topic Commands} {topic} command.
-
- \list
- \li \l {16-qdoc-commands-status.html#compat-command}{\\compat},
- \li \l {15-qdoc-commands-navigation.html#contentspage-command}{\\contentspage},
- \li \l {15-qdoc-commands-navigation.html#indexpage-command}{\\indexpage},
- \li \l {19-qdoc-commands-grouping.html#ingroup-command}{\\ingroup},
- \li \l {18-qdoc-commands-relating.html#inherits-command}{\\inherits},
- \li \l {19-qdoc-commands-grouping.html#inmodule-command}{\\inmodule},
- \li \l {16-qdoc-commands-status.html#internal-command}{\\internal},
- \li \l {19-qdoc-commands-grouping.html#mainclass-command}{\\mainclass},
- \li \l {15-qdoc-commands-navigation.html#nextpage-command}{\\nextpage},
- \li \l {17-qdoc-commands-thread.html#nonreentrant-command}{\\nonreentrant},
- \li \l {16-qdoc-commands-status.html#obsolete-command}{\\obsolete},
- \li \l {18-qdoc-commands-relating.html#overload-command}{\\overload},
- \li \l {16-qdoc-commands-status.html#preliminary-command}{\\preliminary},
- \li \l {15-qdoc-commands-navigation.html#previouspage-command}{\\previouspage},
- \li \l {17-qdoc-commands-thread.html#reentrant-command}{\\reentrant},
- \li \l {18-qdoc-commands-relating.html#reimp-command}{\\reimp},
- \li \l {18-qdoc-commands-relating.html#relates-command}{\\relates},
- \li \l {16-qdoc-commands-status.html#since-command}{\\since},
- \li \l {15-qdoc-commands-navigation.html#startpage-command}{\\startpage},
- \li \l {20-qdoc-commands-namingthings.html#subtitle-command}{\\subtitle}
- \li \l {17-qdoc-commands-thread.html#threadsafe-command}{\\threadsafe},
- \li \l {20-qdoc-commands-namingthings.html#title-command}{\\title}
- \endlist
-
-*/
-
-/*!
- \page 15-qdoc-commands-navigation.html
- \previouspage Context Commands
- \contentspage QDoc Manual
- \nextpage Reporting 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
-
- \code
- / *!
- \page basicqt.html
- \contentspage {Basic Qt} {Contents}
- \nextpage Getting Started
-
- \indexpage Index
- \startpage Basic Qt
-
- \title Basic Qt
-
- The Qt toolkit is a C++ class library and a set of tools for
- building multiplatform GUI programs using a "write once,
- compile anywhere approach".
-
- Table of contents:
-
- \list
- \li \l {Getting Started}
- \li \l {Creating Dialogs}
- \li \l {Creating Main Windows}
- \endlist
- * /
-
- / *!
- \page gettingstarted.html
- \previouspage Basic Qt
- \contentspage {Basic Qt} {Contents}
- \nextpage Creating Dialogs
-
- \indexpage Index
- \startpage Basic Qt
-
- \title Getting Started
-
- This chapter shows how to combine basic C++ with the
- functionality provided by Qt to create a few small graphical
- interface (GUI) applications.
- * /
-
- / *!
- \page creatingdialogs.html
- \previouspage Getting Started
- \contentspage {Basic Qt} {Contents}
-
- \indexpage Index
- \startpage Basic Qt
-
- \title Creating Dialogs
-
- This chapter will teach you how to create dialog boxes using Qt.
- * /
-
- / *!
- \page index.html
-
- \indexpage Index
- \startpage Basic Qt
-
- \title Index
-
- \list
- \li \l {Basic Qt}
- \li \l {Creating Dialogs}
- \li \l {Getting Started}
- \endlist
- * /
- \endcode
-
- QDoc renders the "Getting Started" page in \c{creatingdialogs.html}:
-
- \quotation
- \raw HTML
- <table border="0" cellpadding="0" cellspacing="5" width="100%">
-
- <tr>
- <p>
- [Previous: <a href="15-qdoc-commands-navigation.html#deadlink">
- Basic Qt</a>]
- [<a href="15-qdoc-commands-navigation.html#deadlink">Contents</a>]
- [Next: <a href="15-qdoc-commands-navigation.html#deadlink">
- Creating Dialogs</a>]
- </p>
-
- <h1 align="center">Getting Started<br /></h1>
-
- <p>
- This chapter shows how to combine basic C++ with the
- functionality provided by Qt to create a few small graphical
- interface (GUI) applications.
- </p>
-
- <p>
- [Previous: <a href="15-qdoc-commands-navigation.html#deadlink">
- Basic Qt</a>]
- [<a href="15-qdoc-commands-navigation.html#deadlink">Contents</a>]
- [Next: <a href="15-qdoc-commands-navigation.html#deadlink">
- Creating Dialogs</a>]
- </p>
-
- </table>
- \endraw
- \endquotation
-
- The \l {indexpage-command} {\\indexpage} and \l
- {startpage-command} {\\startpage} commands create links to the
- page's index page and start page. These links can be used by
- browsers and search engines.
-
- The index page is typically an alphabetical list of the document's
- titles and topics, while the start page is the page considered by
- the author to be the starting point of a multipage document.
-
- The links are included in the generated HTML source code, but have
- no visual effect on the documentation:
-
- \code
- <head>
- ...
- <link rel="index" href="index.html" />
- <link rel="start" href="basicqt.html" />
- ...
- </head>
- \endcode
-
- \section1 Commands
-
- \target previouspage-command
- \section2 \\previouspage
-
- The \\previouspage command links the current page to the previous
- page in a sequence.a The command has two arguments, each enclosed
- by curly braces: the first is the link target (the title of
- the previous page), the second is the link text. If the page's
- title is equivalent to the link text, the second argument can be
- omitted.
-
- The command must stand alone on its own line.
-
- \target nextpage-command
- \section2 \\nextpage
-
- The \\nextpage command links the current page to the next page in
- a sequence. The command follows the same syntax and argument
- convention as the \l {previouspage-command} {\\previouspage}
- command.
-
- \target startpage-command
- \section2 \\startpage
-
- The \\startpage command specifies the first page of a sequence of
- pages. The command must stand alone on its own line, and its
- unique argument is the title of the first document.
-
- QDoc will generate a link to the start page and include it in the
- generated HTML file, but this has no visual effect on the
- documentation. The generated link type tells browsers and search
- engines which document is considered by the author to be the
- starting point of the collection.
-
- \target contentspage-command
- \section2 \\contentspage
-
- The \\contentspage command links the current page to a table of
- contents page. The command follows the same syntax and argument
- convention as the \l {previouspage-command} {\\previouspage}
- command.
-
- \target indexpage-command
- \section2 \\indexpage
-
- The \\indexpage command specifies an index page for the current
- document. The command must stand alone on its own line, and its
- unique argument is the title of the index document.
-
- QDoc will generate a link to the index page and include it in the
- generated HTML file, but this has no visual effect on the
- documentation. The generated link type tells browsers and search
- engines which document is considered by the author to be the
- index page of the collection.
-*/
-
-/*!
- \page 16-qdoc-commands-status.html
- \previouspage Document Navigation
- \contentspage QDoc Manual
- \nextpage Thread Support
-
- \title Reporting Status
-
- These commands are for indicating that a documented element is
- still under development, is becoming obsolete, is provided for
- compatibility reasons, or is simply not to be included in the
- public interface. The \l {since-command}{\\since} command is for
- including information about the version when a function or class
- first appeared.
-
- \target compat-command
- \section1 \\compat
-
- The \\compat command is for indicating that a class or function is
- part of the support library provided to keep old source code
- working.
-
- The command must stand on its own line.
-
- Usually an equivalent function or class is provided as an
- alternative.
-
- If the command is used in the documentation of a class, the
- command expands to a warning that the referenced class is part of
- the support library. The warning is located at the top of the
- documentation page.
-
- \code
- / *!
- \class MyQt3SupportClass
- \compat
- * /
- \endcode
-
- QDoc renders this at the top of the MyQt3SupportClass class
- reference page.
-
- \quotation
- \b {This class is part of the Qt 3 support
- library.} It is provided to keep old source code
- working. We strongly advise against using it in new
- code. See the \l
- {http://doc.qt.digia.com/4.0/porting4.html} {Porting
- Guide} for more information.
- \endquotation
-
- If the command is used when documenting a function, QDoc will
- create and link to a separate page documenting Qt 3 support
- members when generating the reference documentation for the
- associated class.
-
- \code
- / *!
- \fn MyClass::MyQt3SupportMemberFunction
- \compat
-
- Use MyNewFunction() instead.
- * /
- \endcode
-
- QDoc renders this in \c{myclass-qt3.html} as:
-
- \quotation
- \raw HTML
- <h1>Qt 3 Support Members for MyClass</h1>
- \endraw
-
- \b {The following class members are part of the Qt 3
- support layer.} They are provided to help you port old code to
- Qt 4. We advise against using them in new code.
-
- ...
-
- \list
- \li void MyQt3SupportMemberFunction()
- \li ...
- \endlist
-
- \raw HTML
- <hr />
- <h2>Member Function Documentation</h2>
- <h3>void MyQt3SupportMemberFunction ()</h3>
- <p>Use MyNewFunction() instead.</p>
- \endraw
- ...
- \endquotation
-
- \target default-command
- \section1 \\default
-
- The \\default command is for marking a QML property as the
- \l {http://qt-project.org/doc/qt-4.7/qdeclarativeintroduction.html#default-properties}
- {default property}. The word \span {class="newStuff"} {default} is shown in red in
- the documentation of the property.
-
- \code
- / *!
- \qmlproperty list<Change> State::changes
- This property holds the changes to apply for this state.
- \default
-
- By default these changes are applied against the default state. If the state
- extends another state, then the changes are applied against the state being
- extended.
- * /
- \endcode
-
- See how QDoc renders this property on the reference page for the
- \l {http://qt-project.org/doc/qt-4.7/qml-state.html#changes-prop} {State}
- type.
-
- \target obsolete-command
- \section1 \\obsolete
-
- The \\obsolete command is for indicating that a function is being
- deprecated, and it should no longer be used in new code. There is
- no guarantee for how long it will remain in the library.
-
- The command must stand on its own line.
-
- When generating the reference documentation for a class, QDoc will
- create and link to a separate page documenting its obsolete
- functions. Usually an equivalent function is provided as an
- alternative.
-
- \code
- / *!
- \fn MyClass::MyObsoleteFunction
- \obsolete
-
- Use MyNewFunction() instead.
- * /
- \endcode
-
- QDoc renders this in \c{myclass-obsolete.html} as:
-
- \quotation
- \raw HTML
- <h1>Obsolete Members for MyClass</h1>
- \endraw
-
- \b {The following class members are obsolete.} They are
- provided to keep old source code working. We strongly advise
- against using them in new code.
-
- ...
-
- \list
- \li void MyObsoleteFunction() \c (obsolete)
- \li ...
- \endlist
-
- \raw HTML
- <hr />
- <h2>Member Function Documentation</h2>
- <h3>void MyObsoleteFunction ()</h3>
- <p>Use MyNewFunction() instead.</p>
- \endraw
- ...
- \endquotation
-
- \target internal-command
- \section1 \\internal
-
- The \\internal command indicates that the referenced
- function is not part of the public interface.
-
- The command must stand on its own line.
-
- QDoc ignores the documentation as well as the documented item,
- when generating the associated class reference documentation.
-
- \code
- / *!
- \internal
-
- Tries to find the decimal separator. If it can't find
- it and the thousand delimiter is != '.' it will try to
- find a '.';
- * /
- int QDoubleSpinBoxPrivate::findDelimiter
- (const QString &str, int index) const
- {
- int dotindex = str.indexOf(delimiter, index);
- if (dotindex == -1 && thousand != dot && delimiter != dot)
- dotindex = str.indexOf(dot, index);
- return dotindex;
- }
- \endcode
-
- This function will not be included in the documentation.
-
- \target preliminary-command
- \section1 \\preliminary
-
- The \\preliminary command is for indicating that a referenced
- function is still under development.
-
- The command must stand on its own line.
-
- The \\preliminary command expands to a notification in the
- function documentation, and marks the function as preliminary when
- it appears in lists.
-
- \code
- / *!
- \preliminary
-
- Returns information about the joining properties of the
- character (needed for certain languages such as
- Arabic).
- * /
- QChar::Joining QChar::joining() const
- {
- return ::joining(*this);
- }
- \endcode
-
- QDoc renders this as:
-
- \quotation
- \raw HTML
- <h3>
- <a href="http://qt-project.org/doc/qt-5.0/qtcore/qchar.html#Joining-enum">Joining</a>
- QChar::joining () const</h3>
- \endraw
-
- \b {This function is under development and
- subject to change.}
-
- Returns information about the joining properties of the
- character (needed for certain languages such as
- Arabic).
- \endquotation
-
- And the function's entry in QChar's list of functions will be
- rendered as:
-
- \quotation
- \list
- \li ...
- \li Joining
- \l {http://qt-project.org/doc/qt-5.0/qtcore/qchar.html#Joining-enum}
- {joining}()
- const \c (preliminary)
- \li ...
- \endlist
- \endquotation
-
- \target since-command
- \section1 \\since
-
- The \\since command tells in which minor release
- the associated functionality was added.
-
- \code
- / *!
- \since 4.1
-
- Returns an icon for \a standardIcon.
-
- ...
-
- \sa standardIconImplementation(), standardPixmap()
- * /
- QIcon QStyle::standardIcon(StandardPixmap standardIcon, const QStyleOption *option, const QWidget *widget) const
- {
- }
- \endcode
-
- QDoc renders this as:
-
- \quotation
- \raw HTML
- <h3>QIcon QStyle::standardIcon(StandardPixmap standardIcon, const QStyleOption *option, const QWidget *widget) const</h3>
- \endraw
-
- This function was introduced in Qt version 4.1
-
- Returns an icon for \a standardIcon.
-
- ...
-
- See also \l {QStyle::standardIconImplementation()}
- {standardIconImplementation()} and \l
- {QStyle::standardPixmap()} {standardPixmap()}.
- \endquotation
-
- QDoc generates the "Qt" reference from the \l
- {25-qdoc-configuration-derivedprojects.html#project} {\c project}
- configuration variable. For that reason this reference will change
- according to the current documentation project.
-
- See also \l {25-qdoc-configuration-derivedprojects.html#project}
- {\c project}.
-*/
-
-/*!
- \page 17-qdoc-commands-thread.html
- \previouspage Reporting Status
- \contentspage QDoc Manual
- \nextpage Relating Things
-
- \title Thread Support
-
- The thread support commands are for specifying the level of
- support for multithreaded programming in a class or function.
- There are three levels of support: \c threadsafe, \c reentrant and
- \c nonreentrant.
-
- The default is \c nonreentrant which means that the associated
- class or function cannot be called by multiple threads. \c
- Reentrant and \c threadsafe are levels primarily used for classes.
-
- \c Reentrant means that all the functions in the referenced class
- can be called simultaneously by multiple threads, provided that
- each invocation of the functions reference unique data. \c
- thread-safe means that all the functions in the referenced class
- can be called simultaneously by multiple threads even when each
- invocation references shared data.
-
- When a class is marked \l {reentrant-command} {\\reentrant} or \l
- {threadsafe-command} {\\threadsafe}, functions in that class can
- be marked \c nonreentrant using the \l {nonreentrant-command}
- {\\nonreentrant} command.
-
- \section1 Example
-
- \target reentrant-example
- \code
- / *!
- \class QLocale
- \brief The QLocale class converts between numbers and their
- string representations in various languages.
-
- \reentrant
- \ingroup i18n
- \ingroup text
- \mainclass
-
- 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()
- * /
- void QLocale::setDefault(const QLocale &locale)
- {
- default_d = locale.d;
- }
- \endcode
-
- QDoc renders this as:
-
- \quotation
- \raw HTML
- <h1><center>QLocale Class Reference</center></h1>
- \endraw
-
- The QLocale class converts between numbers and their string
- representations in various languages. More...
-
- \code
- #include <QLocale>
- \endcode
-
- \b {Note:} All the functions in this class are \l
- {threads.html#reentrant} {reentrant}, except \l
- {QLocale::setDefault()} {setDefault()}.
-
- ...
-
- \raw HTML
- <hr />
- <h2>Member Type Documentation</h2>
- \endraw
-
- ...
-
- \raw HTML
- <h3>void QLocale::setDefault ( const QLocale & locale ) </h3>
- \endraw
-
- Sets the global default locale to locale. These values are
- used when a QLocale object is constructed with no
- arguments. If this function is not called, the system's locale
- is used.
-
- \warning In a multithreaded application, the default locale
- should be set at application startup, before any non-GUI
- threads are created.
-
- \warning This function is not reentrant.
-
- See also \l {QLocale::system()} {system()} and \l
- {QLocale::c()} {c()}.
-
- ...
- \endquotation
-
- As shown above, QDoc generates a notification when a class is
- declared reentrant, and lists the exceptions (the declared
- nonreentrant functions). A link to the general documentation on \l
- {threads.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
- {threads.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 documentation generated for the \l {reentrant-command} {\\reentrant}
- command. See the example above in the \l {reentrant-example}
- {introduction}.
-
- See also \l{reentrant-command} {\\reentrant} and
- \l{nonreentrant-command} {\\nonreentrant}.
-
- \target reentrant-command
- \section2 \\reentrant
-
- The \\reentrant command indicates that the associated class or
- function can be called simultaneously by multiple threads,
- provided that each invocation references its own data. See the \l
- {reentrant-example} {example} above.
-
- The command must stand on its own line.
-
- See also \l{nonreentrant-command} {\\nonreentrant} and
- \l{threadsafe-command} {\\threadsafe}.
-
- \target nonreentrant-command
- \section2 \\nonreentrant
-
- The \\nonreentrant command indicates that the associated class or
- function cannot be called by multiple threads. Nonreentrant is the
- default case.
-
- The command must stand on its own line.
-
- When a class is marked \l {reentrant-command} {\\reentrant} or \l
- {threadsafe-command} {\\threadsafe}, functions in that class can
- be marked \c nonreentrant using this command in the \l{fn-command}
- {\\fn} comment of the functions to be excluded.
-
- See also \l{reentrant-command} {\\reentrant} and
- \l{threadsafe-command} {\\threadsafe}.
-*/
-
-/*!
- \page 18-qdoc-commands-relating.html
- \previouspage Thread Support
- \contentspage QDoc Manual
- \nextpage Grouping Things
-
- \title Relating Things
-
- The relating commands are for specifying how one documented
- element relates to another documented element. Some examples:
- \list
- \li This function is an overload of another function.
- \li This function is a reimplementation of another function.
- \li This typedef is \e related to some class or header file.
- \endlist
-
- There is also a command for documenting that a QML type inherits
- some other QML type.
-
- \section1 Commands
-
- \target inherits-command
- \section2 \\inherits
-
- The \\inherits command is for documenting that one QML type
- inherits some other QML type. It must be included in the
- inheriting element's \l{qmltype-command}{\\qmltype} comment.
- The argument is the name of the inherited QML type.
-
- \code
- / *!
- \qmltype PauseAnimation
- \instantiates QDeclarativePauseAnimation
- \ingroup qml-animation-transition
- \since 4.7
- \inherits Animation
- \brief The PauseAnimation element provides a pause for an animation.
-
- When used in a SequentialAnimation, PauseAnimation is a step
- when nothing happens, for a specified duration.
-
- A 500ms animation sequence, with a 100ms pause between two animations:
-
- SequentialAnimation {
- NumberAnimation { ... duration: 200 }
- PauseAnimation { duration: 100 }
- NumberAnimation { ... duration: 200 }
- }
-
- \sa {QML Animation and Transitions}, {declarative/animation/basics}{Animation basics example}
- * /
- \endcode
-
- QDoc includes this line on the reference page for the
- \l{http://qt-project.org/doc/qt-4.7/qml-pauseanimation.html} {PauseAnimation}
- element:
-
- \quotation
- Inherits \l{http://qt-project.org/doc/qt-4.7/qml-animation.html} {Animation}
- \endquotation
-
- \target overload-command
- \section2 \\overload
-
- The \\overload command is for indicating that a function is a
- secondary overload of its name.
-
- The command must stand on its own line.
-
- For a function name that is overloaded (except constructors), QDoc
- expects one primary version of the function, and all the others
- marked with the \b {\\overload command}. The primary version
- should be fully documented. Each overload can have whatever extra
- documentation you want to add for just that overloaded version.
-
- From Qt 4.5, you can include the function name plus '()' as a
- parameter to the \b{\\overload} command, which will include a
- standard \e{This function overloads...} line of text with a link
- to the documentation for the primary version of the function.
-
- \code
- / *!
- \overload addAction()
-
- This convenience function creates a new action with an
- \a icon and some \a text. The function adds the newly
- created action to the menu's list of actions, and
- returns it.
-
- \sa QWidget::addAction()
- * /
- QAction *QMenu::addAction(const QIcon &icon, const QString &text)
- {
- QAction *ret = new QAction(icon, text, this);
- addAction(ret);
- return ret;
- }
- \endcode
-
- QDoc renders this as:
-
- \quotation
- \raw HTML
- <h3><a href="http://qt-project.org/doc/qt-5.0/qtwidgets/qaction.html">QAction</a>
- * QMenu::addAction ( const QIcon & <i>icon</i>,
- const QString & <i>text</i> )
- </h3>
- \endraw
-
- This function overloads \l {http://qt-project.org/doc/qt-5.0/qtwidgets/qwidget.html#addAction} {addAction()}
-
- This convenience function creates a new action with an
- \e icon and some \e text. The function adds the newly
- created action to the menu's list of actions, and
- returns it.
-
- See also
- \l {http://qt-project.org/doc/qt-5.0/qtwidgets/qwidget.html#addAction}
- {QWidget::addAction}().
- \endquotation
-
- If you don't include the function name with the \b{\\overlaod}
- command, then instead of the "This function overloads..." line
- with the link to the documentation for the primary version, you
- get the old standard line:
-
- \quotation
- This is an overloaded member function, provided for
- convenience.
- \endquotation.
-
- \target reimp-command
- \section2 \\reimp
-
- The \\reimp command is for indicating that a function is a
- reimplementation of a virtual function.
-
- The command must stand on its own line.
-
- QDoc will omit the reimplemented function from the class
- reference.
-
- \code
- / *!
- \reimp
- * /
- void QToolButton::nextCheckState()
- {
- Q_D(QToolButton);
- if (!d->defaultAction)
- QAbstractButton::nextCheckState();
- else
- d->defaultAction->trigger();
- }
- \endcode
-
- This function will not be included in the documentation. Instead,
- a link to the base function QAbstractButton::nextCheckState() will
- appear in the documentation.
-
- \target relates-command
- \section2 \\relates
-
- The \\relates command is for including the documentation of a
- global element to some class or header file. The argument is a
- class name or header file.
-
- \code
- / *!
- \relates QChar
-
- Reads a char from the stream \a in into char \a chr.
-
- \sa {Format of the QDataStream operators}
- * /
- QDataStream &operator>>(QDataStream &in, QChar &chr)
- {
- quint16 u;
- in >> u;
- chr.unicode() = ushort(u);
- return in;
- }
- \endcode
-
- The documentation for this function will be included on the reference page
- for class QChar.
-*/
-
-/*!
- \page 19-qdoc-commands-grouping.html
- \previouspage Relating Things
- \contentspage QDoc Manual
- \nextpage Naming Things
-
- \title Grouping Things
-
- The grouping commands relate classes to defined groups and
- modules. The groups are used when generating lists of related
- classes in the documentation, while the modules are elements of
- Qt's structure.
-
- \section1 Commands
-
- \target mainclass-command
- \section2 \\mainclass
-
- The \\mainclass command relates the documented class to
- a group called mainclasses.
-
- The command must stand on its own line.
-
- \code
- / *!
- \class QWidget qwidget.h
- \brief The QWidget class is the base class of
- all user interface objects.
-
- \mainclass
-
- ...
- * /
- \endcode
-
- This will include the QWidget class in the \e mainclasses
- group, which means, for example, that the class will appear on the
- list created by calling the \l {generatelist-command}
- {\\generatelist} command with the \c mainclasses argument:
-
- \l http://doc.qt.digia.com/4.0/mainclasses.html
-
- \note The Qt documentation no longer includes the \e mainclasses
- page.
-
- See also \l {generatelist-command} {\\generatelist}.
-
- \target ingroup-command
- \section2 \\ingroup
-
- The \\ingroup command indicates that the given
- overview or documented class belongs to a certain group of
- related docmentation.
-
- A class or overview may belong to many groups.
-
- The \\ingroup command's argument is a group name, but note
- that the command considers the rest of the line as part of
- its argument. Make sure that the group name is followed by
- a linebreak.
-
- \code
- / *!
- \class QDir
- \brief The QDir class provides access to directory
- structures and their contents.
-
- \ingroup io
- ...
- * /
- \endcode
-
- This will include the QDir class in the \c io group, which means,
- for example, that QDir will appear on the list created by calling
- the \l {group-command} {\\group} command with the \c io argument.
-
- To list overviews that are related to a certain group, you must
- generate the list explicitly using the \l {generatelist-command}
- {\\generatelist} command with the \c related argument.
-
- See also \l {group-command} {\\group}.
-
- \target inmodule-command
- \section2 \\inmodule
-
- The \\inmodule command relates a class to the module specified by
- the command's argument.
-
- For the basic classes in Qt, a class's module is determined by its
- location, namely its directory. However, for extensions like
- ActiveQt and Qt Designer, a class must be related to a module
- explicitly.
-
- The command's argument is a module name, but note that the command
- considers the rest of the line as part of its argument. Make sure
- that the module name is followed by a linebreak.
-
- \code
- /*!
- \class QDesignerTaskMenuExtension
- \inmodule QtDesigner
- * /
- \endcode
-
- This ensures that the QDesignerTaskMenuExtension class is included
- in the Qt Designer module, which means, for example, that the
- class will appear on the list created by calling the \l
- {generatelist-command} {\\generatelist} command with the \c
- {{classesbymodule QtDesigner}} argument.
-
- See also \l {module-command} {\\module} and \l
- {generatelist-command} {\\generatelist}.
-*/
-
-/*!
- \page 20-qdoc-commands-namingthings.html
- \previouspage Grouping Things
- \contentspage QDoc Manual
- \nextpage Markup Commands
-
- \title Naming Things
-
- In general, a title command considers everything that follows it
- until the first line break as its argument. If the title is so
- long it must span multiple lines, end each line (except the last
- one) with a backslash.
-
- \section1 Commands
-
- \target title-command
- \section2 \\title
-
- The \\title command sets the title for a documentation page, or
- allows you to override it.
-
- \code
- / *!
- \page signalandslots.html
-
- \title Signals & Slots
-
- Signals and slots are used for communication between
- objects. The signals and slots mechanism is a central
- feature of Qt, and probably the part that differs most
- from the features provided by other frameworks.
-
- ...
- * /
- \endcode
-
- QDoc renders this as:
-
- \quotation
- \raw HTML
- <h1><center>Signal and Slots</center></h1>
- \endraw
-
- Signals and slots are used for communication between
- objects. The signals and slots mechanism is a central
- feature of Qt and probably the part that differs most
- from the features provided by other frameworks.
- ...
- \endquotation
- See also \l {subtitle-command} {\\subtitle}.
-
- \target subtitle-command
- \section2 \\subtitle
-
- The \\subtitle command sets a subtitle for a documentation page.
-
- \code
- / *!
- \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.
- ...
- * /
- \endcode
-
- QDoc renders this as:
-
- \quotation
- \raw HTML
- <h1><center>Qtopia Core</center></h1>
- <h2><center>Qt for Embedded Linux</center></h2>
- \endraw
-
- Qt/Embedded, the embedded Linux port of Qt, is a
- complete and self-contained C++ GUI and platform
- development tool for Linux-based embedded development.
- ...
- \endquotation
-
- See also \l {title-command} {\\title}.
-
-*/
-
-/*!
- \page 21-0-qdoc-creating-dita-maps.html
- \previouspage Miscellaneous
- \contentspage QDoc Manual
- \nextpage The QDoc Configuration File
-
- \title Creating DITA Maps
-
- You can create DITA map files using three new qdoc commands, the \l{ditamap-command}
- {ditamap} command, the \l{topicref-command} {topicref} command, and the \l{mapref-command}
- {mapref} command. How these DITA maps will be used automatically or manually by the
- documentation build process is still under consideration. This section will be updated
- as the decisions are made.
-
- \section1 What is a DITA map?
-
- A complete description of DITA can be found at the
- \l{http://www.oasis-open.org/committees/tc_home.php?wg_abbrev=dita}
- {OASIS Darwin Information Typing Architecture} site.
-
- An explanation of the DITA map is found at that site
- \l{http://docs.oasis-open.org/dita/v1.2/os/spec/langref/map.html}{here}.
-
- \target ditamap-command
- \section1 \\ditamap
-
- The \\ditamap command is for creating a DITA map using qdoc commands.
- The \\ditamap command is a kind of \\page command that produces a
- \e{.ditamap} instead of a \e{.html} or \e{.xml} file. The file that
- is created actually contains XML text, but the \e{.ditamap} suffix is
- used to identify the file as containing a DITA MAP.
-
- The argument is the name of the file to be created. In the following
- example, the file \e{creator.ditamap} is output:
- \code
- \ditamap creator.ditamap
- \endcode
-
- \target topicref-command
- \section1 \\topicref \\endtopicref
-
- The \\topicref \\endtopicref commands are for creating a topicref
- in the ditamap. The \\endtopicref command is required because
- \\topicref commands can be nested.
-
- \\topicref has two arguments. The first argument becomes the value
- of the \e navtitle attribute. Normally, you use the title of the
- topic being referenced. This title is often what will appear in a
- table of contents constructed from the ditamap.
-
- The second argument is the name of the page being referenced. The
- second argument is actually optional, for example if you are using
- a topicref as a container for other topicrefs and maprefs. It is
- also optional if you want qdoc to find the page name for you by
- looking up the title in its internal data structure. It is recommended
- that you provide the second parameter if you know the page name.
-
- \code
- \topicref {QML Module QtQuick 2} {qtquick-2.xml}
- \mapref {Creator Manual} {creator-manual.ditamap} \endmapref
- \topicref {QML Mouse Events} {qtquick2-mouseevents.xml} \endtopicref
- \topicref {Property Binding} {qtquick2-propertybinding.xml} \endtopicref
- \endtopicref
- \endcode
-
- \target mapref-command
- \section1 \\mapref
-
- The \\mapref command is for creating a mapref in the ditamap. A
- mapref refers to another ditamap, which you want to include in
- your ditamap. Like the \\topicref command, the \\mapref command
- has two arguments, but for the \\mapref command, both arguments
- are required. The arguments are essentially the same as described
- for \\topicref, but for \\mapref, the second command must be the
- name of another ditamap, i.e. it must have the \e{.ditamap}
- suffix. You must provide the file name. qdoc can't look up the
- file name for you.
-
- \code
- \mapref {Creator Manual} {creator-manual.ditamap} \endmapref
- \endcode
-
- \section1 An example ditamap page
-
- The following example uses the three qdoc ditamap commands described above.
-
- \code
- \ditamap creator.ditamap
- \title The DITA Map for Creator
-
- \topicref {QML Module QtQuick 1}
- \topicref {QML Mouse Events} \endtopicref
- \topicref {Property Binding} \endtopicref
- \endtopicref
-
- \topicref {QML Module QtQuick 2} {qtquick-2.xml}
- \mapref {Creator Manual} {creator-manual.ditamap} \endmapref
- \topicref {QML Mouse Events} {qtquick2-mouseevents.xml} \endtopicref
- \topicref {Property Binding} {qtquick2-propertybinding.xml} \endtopicref
- \endtopicref
-
- \topicref {QML Module QtQuick.Particles 2} {qtquick-particles-2.xml}
- \topicref {Age} {qml-qtquick-particles2-age.xml} \endtopicref
- \endtopicref
- \endcode
-
- \section1 The resulting ditamap file
-
- This is the \e{.ditamap} file you get when you input the qdoc
- ditamap page shown above. Note that you can write ditamap files
- directly in XML just as easily as you can write them using the
- qdoc commands. The choice is yours.
-
- \code
- <?xml version="1.0" encoding="UTF-8"?>
- <!DOCTYPE map PUBLIC "-//OASIS//DTD DITA Map//EN" "map.dtd">
- <map>
- <topicmeta>
- <shortdesc>The DITA Map for Creator</shortdesc>
- </topicmeta>
- <topicref navtitle="QML Module QtQuick 1" href="qtquick-1.xml">
- <topicref navtitle="QML Mouse Events" href="qtquick2-mouseevents.xml"/>
- <topicref navtitle="Property Binding" href="qtquick2-propertybinding.xml"/>
- </topicref>
- <topicref navtitle="QML Module QtQuick 2" href="qtquick-2.xml">
- <mapref navtitle="Creator Manual" href="creator-manual.ditamap"/>
- <topicref navtitle="QML Mouse Events" href="qtquick2-mouseevents.xml"/>
- <topicref navtitle="Property Binding" href="qtquick2-propertybinding.xml"/>
- </topicref>
- <topicref navtitle="QML Module QtQuick.Particles 2" href="qtquick-particles-2.xml">
- <topicref navtitle="Age" href="qml-qtquick-particles2-age.xml"/>
- </topicref>
- </map>
- \endcode
-
-*/
-
-/*!
- \page 21-0-qdoc-configuration.html
- \previouspage Creating DITA Maps
- \contentspage QDoc Manual
- \nextpage Generic Configuration Variables
-
- \title The QDoc Configuration File
-
- Before running QDoc, you must create a QDoc configuration file to
- tell QDoc where to find the source files that contain the QDoc
- comments. The pathname to your configuration file is passed to
- QDoc on the command line:
-
- \quotation
- \c {/current/dir$ ../../bin/qdoc ./config.qdocconf}
- \endquotation
-
- \section1 General Description
-
- The configuration file is a list of entries of the form \e
- {"variable = value"}. Using the configuration variables, you can
- define where QDoc should find the various source files, images and
- examples, where to put generated documentation etc. The
- configuration file can also contain directives like \c
- include. For an example, see the \l minimum.qdocconf file.
-
- You can also use configuration variables to get QDoc to support
- \l{Supporting Derived Projects} {derived projects}, i.e QDoc can
- generate links in your project's documentation to elements in the
- Qt online documentation. See the \l {Supporting Derived projects}
- section.
-
- The value of a configuration variable can be set using either '='
- or '+='. The difference is that '=' overrides the previous value,
- while '+=' adds a new value to the current one.
-
- Some configuration variables accept a list of strings as their
- value, for example:
- \l {22-qdoc-configuration-generalvariables.html#sourcedirs-variable}
- {\c{sourcedirs}}, while others accept only a single string. Double
- quotes around a value string are optional, but including them allows
- you to use special characters like '=' and ' \" ' within the value
- string, for example:
-
- \code
- HTML.postheader = "<a href=\"index.html\">Home</a>"
- \endcode
-
- If an entry spans many lines, use a backslash at the end of every
- line but the last:
-
- \code
- sourcedirs = kernel \
- tools \
- widgets
- \endcode
-
- \section1 Configuration Variables
-
- \section1 Variable List
-
- \list
- \li \l {22-qdoc-configuration-generalvariables.html#alias-variable} {alias}
- \li \l {23-qdoc-configuration-cppvariables.html#Cpp.ignoredirectives-variable} {Cpp.ignoredirectives}
- \li \l {23-qdoc-configuration-cppvariables.html#Cpp.ignoretokens-variable} {Cpp.ignoretokens}
- \li \l {22-qdoc-configuration-generalvariables.html#defines-variable} {defines}
- \li \l {22-qdoc-configuration-generalvariables.html#edition-variable} {edition}
- \li \l {22-qdoc-configuration-generalvariables.html#exampledirs-variable} {exampledirs}
- \li \l {22-qdoc-configuration-generalvariables.html#examples-variable} {examples}
- \li \l {22-qdoc-configuration-generalvariables.html#examples.fileextensions-variable} {examples.fileextensions}
- \li \l {22-qdoc-configuration-generalvariables.html#excludedirs-variable} {excludedirs}
- \li \l {22-qdoc-configuration-generalvariables.html#excludefiles-variable} {excludefiles}
- \li \l {22-qdoc-configuration-generalvariables.html#extraimages-variable} {extraimages}
- \li \l {22-qdoc-configuration-generalvariables.html#falsehoods-variable} {falsehoods}
- \li \l {22-qdoc-configuration-generalvariables.html#headerdirs-variable} {headerdirs}
- \li \l {22-qdoc-configuration-generalvariables.html#headers-variable} {headers}
- \li \l {22-qdoc-configuration-generalvariables.html#headers.fileextensions-variable} {headers.fileextensions}
- \li \l {24-qdoc-configuration-htmlvariables.html#HTML.footer-variable} {HTML.footer}
- \li \l {24-qdoc-configuration-htmlvariables.html#HTML.postheader-variable} {HTML.postheader}
- \li \l {24-qdoc-configuration-htmlvariables.html#HTML.style-variable} {HTML.style}
- \li \l {22-qdoc-configuration-generalvariables.html#imagedirs-variable} {imagedirs}
- \li \l {22-qdoc-configuration-generalvariables.html#images-variable} {images}
- \li \l {22-qdoc-configuration-generalvariables.html#images.fileextensions-variable} {images.fileextensions}
- \li \l {22-qdoc-configuration-generalvariables.html#language-variable} {language}
- \li \l {22-qdoc-configuration-generalvariables.html#macro-variable} {macro}
- \li \l {22-qdoc-configuration-generalvariables.html#manifestmeta-variable} {manifestmeta}
- \li \l {22-qdoc-configuration-generalvariables.html#outputdir-variable} {outputdir}
- \li \l {22-qdoc-configuration-generalvariables.html#outputformats-variable} {outputformats}
- \li \l {22-qdoc-configuration-generalvariables.html#sourcedirs-variable} {sourcedirs}
- \li \l {22-qdoc-configuration-generalvariables.html#sources-variable} {sources}
- \li \l {22-qdoc-configuration-generalvariables.html#sources.fileextensions-variable} {sources.fileextensions}
- \li \l {22-qdoc-configuration-generalvariables.html#spurious-variable} {spurious}
- \li \l {22-qdoc-configuration-generalvariables.html#tabsize-variable} {tabsize}
- \li \l {22-qdoc-configuration-generalvariables.html#version-variable} {version}
- \li \l {22-qdoc-configuration-generalvariables.html#versionsym-variable} {versionsym}
- \endlist
-
- \section1 Categories
-
- \list
- \li \l {Generic Configuration Variables}
- \li \l {C++ Specific Configuration Variables}
- \li \l {HTML Specific Configuration Variables}
- \endlist
-
- \section1 Configuration File Examples
-
- \list
- \li A minimum configuration file: \l minimum.qdocconf
- \li The Qt configuration file: \l qtgui.qdocconf
- \endlist
-*/
-
-/*!
- \page 21-1-minimum-qdocconf.html
- \previouspage qtgui.qdocconf
- \contentspage QDoc Manual
- \nextpage Generating DITA XML Output
-
- \title minimum.qdocconf
-
- \quotefile examples/minimum.qdocconf
-*/
-
-/*!
- \page 21-2-qtgui-qdocconf.html
- \previouspage Supporting Derived Projects
- \contentspage QDoc Manual
- \nextpage minimum.qdocconf
-
- \title qtgui.qdocconf
-
- \quotefile files/qtgui.qdocconf
-*/
-
-/*!
- \page 21-3-qt-dita-xml-output.html
- \previouspage minimum.qdocconf
- \contentspage QDoc Manual
- \nextpage QDoc Manual
-
- \title Generating DITA XML Output
-
- QDoc can generate \l {http://dita.xml.org} {DITA XML output}.
-
- In your configuration file, set your \c {outputformats} variable
- to \c {DITAXML}, and send the output to an appropriate directory:
-
- \code
- outputdir = $QTDIR/doc/ditaxml
- outputformats = DITAXML
- \endcode
-
- And include these macros in your configuration file to prevent
- QDoc from doing some escaping that doesn't validate in XML:
-
- \code
- macro.aacute.DITAXML = "&aacute;"
- macro.Aring.DITAXML = "&Aring;"
- macro.aring.DITAXML = "&aring;"
- macro.Auml.DITAXML = "&Auml;"
- macro.br.DITAXML = " "
- macro.BR.DITAXML = " "
- macro.copyright.DITAXML = "&copy;"
- macro.eacute.DITAXML = "&eacute;"
- macro.hr.DITAXML = " "
- macro.iacute.DITAXML = "&iacute;"
- macro.oslash.DITAXML = "&oslash;"
- macro.ouml.DITAXML = "&ouml;"
- macro.raisedaster.DITAXML = "<sup>*</sup>"
- macro.rarrow.DITAXML = "&rarr;"
- macro.reg.DITAXML = "<sup>&reg;</sup>"
- macro.uuml.DITAXML = "&uuml;"
- macro.mdash.DITAXML = "&mdash;"
- macro.emptyspan.DITAXML = " "
- \endcode
-
- You can also set default values for some of the tags in the DITA
- \c {<prolog>} and \c {<metadata>} elements:
-
- \code
- dita.metadata.default.author = Qt Development Frameworks
- dita.metadata.default.permissions = all
- dita.metadata.default.publisher = Qt Project
- dita.metadata.default.copyryear = 2013
- dita.metadata.default.copyrholder = Qt Project
- dita.metadata.default.audience = programmer
- \endcode
-
- See the \l {12-0-qdoc-commands-miscellaneous.html#meta-command}
- {\\meta} command for more details on DITA metadata.
-
-*/
-
-/*!
- \page 22-qdoc-configuration-generalvariables.html
- \previouspage The QDoc Configuration File
- \contentspage QDoc Manual
- \nextpage Creating Help Project Files
-
- \title Generic Configuration Variables
-
- With the general QDoc configuration variables, you can define
- where QDoc will find the various source files it needs to generate
- the documentation, as well as the directory to put the generated
- documentation. You can also do some minor manipulation of QDoc
- itself, controlling its output and processing behavior.
-
- \target alias-variable
- \section1 alias
-
- The \c alias variable renames a QDoc command.
-
- The general syntax is \tt {alias.\e{original-command-name} = \e
- temporary-command-name}.
-
- \code
- alias.e = i
- \endcode
-
- This renames the built-in command \\e (italics) to be \\i. The \c
- alias variable is often used for compatibility reasons.
-
- See also \l {macro-variable} {macro}.
-
- \target codeindent-variable
- \section1 codeindent
-
- The \c codeindent variable specifies the level of indentation that
- QDoc uses when writing code snippets.
-
- QDoc originally used a hard-coded value of four spaces for code
- indentation to ensure that code snippets could be easily
- distinguished from surrounding text. Since we can use \l{HTML
- Specific Configuration Variables#HTML.stylesheets} {stylesheets}
- to adjust the appearance of certain types of HTML elements, this
- level of indentation is not always required.
-
- \target defines-variable
- \section1 defines
-
- The \c defines variable specifies the C++ preprocessor symbols
- that QDoc will recognize and respond to.
-
- When a preprocessor symbol is specified using the \c defines
- variable, you can also use the \l {if-command} {\\if} command to
- enclose documentation that only will be included if the
- preprocessor symbol is defined.
-
- The values of the variable are regular expressions (see QRegExp
- for details). By default, no symbol is defined, meaning that code
- protected with #ifdef...#endif will be ignored.
-
- \code
- defines = Q_QDOC \
- QT_.*_SUPPORT \
- QT_.*_LIB \
- QT_COMPAT \
- QT3_SUPPORT \
- Q_WS_.* \
- Q_OS_.* \
- Q_BYTE_ORDER \
- __cplusplus
- \endcode
-
- This ensures that QDoc will process the code that requires these
- symbols to be defined. For example:
-
- \code
- #ifdef Q_WS_WIN
- HDC getDC() const;
- void releaseDC(HDC) const;
- #endif
- \endcode
-
- Since the Q_WS_.* regular expression (specified using the \c
- defines variable) matches Q_WS_WIN, QDoc will process the code
- within #ifdef and #endif in our example.
-
- You can also define preprocessor symbols manually on the command
- line using the -D option. For example:
-
- \code
- currentdirectory$ qdoc -Dconsoleedition qtgui.qdocconf
- \endcode
-
- In this case the -D option ensures that the \c consoleedition
- preprocessor symbol is defined when QDoc processes the source
- files defined in the qtgui.qdocconf file.
-
- See also \l {falsehoods-variable} {falsehoods} and \l {if-command} {\\if}.
-
- \target edition-variable
- \section1 edition
-
- The \c edition variable specifies which modules are included in
- each edition of a package, and provides QDoc with information to
- provide class lists for each edition.
-
- This feature is mostly used when providing documentation for Qt
- packages.
-
- The \c edition variable is always used with a particular edition
- name to define the modules for that edition:
-
- \code
- edition.Console = QtCore QtNetwork QtSql QtXml
- edition.Desktop = QtCore QtGui QtNetwork QtOpenGL QtSql QtXml \
- QtDesigner QtAssistant Qt3Support QAxContainer \
- QAxServer
- edition.DesktopLight = QtCore QtGui Qt3SupportLight
- \endcode
-
- In the above examples, the \c Console edition only includes the
- contents of four modules. Only the classes from these modules will
- be used when the \l{Miscellaneous#generatelist-command}
- {generatelist} command is used to generate a list of classes for
- this edition:
-
- \code
- \generatelist{classesbyedition Console}
- \endcode
-
- \target exampledirs-variable
- \section1 exampledirs
-
- The \c exampledirs variable specifies the directories containing
- the source code of the example files.
-
- The \l {examples-variable} {examples} {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.
-
- \code
- exampledirs = $QTDIR/doc/src \
- $QTDIR/examples \
- $QTDIR \
- $QTDIR/qmake/examples
-
- examples = $QTDIR/examples/widgets/analogclock/analogclock.cpp
- \endcode
-
- When processing
-
- \code
- \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} {\c examples} variable. If
- there isn't, it will search in the \c exampledirs variable, and
- first see if there exists a file called
-
- \code
- $QTDIR/doc/src/widgets/calculator/calculator.cpp
- \endcode
-
- If it doesn't, QDoc will continue looking for a file called
-
- \code
- $QTDIR/examples/widgets/calculator/calculator.cpp
- \endcode
-
- and so forth.
-
- See also \l 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} {\\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:
-
- \code
- \quotefromfile calculator.cpp
- \endcode
-
- See also \l {exampledirs-variable} {exampledirs}.
-
- \target examples.fileextensions-variable
- \section1 examples.fileextensions
-
- The \c examples.fileextensions variable specifies the file
- extensions that qdoc will look for when collecting example files
- for display in the documentation.
-
- The default extensions are *.cpp, *.h, *.js, *.xq, *.svg, *.xml
- and *.ui.
-
- The extensions are given as standard wildcard expressions. You
- can add a file extension to the filter using '+='. For example:
-
- \code
- 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:
-
- \code
- 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.
-
- \code
- excludefiles += $QT_CORE_SOURCES/../../src/widgets/kernel/qwidget.h \
- $QT_CORE_SOURCES/../../src/widgets/kernel/qwidget.cpp
- \endcode
-
- If you include the above in your qdocconf file for qtbase, there
- will be no qwidget.html generated for html and no qwidget.xml
- generated for DITA XML.
-
- See also \l {excludedirs-variable} {excludedirs}.
-
- \target extraimages-variable
- \section1 extraimages
-
- The \c extraimages variable tells QDoc to incorporate specific
- images in the generated documentation.
-
- QDoc will not recognize images used within HTML (or any other
- markup language). If we want the images to be copied from the
- directories specified by \l {imagedirs} {\c imagedirs} (the images
- in question must be located in these directories) to the output
- directory, we must specify the images using the \c extraimages
- variable.
-
- The general syntax is \tt {extraimages.\e{format} = \e image}. The
- file extension is optional.
-
- For example, in \l qtgui.qdocconf we use a couple of images within
- the HTML.postheader variable which value is pure HTML. For that
- reason, these images are specified using the \c extraimages
- variable:
-
- \code
- extraimages.HTML = qt-logo
- \endcode
-
- See also \l images and \l imagedirs.
-
- \target falsehoods-variable
- \section1 falsehoods
-
- The \c falsehoods variable defines the truth value of specified
- preprocessor symbols as false.
-
- If this variable is not set for a preprocessor symbol, QDoc
- assumes its truth value is true. The exception is '0', which value
- always is false.
-
- QDoc will recognize, and is able to evaluate, the following
- preprocessor syntax:
-
- \code
- #ifdef NOTYET
- ...
- #endif
-
- #if defined (NOTYET)
- ...
- #end if
- \endcode
-
- However, faced with unknown syntax like
-
- \code
- #if NOTYET
- ...
- #endif
- \endcode
-
- QDoc will evaluate it as true by default, \e unless the
- preprocessor symbol is specified within the \c falsehoods variable
- entry:
-
- \code
- 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.
-
- \code
- headerdirs = $QTDIR/src \
- $QTDIR/extensions/activeqt \
- $QTDIR/extensions/motif \
- $QTDIR/tools/designer/src/lib/extension \
- $QTDIR/tools/designer/src/lib/sdk \
- $QTDIR/tools/designer/src/lib/uilib
- \endcode
-
- When executed, the first thing QDoc will do is to read through the
- headers specified in the \l {headers} {\c headers} variable, and
- the ones located in the directories specified in the \c headerdir
- variable (including all subdirectories), building an internal
- structure of the classes and their functions.
-
- Then it will read through the sources specified in the \l
- {sources-variable} {\c sources}, and the ones located in the
- directories specified in the \l {sourcedirs-variable} {\c
- sourcedirs} varible (including all subdirectories), merging the
- documentation with the structure it retrieved from the header
- files.
-
- If both the \c headers and \c headerdirs variables are defined,
- QDoc will read through both, first \l {headers} {\c headers} then
- \c headerdirs.
-
- In the specified directories, QDoc will only read the files with
- the \c fileextensions specified in the \l {headers.fileextensions}
- {\c headers.fileextensions} variable. The default extensions are
- *.ch, *.h, *.h++, *.hh, *.hpp, and *.hxx". The files specified by
- \l {headers} {\c headers} will be read without taking into account
- their fileextensions.
-
- See also \l headers and \l headers.fileextensions.
-
- \target headers-variable
- \section1 headers
-
- The \c headers variable allows you to specify individual header
- files in addition to those located in the directories specified by
- the \l {headerdirs} {\c headerdirs} variable.
-
- \code
- 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:
-
- \code
- header.fileextensions += *.H
- \endcode
-
- \warning The above assignment may not work as described.
-
- See also \l headerdirs.
-
- \target imagedirs-variable
- \section1 imagedirs
-
- The \c imagedirs variable specifies the directories containing the
- images used in the documentation.
-
- The \l {images} {\c images} and \c imagedirs variables are used by
- the \l {image-command} {\\image} and \l {inlineimage-command}
- {\\inlineimage} commands. If both the \l {images} {\c images} and
- \c imagedirs variables are defined, QDoc will search in both. First
- in \l {images} {\c images}, then in \c imagedirs.
-
- QDoc will search through the directories in the specified order,
- and accept the first matching file it finds. It will only search
- in the specified directories, \e not in subdirectories.
-
- \code
- imagedirs = $QTDIR/doc/src/images \
- $QTDIR/examples
-
- images = $QTDIR/doc/src/images/calculator-example.png
- \endcode
-
- When processing
-
- \code
- \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:
-
- \code
- $QTDIR/doc/src/images/calculator-example.png
- \endcode
-
- If the file doesn't exist, QDoc will look for a file called
-
- \code
- $QTDIR/examples/calculator-example.png
- \endcode
-
- You can filter the images in an image directory using the \l
- {images.fileextensions} {\c images.fileextensions} variable. The
- general idea behind the \l {images.fileextensions} {\c images.fileextensions}
- variable is to enable different image format for different output format.
-
- \warning The \l {images.fileextensions} {\c images.fileextensions}
- variable's functionality is preliminary since QDoc at this point
- only supports HTML.
-
- See also \l images and \l images.fileextensions.
-
- \target images-variable
- \section1 images
-
- The \c images variable allows you to specify individual image
- files in addition to those located in the directories specified by
- the \l {imagedirs} {\c imagedirs} variable.
-
- \code
- images = $QTDIR/doc/src/images/calculator-example.png
- \endcode
-
- When processing the \c images variable, QDoc behaves in the same
- way as it does when processing the \l {imagedirs} {\c imagedirs}
- variable. For more information, see the \l {imagedirs} {\c
- imagedirs} variable.
-
- See also \l imagedirs and \l images.fileextensions.
-
- \target images.fileextensions-variable
- \section1 images.fileextensions
-
- The images.fileextensions variable filters the files within an
- image directory.
-
- The variable's values (the extensions) are given as standard
- wildcard expressions. The general syntax is: \tt
- {images.fileextensions.\e{format} = *.\e{extension}}.
-
- The idea is to enable different image format for different output
- format.
-
- \code
- images.fileextensions.HTML = *.png
- images.fileextensions.LOUT = *.eps
- \endcode
-
- Then, when processing the \l {image-command} {\\image} and \l
- {inlineimage-command} {\\inlineimage} commands, QDoc will only
- search for files with extensions specified in the variable
- containing the list of output formats.
-
- \warning This is only a preliminary functionality since QDoc at this
- point only supports HTML.
-
- The default extensions for HTML are *.png, *.jpg, *.jpeg, and
- *.gif.
-
- You can add a file extension to the filter using '+='. For
- example:
-
- \code
- images.fileextensions.HTML += *.eps
- \endcode
-
- See also \l imagedirs and \l images.
-
- \target language-variable
- \section1 language
-
- The \c language variable specifies the language of the source code
- that is used in the documentation.
-
- Currently, C++ is the only language that QDoc understands. It is
- also the default language, and doesn't really need to be
- specified. However, a possible example of a language variable
- statement:
-
- \code
- language = Cpp
- \endcode
-
- This identifies C++ as the language of the Qt source code.
-
- \target macro-variable
- \section1 macro
-
- The \c macro variable is used to create your own simple QDoc
- commands. The syntax is \tt {macro.\e{command} = \e{definition}},
- where the definition is written using QDoc syntax.
-
- A macro variable can be restricted for use in one type of output
- generation. By appending \c {.HTML} to the macro name, for
- example, the macro is only used when generating HTML output. By
- appending \c {.DITAXML} to the macro name, the macro is only used
- when generating DITA XML.
-
- \code
- macro.gui = "\\b"
- macro.raisedaster.HTML = "<sup>*</sup>"
- \endcode
-
- The first macro defines the \\gui command to render its argument
- using a bold font. The second macro defines the \\raisedaster
- command to render a superscript asterisk, but only when generating
- HTML.
-
- See also \l {alias-variable} {alias}.
-
- \target manifestmeta-variable
- \section1 manifestmeta
-
- The \c manifestmeta variable specifies additional meta-content
- for the example manifest files generated by QDoc.
-
- See the \l{Manifest Meta Content} section for more information.
-
- \target naturallanguage-variable
- \section1 naturallanguage
-
- The \c naturallanguage variable specifies the natural language
- used for the documentation generated by qdoc.
-
- \code
- naturallanguage = zh-Hans
- \endcode
-
- By default, the natural language is \c en for compatibility with
- legacy documentation.
-
- qdoc will add the natural language information to the HTML it
- generates, using the \c lang and \c xml:lang attributes.
-
- See also \l {sourceencoding-variable} {sourceencoding},
- \l {outputencoding-variable} {outputencoding},
- \l{http://www.w3.org/TR/xhtml1/#C_7}
- {C.7. The lang and xml:lang Attributes} and
- \l{http://www.w3.org/TR/i18n-html-tech-lang/#ri20040429.113217290}
- {Best Practice 13: Using Hans and Hant codes}.
-
- \target outputdir-variable
- \section1 outputdir
-
- The \c outputdir variable specifies the directory where QDoc will
- put the generated documentation.
-
- \code
- 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
-
- \code
- $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.
-
- \code
- outputencoding = UTF-8
- \endcode
-
- By default, the output encoding is \c ISO-8859-1 (Latin1) for
- compatibility with legacy documentation. When generating
- documentation for some languages, particularly non-European
- languages, this is not sufficient and an encoding such as UTF-8 is
- required.
-
- qdoc will encode HTML using this encoding and generate the correct
- declarations to indicate to browsers which encoding is being
- used. The \l naturallanguage configuration variable should also be
- specified to provide browsers with a complete set of character
- encoding and language information.
-
- See also \l outputencoding and \l naturallanguage.
-
- \target outputformats-variable
- \section1 outputformats
-
- The \c outputformats variable specifies the format of
- the generated documentation.
-
- Currently, QDoc only supports the HTML format. It is also
- the default format, and doesn't need to be specified.
-
- \target outputprefixes
- \section1 outputprefixes
-
- The \c outputprefixes variable specifies a mapping between types of files
- and the prefixes to prepend to the HTML file names in the generated
- documentation.
-
- \code
- outputprefixes = QML
- outputprefixes.QML = uicomponents-
- \endcode
-
- By default, files containing the API documentation for QML types
- are prefixed with "qml-". In the above example, the
- prefix \c "uicomponents" is used instead.
-
- \target qhp-variable
- \section1 qhp
-
- The \c qhp variable is used to define the information to be
- written out to Qt Help Project (\c{qhp}) files.
-
- See the \l{Creating Help Project Files} chapter for information
- about this process.
-
- \target sourcedirs-variable
- \section1 sourcedirs
-
- The \c sourcedirs variable specifies the directories containing
- the \c .cpp or \c .qdoc files used in the documentation.
-
- \code
- sourcedirs += .. \
- ../../../examples/gui/doc/src
- \endcode
-
- When executed, the first thing QDoc will do is to read through the
- headers specified in the \l {header-command} {\c header} variable,
- and the ones located in the directories specified in the \c
- headerdir variable (including all subdirectories), building an
- internal structure of the classes and their functions.
-
- Then it will read through the sources specified in the \l
- {sources} {\c sources}, and the ones located in the directories
- specified in the \l {sourcedirs} {\c sourcedirs} variable
- (including all subdirectories), merging the documentation with the
- structure it retrieved from the header files.
-
- If both the \c sources and \c sourcedirs variables are defined,
- QDoc will read through both, first \l {sources} {\c sources} then
- \c sourcedirs.
-
- In the specified directories, QDoc will only read the files with
- the \c fileextensions specified in the \l {sources.fileextensions}
- {\c sources.fileextensions} variable. The default extensions are
- *.c++, *.cc, *.cpp and *.cxx. The files specified by \l {sources}
- {\c sources} will be read independent of their fileextensions.
-
- See also \l {sources-variable} {sources} and
- \l {sources.fileextensions-variable} {sources.fileextensions}.
-
- \target sourceencoding-variable
- \section1 sourceencoding
-
- The \c sourceencoding variable specifies the encoding used for the
- source code and documentation.
-
- \code
- 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.
-
- \code
- sources = $QTDIR/src/gui/widgets/qlineedit.cpp \
- $QTDIR/src/gui/widgets/qpushbutton.cpp
- \endcode
-
- When processing the \c sources variable, QDoc behaves in the same
- way as it does when processing the \l {sourcedirs-variable}
- {sourcedirs} variable. For more information, see the \l
- {sourcedirs-variable} {sourcedirs} variable.
-
- See also \l {sourcedirs-variable} {sourcedirs}.
-
- \target sources.fileextensions-variable
- \section1 sources.fileextensions
-
- The \c sources.fileextensions variable filters the files within a
- source directory.
-
- When processing the source files specified in the \l {sourcedirs}
- {\c sourcedirs} variable, QDoc will only read the files with the
- fileextensions specified in the \c sources.fileextensions
- variable. In this way QDoc avoid spending time reading irrelevant
- files.
-
- The default extensions are *.c++, *.cc, *.cpp and *.cxx.
-
- The extensions are given as standard wildcard expressions. You
- can add a file extension to the filter using '+='. For example:
-
- \code
- 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.
-
- \code
- 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:
-
- \code
- qt-4.0/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.
-
- \code
- 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.
-
- \code
- 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.
-
- \code
- version = 4.0.1
- \endcode
-
- When a version number is specified (using the \tt{\l version} or
- \tt {\l versionsym} variables in a \c .qdocconf file), it is
- accessible through the corresponding \\version command for use in
- the documentation.
-
- \warning The \\version command's functionality is not fully
- implemented; currently it only works within raw HTML code.
-
- See also \l versionsym.
-
- \target versionsym-variable
- \section1 versionsym
-
- The \c versionsym variable specifies a C++ preprocessor symbol