Merge "Merge branch 'docs-refactoring' into master" into refs/staging/master

examples/examples.pro

@@ -1,4 +1,6 @@
 TEMPLATE      = subdirs
+CONFIG += no_docs_target
+
 SUBDIRS       = \
                 network \
                 statemachine \

mkspecs/features/default_post.prf

@@ -64,3 +64,30 @@ QMAKE_LIBDIR += $$QMAKE_LIBDIR_POST
     QMAKE_EXTRA_TARGETS += check
 }
 
+# Let every project have a 'docs' target
+!contains(QMAKE_EXTRA_TARGETS, docs) {
+    contains(TEMPLATE, subdirs) {
+        # `make docs' should iterate through all subdirs
+        # (except those with no_default_target or no_docs_target)
+        !contains(CONFIG, no_docs_target):for(subdir, SUBDIRS) {
+            subdir_config = $$eval($${subdir}.CONFIG)
+            !contains(subdir_config, no_docs_target):!contains(subdir_config, no_default_target):docs.recurse += $$subdir
+            unset(subdir_config)
+        }
+        !isEmpty(docs.recurse) {
+            # setup the recurse target only when there is something to recurse into
+            docs.CONFIG = recursive
+            docs.recurse_target = docs
+        }
+    } else {
+        # apps and libs only generate docs if QMAKE_DOCS is set
+        !isEmpty(QMAKE_DOCS) {
+            !exists($$QMAKE_DOCS):error("Cannot find documentation specification file $$QMAKE_DOCS")
+            exists($$[QT_INSTALL_DOCS]):QMAKE_DOCS_INDEX *= $$[QT_INSTALL_DOCS]
+            qtPrepareTool(QDOC, qdoc)
+            for(index, QMAKE_DOCS_INDEX):QDOC_INDEX += -indexdir $$index
+            docs.commands += $$QDOC $$QMAKE_DOCS_OPTIONS $$QDOC_INDEX $$QMAKE_DOCS
+        }
+    }
+    QMAKE_EXTRA_TARGETS += docs
+}

src/concurrent/concurrent.pro

@@ -57,6 +57,9 @@ HEADERS += \
         qfutureinterface_p.h \
         qfuturewatcher_p.h
 
+QMAKE_DOCS = $$PWD/doc/qtconcurrent.qdocconf
+QMAKE_DOCS_INDEX = ../../doc
+
 contains(QT_CONFIG, clock-gettime) {
     linux-*|hpux-*|solaris-*:LIBS *= -lrt
 }

src/concurrent/doc/qtconcurrent.qdocconf

@@ -0,0 +1,92 @@
+include(../../../doc/global/qt-cpp-ignore.qdocconf)
+
+project                 = QtConcurrent
+description             = Qt Concurrent Reference Documentation
+url                     = http://qt-project.org/doc/qt-5.0/qtconcurrent
+version                 = 5.0.0
+
+sourceencoding          = UTF-8
+outputencoding          = UTF-8
+naturallanguage         = en_US
+qhp.projects            = QtConcurrent
+
+qhp.QtConcurrent.file         = qtconcurrent.qhp
+qhp.QtConcurrent.namespace           = org.qt-project.qtconcurrent.500
+qhp.QtConcurrent.virtualFolder       = qdoc
+qhp.QtConcurrent.indexTitle          = Qt Concurrent Reference Documentation
+qhp.QtConcurrent.indexRoot           =
+
+qhp.QtConcurrent.filterAttributes    = qtconcurrent 5.0.0 qtrefdoc
+qhp.QtConcurrent.customFilters.Qt.name = QtConcurrent 5.0.0
+qhp.QtConcurrent.customFilters.Qt.filterAttributes = qtconcurrent 5.0.0
+qhp.QtConcurrent.subprojects         = classes overviews examples
+qhp.QtConcurrent.subprojects.classes.title = Classes
+qhp.QtConcurrent.subprojects.classes.indexTitle = Qt Concurrent's Classes
+qhp.QtConcurrent.subprojects.classes.selectors = class fake:headerfile
+qhp.QtConcurrent.subprojects.classes.sortPages = true
+qhp.QtConcurrent.subprojects.overviews.title = Overviews
+qhp.QtConcurrent.subprojects.overviews.indexTitle = All Overviews and HOWTOs
+qhp.QtConcurrent.subprojects.overviews.selectors = fake:page,group,module
+qhp.QtConcurrent.subprojects.examples.title = Qt Concurrent Examples
+qhp.QtConcurrent.subprojects.examples.indexTitle = Qt Concurrent Examples
+qhp.QtConcurrent.subprojects.examples.selectors = fake:example
+
+dita.metadata.default.author      = Qt Project
+dita.metadata.default.permissions = all
+dita.metadata.default.publisher   = Qt Project
+dita.metadata.default.copyryear = 2012
+dita.metadata.default.copyrholder = Nokia
+dita.metadata.default.audience = programmer
+
+sources.fileextensions  = "*.c++ *.cc *.cpp *.cxx *.mm *.qml *.qdoc"
+headers.fileextensions  = "*.ch *.h *.h++ *.hh *.hpp *.hxx"
+
+examples.fileextensions = "*.cpp *.h *.js *.xq *.svg *.xml *.ui *.qhp *.qhcp *.qml *.css"
+examples.imageextensions = "*.png"
+
+outputdir               = ../../../doc/qtconcurrent
+tagfile                 = ../../../doc/qtconcurrent/qtconcurrent.tags
+
+HTML.generatemacrefs    = "true"
+HTML.nobreadcrumbs      = "true"
+
+HTML.templatedir = .
+
+HTML.stylesheets = ../../../doc/global/style/offline.css
+
+HTML.headerstyles = \
+    "  <link rel=\"stylesheet\" type=\"text/css\" href=\"style/offline.css\" />\n"
+
+HTML.endheader = \
+    "</head>\n" \
+
+defines                 = Q_QDOC \
+                          QT_.*_SUPPORT \
+                          QT_.*_LIB \
+                          QT_COMPAT \
+                          QT_KEYPAD_NAVIGATION \
+                          QT_NO_EGL \
+                          Q_WS_.* \
+                          Q_OS_.* \
+                          Q_BYTE_ORDER \
+                          QT_DEPRECATED \
+                          QT_DEPRECATED_* \
+                          Q_NO_USING_KEYWORD \
+                          __cplusplus \
+                          Q_COMPILER_INITIALIZER_LISTS
+
+versionsym              = QT_VERSION_STR
+
+codeindent              = 1
+
+depends                 += qtcore
+
+headerdirs  += ..
+
+sourcedirs  += ..
+
+exampledirs += ../../../examples \
+               ../ \
+               snippets
+
+imagedirs   += images

src/concurrent/qfuture.cpp

@@ -374,7 +374,7 @@
     QFuture::constBegin() or QFuture::constEnd() before you start iterating.
     Here's a typical loop that prints all the results available in a future:
 
-    \snippet doc/src/snippets/code/src_corelib_concurrent_qfuture.cpp 0
+    \snippet code/src_concurrent_qfuture.cpp 0
 
     \sa QFutureIterator, QFuture
 */
@@ -555,7 +555,7 @@
     list (i.e. before the first result). Here's how to iterate over all the
     results sequentially:
 
-    \snippet doc/src/snippets/code/src_corelib_concurrent_qfuture.cpp 1
+    \snippet code/src_concurrent_qfuture.cpp 1
 
     The next() function returns the next result (waiting for it to become
     available, if necessary) from the future and advances the iterator. Unlike
@@ -570,7 +570,7 @@
 
     Here's how to iterate over the elements in reverse order:
 
-    \snippet doc/src/snippets/code/src_corelib_concurrent_qfuture.cpp 2
+    \snippet code/src_concurrent_qfuture.cpp 2
 
     If you want to find all occurrences of a particular value, use findNext()
     or findPrevious() in a loop.

src/concurrent/qfuturesynchronizer.cpp

@@ -57,7 +57,7 @@
     an easy way to ensure that all futures have finished before returning from
     a function:
     
-    \snippet doc/src/snippets/code/src_corelib_concurrent_qfuturesynchronizer.cpp 0
+    \snippet code/src_concurrent_qfuturesynchronizer.cpp 0
     
     The behavior of waitForFinished() can be changed using the
     setCancelOnWait() function. Calling setCancelOnWait(true) will cause

src/concurrent/qfuturewatcher.cpp

@@ -86,7 +86,7 @@ QT_BEGIN_NAMESPACE
     Example: Starting a computation and getting a slot callback when it's
     finished:
 
-    \snippet doc/src/snippets/code/src_corelib_concurrent_qfuturewatcher.cpp 0
+    \snippet code/src_concurrent_qfuturewatcher.cpp 0
 
     Be aware that not all asynchronous computations can be canceled or paused.
     For example, the future returned by QtConcurrent::run() cannot be

src/concurrent/qtconcurrentexception.cpp

@@ -56,12 +56,12 @@ QT_BEGIN_NAMESPACE
     boundaries, provided that the exception inherit from QtConcurrent::Exception
     and implement two helper functions:
 
-    \snippet doc/src/snippets/code/src_corelib_concurrent_qtconcurrentexception.cpp 0
+    \snippet code/src_concurrent_qtconcurrentexception.cpp 0
 
     QtConcurrent::Exception subclasses must be thrown by value and
     caught by reference:
 
-    \snippet doc/src/snippets/code/src_corelib_concurrent_qtconcurrentexception.cpp 1
+    \snippet code/src_concurrent_qtconcurrentexception.cpp 1
 
     If you throw an exception that is not a subclass of QtConcurrent::Exception,
     the Qt Concurrent functions will throw a QtConcurrent::UnhandledException
@@ -80,14 +80,14 @@ QT_BEGIN_NAMESPACE
     \fn QtConcurrent::Exception::raise() const 
     In your QtConcurrent::Exception subclass, reimplement raise() like this:
     
-    \snippet doc/src/snippets/code/src_corelib_concurrent_qtconcurrentexception.cpp 2
+    \snippet code/src_concurrent_qtconcurrentexception.cpp 2
 */
 
 /*!
     \fn QtConcurrent::Exception::clone() const
     In your QtConcurrent::Exception subclass, reimplement clone() like this:
     
-    \snippet doc/src/snippets/code/src_corelib_concurrent_qtconcurrentexception.cpp 3
+    \snippet code/src_concurrent_qtconcurrentexception.cpp 3
 */
 
 /*! 

src/concurrent/qtconcurrentfilter.cpp

@@ -60,7 +60,7 @@
     result instead of a QFuture. You use them in the same way as the
     asynchronous variants.
 
-    \snippet doc/src/snippets/code/src_corelib_concurrent_qtconcurrentfilter.cpp 6
+    \snippet code/src_concurrent_qtconcurrentfilter.cpp 6
 
     Note that the result types above are not QFuture objects, but real result
     types (in this case, QStringList and QSet<QString>).
@@ -73,7 +73,7 @@
 
     The filter function must be of the form:
 
-    \snippet doc/src/snippets/code/src_corelib_concurrent_qtconcurrentfilter.cpp 0
+    \snippet code/src_concurrent_qtconcurrentfilter.cpp 0
 
     T must match the type stored in the sequence. The function returns true if
     the item should be kept, false if it should be discarded.
@@ -81,7 +81,7 @@
     This example shows how to keep strings that are all lower-case from a
     QStringList:
 
-    \snippet doc/src/snippets/code/src_corelib_concurrent_qtconcurrentfilter.cpp 1
+    \snippet code/src_concurrent_qtconcurrentfilter.cpp 1
 
     The results of the filter are made available through QFuture. See the
     QFuture and QFutureWatcher documentation for more information on how to
@@ -89,7 +89,7 @@
 
     If you want to modify a sequence in-place, use QtConcurrent::filter():
 
-    \snippet doc/src/snippets/code/src_corelib_concurrent_qtconcurrentfilter.cpp 2
+    \snippet code/src_concurrent_qtconcurrentfilter.cpp 2
 
     Since the sequence is modified in place, QtConcurrent::filter() does not
     return any results via QFuture. However, you can still use QFuture and
@@ -103,7 +103,7 @@
 
     The reduce function must be of the form:
 
-    \snippet doc/src/snippets/code/src_corelib_concurrent_qtconcurrentfilter.cpp 3
+    \snippet code/src_concurrent_qtconcurrentfilter.cpp 3
 
     T is the type of the final result, U is the type of items being filtered.
     Note that the return value and return type of the reduce function are not
@@ -111,7 +111,7 @@
 
     Call QtConcurrent::filteredReduced() like this:
 
-    \snippet doc/src/snippets/code/src_corelib_concurrent_qtconcurrentfilter.cpp 4
+    \snippet code/src_concurrent_qtconcurrentfilter.cpp 4
 
     The reduce function will be called once for each result kept by the filter
     function, and should merge the \e{intermediate} into the \e{result}
@@ -128,7 +128,7 @@
     instead of a sequence. You use them in the same way as the sequence
     variants:
 
-    \snippet doc/src/snippets/code/src_corelib_concurrent_qtconcurrentfilter.cpp 5
+    \snippet code/src_concurrent_qtconcurrentfilter.cpp 5
 
 
     \section2 Using Member Functions
@@ -137,12 +137,12 @@
     QtConcurrent::filteredReduced() accept pointers to member functions.
     The member function class type must match the type stored in the sequence:
 
-    \snippet doc/src/snippets/code/src_corelib_concurrent_qtconcurrentfilter.cpp 7
+    \snippet code/src_concurrent_qtconcurrentfilter.cpp 7
 
     Note that when using QtConcurrent::filteredReduced(), you can mix the use of
     normal and member functions freely:
 
-    \snippet doc/src/snippets/code/src_corelib_concurrent_qtconcurrentfilter.cpp 8
+    \snippet code/src_concurrent_qtconcurrentfilter.cpp 8
 
     \section2 Using Function Objects
 
@@ -151,7 +151,7 @@
     add state to a function call. The result_type typedef must define the 
     result type of the function call operator:
 
-    \snippet doc/src/snippets/code/src_corelib_concurrent_qtconcurrentfilter.cpp 13
+    \snippet code/src_concurrent_qtconcurrentfilter.cpp 13
 
     \section2 Using Bound Function Arguments
 
@@ -167,7 +167,7 @@
 
     As an example, we use QString::contains():
 
-    \snippet doc/src/snippets/code/src_corelib_concurrent_qtconcurrentfilter.cpp 9
+    \snippet code/src_concurrent_qtconcurrentfilter.cpp 9
 
     QString::contains() takes 2 arguments (including the "this" pointer) and
     can't be used with QtConcurrent::filtered() directly, because
@@ -175,17 +175,17 @@
     use QString::contains() with QtConcurrent::filtered() we have to provide a
     value for the \e regexp argument:
 
-    \snippet doc/src/snippets/code/src_corelib_concurrent_qtconcurrentfilter.cpp 10
+    \snippet code/src_concurrent_qtconcurrentfilter.cpp 10
 
     The return value from boost::bind() is a function object (functor) with
     the following signature:
 
-    \snippet doc/src/snippets/code/src_corelib_concurrent_qtconcurrentfilter.cpp 11
+    \snippet code/src_concurrent_qtconcurrentfilter.cpp 11
 
     This matches what QtConcurrent::filtered() expects, and the complete
     example becomes:
 
-    \snippet doc/src/snippets/code/src_corelib_concurrent_qtconcurrentfilter.cpp 12
+    \snippet code/src_concurrent_qtconcurrentfilter.cpp 12
 */
 
 /*!

src/concurrent/qtconcurrentmap.cpp

@@ -95,7 +95,7 @@
     the final result instead of a QFuture. You use them in the same
     way as the asynchronous variants.
 
-    \snippet doc/src/snippets/code/src_corelib_concurrent_qtconcurrentmap.cpp 7
+    \snippet code/src_concurrent_qtconcurrentmap.cpp 7
 
     Note that the result types above are not QFuture objects, but real result
     types (in this case, QList<QImage> and QImage).
@@ -108,7 +108,7 @@
 
     The map function must be of the form:
 
-    \snippet doc/src/snippets/code/src_corelib_concurrent_qtconcurrentmap.cpp 0
+    \snippet code/src_concurrent_qtconcurrentmap.cpp 0
 
     T and U can be any type (and they can even be the same type), but T must
     match the type stored in the sequence. The function returns the modified
@@ -117,7 +117,7 @@
     This example shows how to apply a scale function to all the items
     in a sequence:
 
-    \snippet doc/src/snippets/code/src_corelib_concurrent_qtconcurrentmap.cpp 1
+    \snippet code/src_concurrent_qtconcurrentmap.cpp 1
 
     The results of the map are made available through QFuture.  See the
     QFuture and QFutureWatcher documentation for more information on how to
@@ -126,14 +126,14 @@
     If you want to modify a sequence in-place, use QtConcurrent::map(). The
     map function must then be of the form:
 
-    \snippet doc/src/snippets/code/src_corelib_concurrent_qtconcurrentmap.cpp 2
+    \snippet code/src_concurrent_qtconcurrentmap.cpp 2
 
     Note that the return value and return type of the map function are not
     used.
 
     Using QtConcurrent::map() is similar to using QtConcurrent::mapped():
 
-    \snippet doc/src/snippets/code/src_corelib_concurrent_qtconcurrentmap.cpp 3
+    \snippet code/src_concurrent_qtconcurrentmap.cpp 3
 
     Since the sequence is modified in place, QtConcurrent::map() does not
     return any results via QFuture. However, you can still use QFuture and
@@ -147,7 +147,7 @@
 
     The reduce function must be of the form:
 
-    \snippet doc/src/snippets/code/src_corelib_concurrent_qtconcurrentmap.cpp 4
+    \snippet code/src_concurrent_qtconcurrentmap.cpp 4
 
     T is the type of the final result, U is the return type of the map
     function. Note that the return value and return type of the reduce
@@ -155,7 +155,7 @@
 
     Call QtConcurrent::mappedReduced() like this:
 
-    \snippet doc/src/snippets/code/src_corelib_concurrent_qtconcurrentmap.cpp 5
+    \snippet code/src_concurrent_qtconcurrentmap.cpp 5
 
     The reduce function will be called once for each result returned by the map
     function, and should merge the \e{intermediate} into the \e{result}
@@ -175,7 +175,7 @@
     instead of a sequence. You use them in the same way as the sequence
     variants:
 
-    \snippet doc/src/snippets/code/src_corelib_concurrent_qtconcurrentmap.cpp 6
+    \snippet code/src_concurrent_qtconcurrentmap.cpp 6
 
     \section2 Blocking Variants
 
@@ -183,7 +183,7 @@
     the final result instead of a QFuture. You use them in the same
     way as the asynchronous variants.
 
-    \snippet doc/src/snippets/code/src_corelib_concurrent_qtconcurrentmap.cpp 7
+    \snippet code/src_concurrent_qtconcurrentmap.cpp 7
 
     Note that the result types above are not QFuture objects, but real result
     types (in this case, QList<QImage> and QImage).
@@ -194,12 +194,12 @@
     QtConcurrent::mappedReduced() accept pointers to member functions.
     The member function class type must match the type stored in the sequence:
 
-    \snippet doc/src/snippets/code/src_corelib_concurrent_qtconcurrentmap.cpp 8
+    \snippet code/src_concurrent_qtconcurrentmap.cpp 8
 
     Note that when using QtConcurrent::mappedReduced(), you can mix the use of
     normal and member functions freely:
 
-    \snippet doc/src/snippets/code/src_corelib_concurrent_qtconcurrentmap.cpp 9
+    \snippet code/src_concurrent_qtconcurrentmap.cpp 9
 
     \section2 Using Function Objects
 
@@ -208,7 +208,7 @@
     add state to a function call. The result_type typedef must define the 
     result type of the function call operator:
 
-    \snippet doc/src/snippets/code/src_corelib_concurrent_qtconcurrentmap.cpp 14
+    \snippet code/src_concurrent_qtconcurrentmap.cpp 14
 
     \section2 Using Bound Function Arguments
 
@@ -224,7 +224,7 @@
 
     As an example, we'll use QImage::scaledToWidth():
 
-    \snippet doc/src/snippets/code/src_corelib_concurrent_qtconcurrentmap.cpp 10
+    \snippet code/src_concurrent_qtconcurrentmap.cpp 10
 
     scaledToWidth takes three arguments (including the "this" pointer) and
     can't be used with QtConcurrent::mapped() directly, because
@@ -232,17 +232,17 @@
     QImage::scaledToWidth() with QtConcurrent::mapped() we have to provide a
     value for the \e{width} and the \e{transformation mode}:
 
-    \snippet doc/src/snippets/code/src_corelib_concurrent_qtconcurrentmap.cpp 11
+    \snippet code/src_concurrent_qtconcurrentmap.cpp 11
 
     The return value from boost::bind() is a function object (functor) with
     the following signature:
 
-    \snippet doc/src/snippets/code/src_corelib_concurrent_qtconcurrentmap.cpp 12
+    \snippet code/src_concurrent_qtconcurrentmap.cpp 12
 
     This matches what QtConcurrent::mapped() expects, and the complete example
     becomes:
 
-    \snippet doc/src/snippets/code/src_corelib_concurrent_qtconcurrentmap.cpp 13
+    \snippet code/src_concurrent_qtconcurrentmap.cpp 13
 */
 
 /*!

src/concurrent/qtconcurrentrun.cpp

@@ -57,7 +57,7 @@
     
     To run a function in another thread, use QtConcurrent::run():
     
-    \snippet doc/src/snippets/code/src_corelib_concurrent_qtconcurrentrun.cpp 0
+    \snippet code/src_concurrent_qtconcurrentrun.cpp 0
     
     This will run \e aFunction in a separate thread obtained from the default
     QThreadPool. You can use the QFuture and QFutureWatcher classes to monitor
@@ -68,7 +68,7 @@
     Passing arguments to the function is done by adding them to the
     QtConcurrent::run() call immediately after the function name. For example:
     
-    \snippet doc/src/snippets/code/src_corelib_concurrent_qtconcurrentrun.cpp 1
+    \snippet code/src_concurrent_qtconcurrentrun.cpp 1
     
     A copy of each argument is made at the point where QtConcurrent::run() is
     called, and these values are passed to the thread when it begins executing
@@ -79,11 +79,11 @@
     
     Any return value from the function is available via QFuture:
     
-    \snippet doc/src/snippets/code/src_corelib_concurrent_qtconcurrentrun.cpp 2
+    \snippet code/src_concurrent_qtconcurrentrun.cpp 2
     
     As documented above, passing arguments is done like this:
     
-    \snippet doc/src/snippets/code/src_corelib_concurrent_qtconcurrentrun.cpp 3
+    \snippet code/src_concurrent_qtconcurrentrun.cpp 3
     
     Note that the QFuture::result() function blocks and waits for the result
     to become available. Use QFutureWatcher to get notification when the
@@ -102,11 +102,11 @@
     For example, calling QByteArray::split() (a const member function) in a
     separate thread is done like this:
     
-    \snippet doc/src/snippets/code/src_corelib_concurrent_qtconcurrentrun.cpp 4
+    \snippet code/src_concurrent_qtconcurrentrun.cpp 4
     
     Calling a non-const member function is done like this:
 
-    \snippet doc/src/snippets/code/src_corelib_concurrent_qtconcurrentrun.cpp 5
+    \snippet code/src_concurrent_qtconcurrentrun.cpp 5
 
     \section2 Using Bound Function Arguments
 
@@ -131,7 +131,7 @@
 
     Calling a bound function is done like this:
 
-    \snippet doc/src/snippets/code/src_corelib_concurrent_qtconcurrentrun.cpp 6
+    \snippet code/src_concurrent_qtconcurrentrun.cpp 6
 */
 
 /*!

src/corelib/corelib.pro

@@ -16,6 +16,9 @@ load(qt_module_config)
 
 HEADERS += $$QT_SOURCE_TREE/src/corelib/qtcoreversion.h
 
+QMAKE_DOCS = $$PWD/doc/qtcore.qdocconf
+QMAKE_DOCS_INDEX = ../../doc
+
 include(animation/animation.pri)
 include(arch/arch.pri)
 include(global/global.pri)
@@ -30,7 +33,6 @@ include(codecs/codecs.pri)
 include(statemachine/statemachine.pri)
 include(mimetypes/mimetypes.pri)
 include(xml/xml.pri)
-include(doc/doc.pri)
 
 mac|darwin {
     !ios {

src/corelib/doc/doc.pri

@@ -1,3 +0,0 @@
-qtPrepareTool(QDOC, qdoc)
-docs.commands += $$QDOC $$QT.core.sources/doc/qtcore.qdocconf
-QMAKE_EXTRA_TARGETS += docs

src/corelib/doc/src/io.qdoc

@@ -0,0 +1,39 @@
+/****************************************************************************
+**
+** Copyright (C) 2012 Nokia Corporation and/or its subsidiary(-ies).
+** Contact: http://www.qt-project.org/
+**
+** This file is part of the documentation of the Qt Toolkit.
+**
+** $QT_BEGIN_LICENSE:FDL$
+** GNU Free Documentation License
+** 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.
+**
+** Other Usage
+** Alternatively, this file may be used in accordance with the terms
+** and conditions contained in a signed written agreement between you
+** and Nokia.
+**
+**
+**
+**
+**
+** $QT_END_LICENSE$
+**
+****************************************************************************/
+
+/*!
+    \group io
+    \title Input/Output and Networking
+    \ingroup groups
+
+    \brief Classes providing file input and output along with directory and
+    network handling.
+
+    These classes are used to handle input and output to and from external
+    devices, processes, files etc. as well as manipulating files and directories.
+*/
+

src/corelib/doc/src/resource-system.qdoc

@@ -25,18 +25,6 @@
 **
 ****************************************************************************/
 
-/*!
-    \group io
-    \title Input/Output and Networking
-    \ingroup groups
-
-    \brief Classes providing file input and output along with directory and
-    network handling.
-
-    These classes are used to handle input and output to and from external
-    devices, processes, files etc. as well as manipulating files and directories.
-*/
-
 /*!
     \page resources.html
     \title The Qt Resource System
@@ -89,14 +77,14 @@
     is \c images/cut.png. This can be changed using the \c file tag's
     \c alias attribute:
 
-    \snippet doc/src/snippets/code/doc_src_resources.qdoc 0
+    \snippet code/doc_src_resources.qdoc 0
 
     The file is then accessible as \c :/cut-img.png from the
     application. It is also possible to specify a path prefix for all
     files in the \c .qrc file using the \c qresource tag's \c prefix
     attribute:
 
-    \snippet doc/src/snippets/code/doc_src_resources.qdoc 1
+    \snippet code/doc_src_resources.qdoc 1
 
     In this case, the file is accessible as \c
     :/myresources/cut-img.png.
@@ -106,7 +94,7 @@
     attribute to the \c qresource tag, specifying a suitable locale
     string. For example:
 
-    \snippet doc/src/snippets/code/doc_src_resources.qdoc 2
+    \snippet code/doc_src_resources.qdoc 2
 
     If the user's locale is French (i.e., QLocale::system().name() returns
     "fr_FR"), \c :/cut.jpg becomes a reference to the \c cut_fr.jpg
@@ -126,11 +114,11 @@
     For example, a set of resource data specified in a \c .qrc file can be
     compiled in the following way:
 
-    \snippet doc/src/snippets/code/doc_src_resources.qdoc 3
+    \snippet code/doc_src_resources.qdoc 3
 
     In the application, this resource would be registered with code like this:
 
-    \snippet doc/src/snippets/code/doc_src_resources.cpp 4
+    \snippet code/doc_src_resources.cpp 4
 
     \section2 Compiled-In Resources
 
@@ -138,7 +126,7 @@
     mentioned in the application's \c .pro file so that \c qmake knows
     about it. For example:
 
-    \snippet examples/mainwindows/application/application.pro 0
+    \snippet mainwindows/application/application.pro 0
 
     \c qmake will produce make rules to generate a file called \c
     qrc_application.cpp that is linked into the application. This
@@ -183,7 +171,7 @@
     pass a resource path instead of a file name to the QIcon, QImage,
     or QPixmap constructor:
 
-    \snippet examples/mainwindows/application/mainwindow.cpp 21
+    \snippet mainwindows/application/mainwindow.cpp 21
 
     See the \l{mainwindows/application}{Application} example for an
     actual application that uses Qt's resource system to store its
@@ -205,7 +193,7 @@
     Q_INIT_RESOURCE() with the base name of the \c .qrc file. For
     example:
 
-    \snippet doc/src/snippets/code/doc_src_resources.cpp 5
+    \snippet code/doc_src_resources.cpp 5
 
     Similarly, if you must unload a set of resources explicitly
     (because a plugin is being unloaded or the resources are not valid

src/corelib/global/qlogging.cpp

@@ -737,7 +737,7 @@ void qWinMessageHandler2(QtMsgType t, const QMessageLogContext &context,
     This is a typedef for a pointer to a function with the following
     signature:
 
-    \snippet doc/src/snippets/code/src_corelib_global_qglobal.cpp 7
+    \snippet code/src_corelib_global_qglobal.cpp 7
 
     This typedef is deprecated, you should use QtMessageHandler instead.
     \sa QtMsgType, QtMessageHandler, qInstallMsgHandler(), qInstallMessageHandler()
@@ -751,7 +751,7 @@ void qWinMessageHandler2(QtMsgType t, const QMessageLogContext &context,
     This is a typedef for a pointer to a function with the following
     signature:
 
-    \snippet doc/src/snippets/code/src_corelib_global_qglobal.cpp 49
+    \snippet code/src_corelib_global_qglobal.cpp 49
 
     \sa QtMsgType, qInstallMessageHandler()
 */
@@ -785,7 +785,7 @@ void qWinMessageHandler2(QtMsgType t, const QMessageLogContext &context,
 
     Example:
 
-    \snippet doc/src/snippets/code/src_corelib_global_qglobal.cpp 23
+    \snippet code/src_corelib_global_qglobal.cpp 23
 
     \sa QtMessageHandler, QtMsgType, qDebug(), qWarning(), qCritical(), qFatal(),
     {Debugging Techniques}

src/corelib/io/qfiledevice.cpp

@@ -146,12 +146,12 @@ void QFileDevicePrivate::setError(QFileDevice::FileError err, int errNum)
     handling considerably. It is possible to force permission checking
     on NTFS by including the following code in your source:
 
-    \snippet doc/src/snippets/ntfsp.cpp 0
+    \snippet ntfsp.cpp 0
 
     Permission checking is then turned on and off by incrementing and
     decrementing \c qt_ntfs_permission_lookup by 1.
 
-    \snippet doc/src/snippets/ntfsp.cpp 1
+    \snippet ntfsp.cpp 1
 */
 
 //************* QFileDevice

src/corelib/io/qurlquery.cpp

@@ -511,7 +511,7 @@ QString QUrlQuery::query(QUrl::ComponentFormattingOptions encoding) const
     If \a valueDelimiter is set to '(' and \a pairDelimiter is ')',
     the above query string would instead be represented like this:
 
-    \snippet doc/src/snippets/code/src_corelib_io_qurl.cpp 4
+    \snippet code/src_corelib_io_qurl.cpp 4
 
     \note Non-standard delimiters should be chosen from among what RFC 3986 calls
     "sub-delimiters". They are:

src/corelib/tools/qhash.cpp

@@ -838,7 +838,7 @@ void QHashData::checkSanity()
     operator==() and a qHash() implementation.
 
     Example:
-    \snippet doc/src/snippets/code/src_corelib_tools_qhash.cpp 13
+    \snippet code/src_corelib_tools_qhash.cpp 13
 
     In the example above, we've relied on Qt's global qHash(const
     QString &, uint) to give us a hash value for the employee's name, and

src/corelib/tools/qstringlist.cpp

@@ -404,8 +404,8 @@ void QtPrivate::QStringList_replaceInStrings(QStringList *that, const QRegExp &r
 
     For example:
 
-    \snippet doc/src/snippets/qstringlist/main.cpp 5
+    \snippet qstringlist/main.cpp 5
-    \snippet doc/src/snippets/qstringlist/main.cpp 16
+    \snippet qstringlist/main.cpp 16
 
     For regular expressions that contain capturing groups,
     occurrences of \b{\\1}, \b{\\2}, ..., in \a after are
@@ -413,8 +413,8 @@ void QtPrivate::QStringList_replaceInStrings(QStringList *that, const QRegExp &r
 
     For example:
 
-    \snippet doc/src/snippets/qstringlist/main.cpp 5
+    \snippet qstringlist/main.cpp 5
-    \snippet doc/src/snippets/qstringlist/main.cpp 17
+    \snippet qstringlist/main.cpp 17
 */
 void QtPrivate::QStringList_replaceInStrings(QStringList *that, const QRegularExpression &re, const QString &after)
 {

src/dbus/dbus.pro

@@ -35,6 +35,9 @@ load(qt_module_config)
 
 HEADERS += $$QT_SOURCE_TREE/src/dbus/qtdbusversion.h
 
+QMAKE_DOCS = $$PWD/doc/qtdbus.qdocconf
+QMAKE_DOCS_INDEX = ../../doc
+
 PUB_HEADERS = qdbusargument.h \
     qdbusconnectioninterface.h \
     qdbusmacros.h \

src/dbus/doc/qtdbus.qdocconf

@@ -0,0 +1,92 @@
+include(../../../doc/global/qt-cpp-ignore.qdocconf)
+
+project                 = QtDBus
+description             = Qt DBus Reference Documentation
+url                     = http://qt-project.org/doc/qt-5.0/qtdbus
+version                 = 5.0.0
+
+sourceencoding          = UTF-8
+outputencoding          = UTF-8
+naturallanguage         = en_US
+qhp.projects            = QtDBus
+
+qhp.QtDBus.file         = qtdbus.qhp
+qhp.QtDBus.namespace           = org.qt-project.qtdbus.500
+qhp.QtDBus.virtualFolder       = qdoc
+qhp.QtDBus.indexTitle          = Qt DBus Reference Documentation
+qhp.QtDBus.indexRoot           =
+
+qhp.QtDBus.filterAttributes    = qtdbus 5.0.0 qtrefdoc
+qhp.QtDBus.customFilters.Qt.name = QtDBus 5.0.0
+qhp.QtDBus.customFilters.Qt.filterAttributes = qtdbus 5.0.0
+qhp.QtDBus.subprojects         = classes overviews examples
+qhp.QtDBus.subprojects.classes.title = Classes
+qhp.QtDBus.subprojects.classes.indexTitle = Qt DBus' Classes
+qhp.QtDBus.subprojects.classes.selectors = class fake:headerfile
+qhp.QtDBus.subprojects.classes.sortPages = true
+qhp.QtDBus.subprojects.overviews.title = Overviews
+qhp.QtDBus.subprojects.overviews.indexTitle = All Overviews and HOWTOs
+qhp.QtDBus.subprojects.overviews.selectors = fake:page,group,module
+qhp.QtDBus.subprojects.examples.title = Qt DBus Examples
+qhp.QtDBus.subprojects.examples.indexTitle = Qt DBus Examples
+qhp.QtDBus.subprojects.examples.selectors = fake:example
+
+dita.metadata.default.author      = Qt Project
+dita.metadata.default.permissions = all
+dita.metadata.default.publisher   = Qt Project
+dita.metadata.default.copyryear = 2012
+dita.metadata.default.copyrholder = Nokia
+dita.metadata.default.audience = programmer
+
+sources.fileextensions  = "*.c++ *.cc *.cpp *.cxx *.mm *.qml *.qdoc"
+headers.fileextensions  = "*.ch *.h *.h++ *.hh *.hpp *.hxx"
+
+examples.fileextensions = "*.cpp *.h *.js *.xq *.svg *.xml *.ui *.qhp *.qhcp *.qml *.css"
+examples.imageextensions = "*.png"
+
+outputdir               = ../../../doc/qtdbus
+tagfile                 = ../../../doc/qtdbus/qtdbus.tags
+
+HTML.generatemacrefs    = "true"
+HTML.nobreadcrumbs      = "true"
+
+HTML.templatedir = .
+
+HTML.stylesheets = ../../../doc/global/style/offline.css
+
+HTML.headerstyles = \
+    "  <link rel=\"stylesheet\" type=\"text/css\" href=\"style/offline.css\" />\n"
+
+HTML.endheader = \
+    "</head>\n" \
+
+defines                 = Q_QDOC \
+                          QT_.*_SUPPORT \
+                          QT_.*_LIB \
+                          QT_COMPAT \
+                          QT_KEYPAD_NAVIGATION \
+                          QT_NO_EGL \
+                          Q_WS_.* \
+                          Q_OS_.* \
+                          Q_BYTE_ORDER \
+                          QT_DEPRECATED \
+                          QT_DEPRECATED_* \
+                          Q_NO_USING_KEYWORD \
+                          __cplusplus \
+                          Q_COMPILER_INITIALIZER_LISTS
+
+versionsym              = QT_VERSION_STR
+
+codeindent              = 1
+
+depends                 += qtcore
+
+headerdirs  += ..
+
+sourcedirs  += ..
+
+exampledirs += ../../../examples \
+               ../ \
+               snippets
+
+imagedirs   += images

src/dbus/doc/snippets/code/doc_src_introtodbus.qdoc

@@ -0,0 +1,48 @@
+/****************************************************************************
+**
+** Copyright (C) 2012 Nokia Corporation and/or its subsidiary(-ies).
+** Contact: http://www.qt-project.org/
+**
+** This file is part of the documentation of the Qt Toolkit.
+**
+** $QT_BEGIN_LICENSE:BSD$
+** You may use this file under the terms of the BSD license as follows:
+**
+** "Redistribution and use in source and binary forms, with or without
+** modification, are permitted provided that the following conditions are
+** met:
+**   * Redistributions of source code must retain the above copyright
+**     notice, this list of conditions and the following disclaimer.
+**   * Redistributions in binary form must reproduce the above copyright
+**     notice, this list of conditions and the following disclaimer in
+**     the documentation and/or other materials provided with the
+**     distribution.
+**   * Neither the name of Nokia Corporation and its Subsidiary(-ies) nor
+**     the names of its contributors may be used to endorse or promote
+**     products derived from this software without specific prior written
+**     permission.
+**
+** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
+** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
+** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
+** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
+** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
+** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
+** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
+** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
+** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
+** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE."
+**
+** $QT_END_LICENSE$
+**
+****************************************************************************/
+
+//! [0]
+org.freedesktop.DBus
+//! [0]
+
+//! [QDBUS_DEBUG]
+examples/dbus/remotecontrolledcar/controller/controller &
+QDBUS_DEBUG=1 examples/dbus/remotecontrolledcar/car/car &
+//! [QDBUS_DEBUG]

src/dbus/doc/snippets/code/doc_src_qdbusadaptors.cpp

@@ -0,0 +1,293 @@
+/****************************************************************************
+**
+** Copyright (C) 2012 Nokia Corporation and/or its subsidiary(-ies).
+** Contact: http://www.qt-project.org/
+**
+** This file is part of the documentation of the Qt Toolkit.
+**
+** $QT_BEGIN_LICENSE:BSD$
+** You may use this file under the terms of the BSD license as follows:
+**
+** "Redistribution and use in source and binary forms, with or without
+** modification, are permitted provided that the following conditions are
+** met:
+**   * Redistributions of source code must retain the above copyright
+**     notice, this list of conditions and the following disclaimer.
+**   * Redistributions in binary form must reproduce the above copyright
+**     notice, this list of conditions and the following disclaimer in
+**     the documentation and/or other materials provided with the
+**     distribution.
+**   * Neither the name of Nokia Corporation and its Subsidiary(-ies) nor
+**     the names of its contributors may be used to endorse or promote
+**     products derived from this software without specific prior written
+**     permission.
+**
+** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
+** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
+** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
+** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
+** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
+** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
+** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
+** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
+** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
+** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE."
+**
+** $QT_END_LICENSE$
+**
+****************************************************************************/
+
+//! [0]
+class MainApplicationAdaptor: public QDBusAbstractAdaptor
+{
+    Q_OBJECT
+    Q_CLASSINFO("D-Bus Interface", "org.kde.DBus.MainApplication")
+    Q_PROPERTY(QString caption READ caption WRITE setCaption)
+    Q_PROPERTY(QString organizationName READ organizationName)
+    Q_PROPERTY(QString organizationDomain READ organizationDomain)
+
+private:
+    QApplication *app;
+
+public:
+    MainApplicationAdaptor(QApplication *application)
+        : QDBusAbstractAdaptor(application), app(application)
+    {
+        connect(application, SIGNAL(aboutToQuit()), SIGNAL(aboutToQuit()));
+        connect(application, SIGNAL(focusChanged(QWidget*, QWidget*)),
+                SLOT(focusChangedSlot(QWidget*, QWidget*)));
+    }
+
+    QString caption()
+    {
+        if (app->hasMainWindow())
+            return app->mainWindow()->caption();
+        return QString(""); // must not return a null QString
+    }
+
+    void setCaption(const QString &newCaption)
+    {
+        if (app->hasMainWindow())
+            app->mainWindow()->setCaption(newCaption);
+    }
+
+    QString organizationName()
+    {
+        return app->organizationName();
+    }
+
+    QString organizationDomain()
+    {
+        return app->organizationDomain();
+    }
+
+public slots:
+    Q_NOREPLY void quit()
+    { app->quit(); }
+
+    void reparseConfiguration()
+    { app->reparseConfiguration(); }
+
+    QString mainWindowObject()
+    {
+        if (app->hasMainWindow())
+            return QString("/%1/mainwindow").arg(app->applicationName());
+        return QString();
+    }
+
+    void setSessionManagement(bool enable)
+    {
+        if (enable)
+           app->enableSessionManagement();
+        else
+           app->disableSessionManagement();
+    }
+
+private slots:
+    void focusChangedSlot(QWidget *, QWidget *now)
+    {
+        if (now == app->mainWindow())
+            emit mainWindowHasFocus();
+    }
+
+signals:
+    void aboutToQuit();
+    void mainWindowHasFocus();
+};
+//! [0]
+
+
+//! [1]
+interface org.kde.DBus.MainApplication
+{
+    property readwrite STRING caption
+    property read STRING organizationName
+    property read STRING organizationDomain
+
+    method quit() annotation("org.freedesktop.DBus.Method.NoReply", "true")
+    method reparseConfiguration()
+    method mainWindowObject(out STRING)
+    method disableSessionManagement(in BOOLEAN enable)
+
+    signal aboutToQuit()
+    signal mainWindowHasFocus()
+}
+//! [1]
+
+
+//! [2]
+int main(int argc, char **argv)
+{
+    // create the QApplication object
+    QApplication app(argc, argv);
+
+    // create the MainApplication adaptor:
+    new MainApplicationAdaptor(app);
+
+    // connect to D-Bus and register as an object:
+    QDBusConnection::sessionBus().registerObject("/MainApplication", app);
+
+    // add main window, etc.
+    [...]
+
+    app.exec();
+}
+//! [2]
+
+
+//! [3]
+class MainApplicationAdaptor: public QDBusAbstractAdaptor
+{
+    Q_OBJECT
+    Q_CLASSINFO("D-Bus Interface", "org.kde.DBus.MainApplication")
+//! [3]
+
+
+//! [4]
+    Q_PROPERTY(QString caption READ caption WRITE setCaption)
+    Q_PROPERTY(QString organizationName READ organizationName)
+    Q_PROPERTY(QString organizationDomain READ organizationDomain)
+//! [4]
+
+
+//! [5]
+QString caption()
+{
+    if (app->hasMainWindow())
+        return app->mainWindow()->caption();
+    return QString();
+}
+
+void setCaption(const QString &newCaption)
+{
+    if (app->hasMainWindow())
+        app->mainWindow()->setCaption(newCaption);
+}
+
+QString organizationName()
+{
+    return app->organizationName();
+}
+
+QString organizationDomain()
+{
+    return app->organizationDomain();
+}
+//! [5]
+
+
+//! [6]
+MyInterfaceAdaptor(QApplication *application)
+    : QDBusAbstractAdaptor(application), app(application)
+{
+    connect(application, SIGNAL(aboutToQuit()), SIGNAL(aboutToQuit());
+    connect(application, SIGNAL(focusChanged(QWidget*, QWidget*)),
+            SLOT(focusChangedSlot(QWidget*, QWidget*)));
+}
+//! [6]
+
+
+//! [7]
+public slots:
+    Q_NOREPLY void quit()
+    { app->quit(); }
+
+    void reparseConfiguration()
+    { app->reparseConfiguration(); }
+
+    QString mainWindowObject()
+    {
+        if (app->hasMainWindow())
+            return QString("/%1/mainwindow").arg(app->applicationName());
+        return QString();
+    }
+
+    void setSessionManagement(bool enable)
+    {
+        if (enable)
+           app->enableSessionManagement();
+        else
+           app->disableSessionManagement();
+    }
+//! [7]
+
+
+//! [8]
+signals:
+    void aboutToQuit();
+    void mainWindowHasFocus();
+//! [8]
+
+
+//! [9]
+private slots:
+    void focusChangedSlot(QWidget *, QWidget *now)
+    {
+        if (now == app->mainWindow())
+            emit mainWindowHasFocus();
+    }
+//! [9]
+
+
+//! [10]
+struct RequestData
+{
+    QString request;
+    QString processedData;
+    QDBusMessage reply;
+};
+
+QString processRequest(const QString &request, const QDBusMessage &message)
+{
+    RequestData *data = new RequestData;
+    data->request = request;
+    message.setDelayedReply(true);
+    data->reply = message.createReply();
+    QDBusConnection::sessionBus().send(data->reply);
+
+    appendRequest(data);
+    return QString();
+}
+//! [10]
+
+
+//! [11]
+void sendReply(RequestData *data)
+{
+    // data->processedData has been initialized with the request's reply
+    QDBusMessage &reply = &data->reply;
+
+    // send the reply over D-Bus:
+    reply << data->processedData;
+    QDBusConnection::sessionBus().send(reply);
+
+    // dispose of the transaction data
+    delete data;
+}
+//! [11]
+
+
+//! [12]
+Q_NOREPLY void myMethod();
+//! [12]

src/dbus/doc/snippets/code/doc_src_qtdbus.cpp

@@ -39,6 +39,5 @@
 ****************************************************************************/
 
 //! [0]
-s*Xs = a*Xd + b*Yd + c
+#include <QtDBus>
-s*Ys = d*Xd + e*Yd + f
 //! [0]

src/dbus/doc/snippets/code/doc_src_qtdbus.pro

@@ -0,0 +1,3 @@
+#! [1]
+QT += dbus
+#! [1]

src/dbus/doc/src/dbus-adaptors.qdoc

@@ -0,0 +1,481 @@
+/****************************************************************************
+**
+** Copyright (C) 2012 Nokia Corporation and/or its subsidiary(-ies).
+** Contact: http://www.qt-project.org/
+**
+** This file is part of the documentation of the Qt Toolkit.
+**
+** $QT_BEGIN_LICENSE:FDL$
+** GNU Free Documentation License
+** 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.
+**
+** Other Usage
+** Alternatively, this file may be used in accordance with the terms
+** and conditions contained in a signed written agreement between you
+** and Nokia.
+**
+**
+**
+**
+**
+** $QT_END_LICENSE$
+**
+****************************************************************************/
+
+/*!
+    \page usingadaptors.html
+    \title Using QtDBus Adaptors
+    \brief How to create and use DBus adaptors in Qt.
+
+    \ingroup best-practices
+
+    Adaptors are special classes that are attached to any QObject-derived class
+    and provide the interface to the external world using D-Bus. Adaptors are
+    intended to be lightweight classes whose main purpose is to relay calls to
+    and from the real object, possibly validating or converting the input from
+    the external world and, thus, protecting the real object.
+
+    Unlike multiple inheritance, adaptors can be added at any time to any object
+    (but not removed), which allows for greater flexibility when exporting
+    existing classes. Another advantage of adaptors is to provide similar but not
+    identical functionality in methods of the same name in different interfaces,
+    a case which can be quite common when adding a new version of a standard
+    interface to an object.
+
+    In order to use an adaptor, one must create a class which inherits
+    QDBusAbstractAdaptor. Since that is a standard QObject-derived class, the
+    Q_OBJECT macro must appear in the declaration and the source file must be
+    processed with the \l {moc} tool. The class must also contain one
+    Q_CLASSINFO entry with the \c {"D-Bus Interface"} name, declaring which
+    interface it is exporting. Only one entry per class is supported.
+
+    Any public slot in the class will be accessible through the bus over messages
+    of the MethodCall type. (See \l {Declaring Slots in D-Bus Adaptors} for more
+    information). Signals in the class will be automatically relayed over D-Bus.
+    However, not all types are allowed signals or slots' parameter lists: see
+    \l {The QtDBus Type System} for more information.
+
+    Also, any property declared with Q_PROPERTY will be automatically exposed
+    over the Properties interface on D-Bus. Since the QObject property system
+    does not allow for non-readable properties, it is not possible to declare
+    write-only properties using adaptors.
+
+    More information:
+    \list
+      \li \l{Declaring Slots in D-Bus Adaptors}
+      \li \l{Declaring Signals in D-Bus Adaptors}
+      \li \l{The QtDBus Type System}
+      \li \l{D-Bus Adaptor Example}
+    \endlist
+
+    \sa QDBusAbstractAdaptor
+*/
+
+/*!
+    \page qdbusadaptorexample.html
+    \title D-Bus Adaptor Example
+
+    \previouspage The QtDBus Type System
+    \contentspage Using QtDBus Adaptors
+
+    The following example code shows how a D-Bus interface can be implemented
+    using an adaptor.
+
+    A sample usage of QDBusAbstractAdaptor is as follows:
+    \snippet code/doc_src_qdbusadaptors.cpp 0
+
+    The code above would create an interface that could be represented more or less in the following
+    canonical representation:
+    \snippet code/doc_src_qdbusadaptors.cpp 1
+
+    This adaptor could be used in the application's main function as follows
+    \snippet code/doc_src_qdbusadaptors.cpp 2
+
+    Break-down analysis:
+    \tableofcontents
+
+    \section1 The header
+
+    The header of the example is:
+    \snippet code/doc_src_qdbusadaptors.cpp 3
+
+    The code does the following:
+    \list
+      \li it declares the adaptor MainApplicationAdaptor, which descends from QDBusAbstractAdaptor
+      \li it declares the Qt meta-object data using the Q_OBJECT macro
+      \li it declares the name of the D-Bus interface it implements.
+    \endlist
+
+    \section1 The properties
+
+    The properties are declared as follows:
+    \snippet code/doc_src_qdbusadaptors.cpp 4
+
+    And are implemented as follows:
+    \snippet code/doc_src_qdbusadaptors.cpp 5
+
+    The code declares three properties: one of them is a read-write property called "caption" of
+    string type. The other two are read-only, also of the string type.
+
+    The properties organizationName and organizationDomain are simple relays of the app object's
+    organizationName and organizationDomain properties. However, the caption property requires
+    verifying if the application has a main window associated with it: if there isn't any, the
+    caption property is empty. Note how it is possible to access data defined in other objects
+    through the getter/setter functions.
+
+    \section1 The constructor
+
+    The constructor:
+    \snippet code/doc_src_qdbusadaptors.cpp 6
+
+    The constructor does the following:
+    \list
+    \li it initialises its base class (QDBusAbstractAdaptor) with the parent object it is related to.
+    \li it stores the app pointer in a member variable. Note that it would be possible to access the
+       same object using the QDBusAbstractAdaptor::object() function, but it would be necessary to
+       use \a static_cast<> to properly access the methods in QApplication that are not part of
+       QObject.
+    \li it connects the application's signal \a aboutToQuit to its own signal \a aboutToQuit.
+    \li it connects the application's signal \a focusChanged to a private slot to do some further
+       processing before emitting a D-Bus signal.
+    \endlist
+
+    Note that there is no destructor in the example. An eventual destructor could be used to emit
+    one last signal before the object is destroyed, for instance.
+
+    \section1 Slots/methods
+
+    The public slots in the example (which will be exported as D-Bus methods) are the following:
+    \snippet code/doc_src_qdbusadaptors.cpp 7
+
+    This snippet of code defines 4 methods with different properties each:
+    \list 1
+    \li \c quit: this method takes no parameters and is defined to be asynchronous. That is, callers
+      are expected to use "fire-and-forget" mechanism when calling this method, since it provides no
+      useful reply. This is represented in D-Bus by the use of the
+      org.freedesktop.DBus.Method.NoReply annotation. See \l Q_NOREPLY for more information on
+      asynchronous methods
+
+    \li \c reparseConfiguration: this simple method, with no input or output arguments simply relays
+      the call to the application's reparseConfiguration member function.
+
+    \li \c mainWindowObject: this method takes no input parameter, but returns one string output
+      argument, containing the path to the main window object (if the application has a main
+      window), or an empty string if it has no main window. Note that this method could have also
+      been written: void mainWindowObject(QString &path).
+
+    \li \c setSessionManagement: this method takes one input argument (a boolean) and, depending on
+      its value, it calls one function or another in the application.
+    \endlist
+
+    See also: \l Q_NOREPLY.
+
+    \section1 Signals
+
+    The signals in this example are defined as follows:
+    \snippet code/doc_src_qdbusadaptors.cpp 8
+
+    However, signal definition isn't enough: signals have to be emitted. One simple way of emitting
+    signals is to connect another signal to them, so that Qt's signal handling system chains them
+    automatically. This is what is done for the \a aboutToQuit signal.
+
+    When this is the case, one can use the QDBusAbstractAdaptor::setAutoRelaySignals to
+    automatically connect every signal from the real object to the adaptor.
+
+    When simple signal-to-signal connection isn't enough, one can use a private slot do do some
+    work. This is what was done for the mainWindowHasFocus signal:
+    \snippet code/doc_src_qdbusadaptors.cpp 9
+
+    This private slot (which will not be exported as a method via D-Bus) was connected to the
+    \c focusChanged signal in the adaptor's constructor. It is therefore able to shape the
+    application's signal into what the interface expects it to be.
+*/
+
+/*!
+    \page qdbusdeclaringslots.html
+    \title Declaring Slots in D-Bus Adaptors
+
+    \contentspage Using QtDBus Adaptors
+    \nextpage Declaring Signals in D-Bus Adaptors
+
+    Slots in D-Bus adaptors are declared just like normal, public slots, but their
+    parameters must follow certain rules (see \l{The QtDBus Type System} for more
+    information). Slots whose parameters do not follow those rules or that are not
+    public will not be accessible via D-Bus.
+
+    Slots can have one parameter of type \c{const QDBusMessage &}, which must
+    appear at the end of the input parameter list, before any output parameters.
+    This parameter, if present, will be initialized with a copy of the
+    current message being processed, which allows the callee to obtain
+    information about the caller, such as its connection name.
+
+    Slots can be of three kinds:
+    \list 1
+      \li Asynchronous
+      \li Input-only
+      \li Input-and-output
+    \endlist
+
+    \section1 Asynchronous Slots
+    Asynchronous slots are those that do not normally return any reply to the
+    caller. For that reason, they cannot take any output parameters. In most
+    cases, by the time the first line of the slot is run, the caller function
+    has already resumed working.
+
+    However, slots must not rely on that behavior. Scheduling and message-dispatching
+    issues could change the order in which the slot is run. Code intending to
+    synchronize with the caller should provide its own method of synchronization.
+
+    Asynchronous slots are marked by the keyword \l Q_NOREPLY in the method
+    signature, before the \c void return type and the slot name. (See the
+    \c quit() slot in the \l{D-Bus Adaptor Example}).
+
+    \section1 Input-Only Slots
+
+    Input-only slots are normal slots that take parameters passed by value or
+    by constant reference. However, unlike asynchronous slots, the caller is
+    usually waiting for completion of the callee before resuming operation.
+    Therefore, non-asynchronous slots should not block or should state it its
+    documentation that they may do so.
+
+    Input-only slots have no special marking in their signature, except that
+    they take only parameters passed by value or by constant reference.
+    Optionally, slots can take a QDBusMessage parameter as a last parameter,
+    which can be used to perform additional analysis of the method call message.
+
+    \section1 Input and Output Slots
+
+    Like input-only slots, input-and-output slots are those that the caller is
+    waiting for a reply. Unlike input-only ones, though, this reply will contain
+    data. Slots that output data may contain non-constant references and may
+    return a value as well. However, the output parameters must all appear at
+    the end of the argument list and may not have input arguments interleaved.
+    Optionally, a QDBusMessage argument may appear between the input and the
+    output arguments.
+
+    \section1 Automatic Replies
+
+    Method replies are generated automatically with the contents of the output
+    parameters (if there were any) by the QtDBus implementation. Slots need not
+    worry about constructing proper QDBusMessage objects and sending them over
+    the connection.
+
+    However, the possibility of doing so remains there. Should the slot find out
+    it needs to send a special reply or even an error, it can do so by using
+    QDBusMessage::createReply() or QDBusMessage::createErrorReply() on the
+    QDBusMessage parameter and send it with QDBusConnection::send(). The
+    QtDBus implementation will not generate any reply if the slot did so.
+
+    \warning When a caller places a method call and waits for a reply, it will
+    only wait for a limited amount of time. Slots intending to take a long time
+    to complete should make that fact clear in documentation so that callers
+    properly set higher timeouts.
+
+    \section1 Delayed Replies
+
+    In some circumstances, the called slot may not be able to process
+    the request immediately. This is frequently the case when the
+    request involves an I/O or networking operation which may block.
+
+    If this is the case, the slot should return control to the
+    application's main loop to avoid freezing the user interface, and
+    resume the process later. To accomplish this, it should make use
+    of the extra \c QDBusMessage parameter at the end of the input
+    parameter list and request a delayed reply.
+
+    We do this by writing a slot that stores the request data in a
+    persistent structure, indicating to the caller using
+    \l{QDBusMessage::setDelayedReply()}{QDBusMessage::setDelayedReply(true)}
+    that the response will be sent later.
+
+    \snippet code/doc_src_qdbusadaptors.cpp 10
+
+    The use of
+    \l{QDBusConnection::send()}{QDBusConnection::sessionBus().send(data->reply)}
+    is needed to explicitly inform the caller that the response will be delayed.
+    In this case, the return value is unimportant; we return an arbitrary value
+    to satisfy the compiler.
+
+    When the request is processed and a reply is available, it should be sent
+    using the \c QDBusMessage object that was obtained. In our example, the
+    reply code could be something as follows:
+
+    \snippet code/doc_src_qdbusadaptors.cpp 11
+
+    As can be seen in the example, when a delayed reply is in place,
+    the return value(s) from the slot will be ignored by QtDBus. They
+    are used only to determine the slot's signature when communicating
+    the adaptor's description to remote applications, or in case the
+    code in the slot decides not to use a delayed reply.
+
+    The delayed reply itself is requested from QtDBus by calling
+    QDBusMessage::reply() on the original message. It then becomes the
+    resposibility of the called code to eventually send a reply to the
+    caller.
+
+    \warning When a caller places a method call and waits for a reply, it will
+    only wait for a limited amount of time. Slots intending to take a long time
+    to complete should make that fact clear in documentation so that callers
+    properly set higher timeouts.
+
+    \sa {Using QtDBus Adaptors}, {Declaring Signals in D-Bus Adaptors},
+        {The QtDBus Type System}, QDBusConnection, QDBusMessage
+*/
+
+/*!
+    \page qdbusdeclaringsignals.html
+    \title Declaring Signals in D-Bus Adaptors
+
+    \previouspage Declaring Slots in D-Bus Adaptors
+    \contentspage Using QtDBus Adaptors
+    \nextpage The QtDBus Type System
+
+    Any signal in a class derived from QDBusAbstractAdaptor will be automatically
+    relayed into D-Bus, provided that the signal's parameters conform to certain
+    rules (see \l{The QtDBus Type System} for more information). No special code
+    is necessary to make this relay.
+
+    However, signals must still be emitted. The easiest way to emit an adaptor
+    signal is to connect another signal to it, so that Qt's signals and slots
+    mechanism automatically emits the adaptor signal, too. This can be done in
+    the adaptor's constructor, as has been done in the
+    \l{D-Bus Adaptor Example}{D-Bus Adaptor example}.
+
+    The QDBusAbstractAdaptor::setAutoRelaySignals() convenience function can also
+    be used to make and break connections between signals in the real object and
+    the corresponding signals in the adaptor. It will inspect the list of signals
+    in both classes and connect those whose parameters match exactly.
+
+    \sa {Using QtDBus Adaptors},
+        {Declaring Slots in D-Bus Adaptors},
+        {The QtDBus Type System}, QDBusAbstractAdaptor
+*/
+
+/*!
+    \page qdbustypesystem.html
+    \title The QtDBus Type System
+
+    \previouspage Declaring Signals in D-Bus Adaptors
+    \contentspage Using QtDBus Adaptors
+    \nextpage D-Bus Adaptor Example
+
+    D-Bus has an extensible type system based on a few primitives and
+    composition of the primitives in arrays and structures. QtDBus
+    implements the interface to that type system through the
+    QDBusArgument class, allowing user programs to send and receive
+    practically every C++ type over the bus.
+
+    \section1 Primitive Types
+
+    The primitive types are supported natively by QDBusArgument and
+    need no special customization to be sent or received. They are
+    listed below, along with the C++ class they relate to:
+
+    \table
+      \header
+        \li Qt type
+        \li D-Bus equivalent type
+      \row
+        \li uchar
+        \li BYTE
+      \row
+        \li bool
+        \li BOOLEAN
+      \row
+        \li short
+        \li INT16
+      \row
+        \li ushort
+        \li UINT16
+      \row
+        \li int
+        \li INT32
+      \row
+        \li uint
+        \li UINT32
+      \row
+        \li qlonglong
+        \li INT64
+      \row
+        \li qulonglong
+        \li UINT64
+      \row
+        \li double
+        \li DOUBLE
+      \row
+        \li QString
+        \li STRING
+      \row
+        \li QDBusVariant
+        \li VARIANT
+      \row
+        \li QDBusObjectPath
+        \li OBJECT_PATH
+      \row
+        \li QDBusSignature
+        \li SIGNATURE
+    \endtable
+
+    Aside from the primitive types, QDBusArgument also supports two
+    non-primitive types natively, due to their widespread use in Qt
+    applications: QStringList and QByteArray.
+
+    \section1 Compound Types
+
+    D-Bus specifies three types of aggregations of primitive types
+    that allow one to create compound types. They are \c ARRAY, \c
+    STRUCT and maps/dictionaries.
+
+    Arrays are sets of zero or more elements of the same type, while
+    structures are a set of a fixed number of elements, each of any
+    type. Maps or dictionaries are implemented as arrays of a pair of
+    elements, so there can be zero or more elements in one map.
+
+    \section1 Extending the Type System
+
+    In order to use one's own type with QtDBus, the type has to be
+    declared as a Qt meta-type with the Q_DECLARE_METATYPE() macro and
+    registered with the qDBusRegisterMetaType() function. The
+    streaming operators \c{operator>>} and \c{operator<<} will be
+    automatically found by the registration system.
+
+    QtDBus provides template specializations for arrays and maps for
+    use with Qt's \l{Container classes}{container classes}, such as
+    QMap and QList, so it is not necessary to write the streaming
+    operator functions for those. For other types, and specially for
+    types implementing structures, the operators have to be explicitly
+    implemented.
+
+    See the documentation for QDBusArgument for examples for
+    structures, arrays and maps.
+
+    \section1 The Type System in Use
+
+    All of the QtDBus types (primitives and user-defined alike) can be
+    used to send and receive messages of all types over the bus.
+
+    \warning You may not use any type that is not on the list above,
+    including \a typedefs to the types listed. This also includes
+    QList<QVariant> and QMap<QString,QVariant>.
+*/
+
+/*!
+    \macro Q_NOREPLY
+    \relates QDBusAbstractAdaptor
+    \since 4.2
+
+    The Q_NOREPLY macro can be used to mark a method to be called and not wait for it to finish
+    processing before returning from QDBusInterface::call(). The called method cannot return any
+    output arguments and, if it does, any such arguments will be discarded.
+
+    You can use this macro in your own adaptors by placing it before your method's return value
+    (which must be "void") in the class declaration, as shown in the example:
+    \snippet code/doc_src_qdbusadaptors.cpp 12
+
+    Its presence in the method implementation (outside the class declaration) is optional.
+
+    \sa {Using QtDBus Adaptors}
+*/

src/dbus/doc/src/dbus-intro.qdoc

@@ -0,0 +1,215 @@
+/****************************************************************************
+**
+** Copyright (C) 2012 Nokia Corporation and/or its subsidiary(-ies).
+** Contact: http://www.qt-project.org/
+**
+** This file is part of the documentation of the Qt Toolkit.
+**
+** $QT_BEGIN_LICENSE:FDL$
+** GNU Free Documentation License
+** 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.
+**
+** Other Usage
+** Alternatively, this file may be used in accordance with the terms
+** and conditions contained in a signed written agreement between you
+** and Nokia.
+**
+**
+**
+**
+**
+** $QT_END_LICENSE$
+**
+****************************************************************************/
+
+/*!
+    \page intro-to-dbus.html
+    \title D-Bus
+    \brief An introduction to Inter-Process Communication and Remote Procedure Calling with D-Bus.
+
+    \keyword QtDBus
+    \ingroup technology-apis
+
+    \section1 Introduction
+
+    D-Bus is an Inter-Process Communication (IPC) and Remote Procedure
+    Calling (RPC) mechanism originally developed for Linux to replace
+    existing and competing IPC solutions with one unified protocol. It
+    has also been designed to allow communication between system-level
+    processes (such as printer and hardware driver services) and
+    normal user processes.
+
+    It uses a fast, binary message-passing protocol, which is suitable
+    for same-machine communication due to its low latency and low
+    overhead. Its specification is currently defined by the
+    \tt{freedesktop.org} project, and is available to all parties.
+
+    Communication in general happens through a central server
+    application, called the "bus" (hence the name), but direct
+    application-to-application communication is also possible. When
+    communicating on a bus, applications can query which other
+    applications and services are available, as well as activate one
+    on demand.
+
+    \section1 The Buses
+
+    D-Bus buses are used to when many-to-many communication is
+    desired. In order to achieve that, a central server is launched
+    before any applications can connect to the bus: this server is
+    responsible for keeping track of the applications that are
+    connected and for properly routing messages from their source to
+    their destination.
+
+    In addition, D-Bus defines two well-known buses, called the
+    system bus and the session bus. These buses are special in the
+    sense that they have well-defined semantics: some services are
+    defined to be found in one or both of these buses.
+
+    For example, an application wishing to query the list of hardware
+    devices attached to the computer will probably communicate to a
+    service available on the system bus, while the service providing
+    opening of the user's web browser will be probably found on the
+    session bus.
+
+    On the system bus, one can also expect to find restrictions on
+    what services each application is allowed to offer. Therefore, one
+    can be reasonably certain that, if a certain service is present,
+    it is being offered by a trusted application.
+
+    \section1 Concepts
+
+    \section2 Messages
+
+    On the low level, applications communicate over D-Bus by sending
+    messages to one another. Messages are used to relay the remote
+    procedure calls as well as the replies and errors associated
+    with them. When used over a bus, messages have a destination,
+    which means they are routed only to the interested parties,
+    avoiding congestion due to "swarming" or broadcasting.
+
+    A special kind of message called a "signal message"
+    (a concept based on Qt's \l {Signals and Slots} mechanism),
+    however, does not have a pre-defined destination. Since its
+    purpose is to be used in a one-to-many context, signal messages
+    are designed to work over an "opt-in" mechanism.
+
+    The QtDBus module fully encapsulates the low-level concept of
+    messages into a simpler, object-oriented approach familiar to Qt
+    developers. In most cases, the developer need not worry about
+    sending or receiving messages.
+
+    \section2 Service Names
+
+    When communicating over a bus, applications obtain what is
+    called a "service name": it is how that application chooses to be
+    known by other applications on the same bus. The service names
+    are brokered by the D-Bus bus daemon and are used to
+    route messages from one application to another. An analogous
+    concept to service names are IP addresses and hostnames: a
+    computer normally has one IP address and may have one or more
+    hostnames associated with it, according to the services that it
+    provides to the network.
+
+    On the other hand, if a bus is not used, service names are also
+    not used. If we compare this to a computer network again, this
+    would equate to a point-to-point network: since the peer is
+    known, there is no need to use hostnames to find it or its IP
+    address.
+
+    The format of a D-Bus service name is in fact very similar to a
+    host name: it is a dot-separated sequence of letters and
+    digits. The common practice is even to name one's service name
+    according to the domain name of the organization that defined
+    that service.
+
+    For example, the D-Bus service is defined by
+    \tt{freedesktop.org} and can be found on the bus under the
+    service name:
+
+    \snippet code/doc_src_introtodbus.qdoc 0
+
+    \section2 Object Paths
+
+    Like network hosts, applications provide specific services to
+    other applications by exporting objects. Those objects are
+    hierarchically organised, much like the parent-child
+    relationship that classes derived from QObject possess. One
+    difference, however, is that there is the concept of "root
+    object", that all objects have as ultimate parent.
+
+    If we continue our analogy with Web services, object paths
+    equate to the path part of a URL:
+
+    \img qurl-ftppath.png
+
+    Like them, object paths in D-Bus are formed resembling path
+    names on the filesystem: they are slash-separated labels, each
+    consisting of letters, digits and the underscore character
+    ("_"). They must always start with a slash and must not end with
+    one.
+
+    \section2 Interfaces
+
+    Interfaces are similar to C++ abstract classes and Java's
+    \c interface keyword and declare the "contract" that is
+    established between caller and callee. That is, they establish
+    the names of the methods, signals and properties that are
+    available as well as the behavior that is expected from either
+    side when communication is established.
+
+    Qt uses a very similar mechanism in its \l {How to Create Qt
+    Plugins}{Plugin system}: Base classes in C++ are associated
+    with a unique identifier by way of the Q_DECLARE_INTERFACE()
+    macro.
+
+    D-Bus interface names are, in fact, named in a manner similar to
+    what is suggested by the Qt Plugin System: an identifier usually
+    constructed from the domain name of the entity that defined that
+    interface.
+
+    \section2 Cheat Sheet
+
+    To facilitate remembering of the naming formats and their
+    purposes, the following table can be used:
+
+    \table 90%
+    \header \li D-Bus Concept  \li Analogy            \li Name format
+    \row    \li Service name   \li Network hostnames  \li Dot-separated
+                                                       ("looks like a hostname")
+    \row    \li Object path    \li URL path component \li Slash-separated
+                                                       ("looks like a path")
+    \row    \li Interface      \li Plugin identifier  \li Dot-separated
+    \endtable
+
+    \section1 Debugging
+
+    When developing applications that use D-Bus, it is sometimes useful to be able
+    to see information about the messages that are sent and received across the
+    bus by each application.
+
+    This feature can be enabled on a per-application basis by setting the
+    \c QDBUS_DEBUG environment variable before running each application.
+    For example, we can enable debugging only for the car in the
+    \l{D-Bus Remote Controlled Car Example} by running the controller and the
+    car in the following way:
+
+    \snippet code/doc_src_introtodbus.qdoc QDBUS_DEBUG
+
+    Information about the messages will be written to the console the application
+    was launched from.
+
+    \section1 Further Reading
+
+    The following documents contain information about Qt's D-Bus integration
+    features, and provide details about the mechanisms used to send and receive
+    type information over the bus:
+
+    \list
+    \li \l{Using QtDBus Adaptors}
+    \li \l{The QtDBus Type System}
+    \li \l{QtDBus XML compiler (qdbusxml2cpp)}
+    \endlist
+*/

src/dbus/doc/src/qdbusxml2cpp.qdoc

@@ -0,0 +1,49 @@
+/****************************************************************************
+**
+** Copyright (C) 2012 Nokia Corporation and/or its subsidiary(-ies).
+** Contact: http://www.qt-project.org/
+**
+** This file is part of the documentation of the Qt Toolkit.
+**
+** $QT_BEGIN_LICENSE:FDL$
+** GNU Free Documentation License
+** 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.
+**
+** Other Usage
+** Alternatively, this file may be used in accordance with the terms
+** and conditions contained in a signed written agreement between you
+** and Nokia.
+**
+**
+**
+**
+**
+** $QT_END_LICENSE$
+**
+****************************************************************************/
+
+/*!
+    \page qdbusxml2cpp.html
+    \title QtDBus XML compiler (qdbusxml2cpp)
+    \keyword qdbusxml2cpp
+
+    The QtDBus XML compiler is a tool that can be used to parse interface descriptions and produce
+    static code representing those interfaces, which can then be used to make calls to remote
+    objects or implement said interfaces.
+
+    \c qdbusxml2cpp has two modes of operation, that correspond to the two possible outputs it can
+    produce: the interface (proxy) class or the adaptor class. The latter consists of both a C++
+    header and a source file, which are meant to be edited and adapted to your needs.
+
+    The \c qdbusxml2cpp tool is not meant to be run every time you compile your
+    application. Instead, it's meant to be used when developing the code or when the interface
+    changes.
+
+    The adaptor classes generated by \c qdbusxml2cpp are just a skeleton that must be completed. It
+    generates, by default, calls to slots with the same name on the object the adaptor is attached
+    to. However, you may modify those slots or the property accessor functions to suit your needs.
+*/
+

src/dbus/doc/src/qtdbus.qdoc

@@ -48,13 +48,13 @@
 
     To use this module, use the following code in your application:
 
-    \snippet doc/src/snippets/code/doc_src_qtdbus.cpp 0
+    \snippet code/doc_src_qtdbus.cpp 0
 
     If you're using qmake to build your application, you can add this
     line to your .pro file to make it link against the QtDBus
     libraries:
 
-    \snippet doc/src/snippets/code/doc_src_qtdbus.pro 1
+    \snippet code/doc_src_qtdbus.pro 1
 
     \note The source code for this module is located in the \c{src/qdbus}
     directory. When installing Qt from source, this module is built when Qt's
@@ -62,6 +62,4 @@
 
     See the \l {D-Bus} page for detailed information on
     how to use this module.
-
-    This module is part of all \l{Qt editions}.
 */

src/dbus/qdbusabstractinterface.cpp

@@ -650,7 +650,7 @@ void QDBusAbstractInterface::internalPropSet(const char *propname, const QVarian
 
     It can be used the following way:
 
-    \snippet doc/src/snippets/code/src_qdbus_qdbusabstractinterface.cpp 0
+    \snippet code/src_qdbus_qdbusabstractinterface.cpp 0
 
     This example illustrates function calling with 0, 1 and 2 parameters and illustrates different
     parameter types passed in each (the first call to \c "ProcessWorkUnicode" will contain one
@@ -742,7 +742,7 @@ QDBusMessage QDBusAbstractInterface::call(QDBus::CallMode mode, const QString &m
 
     It can be used the following way:
 
-    \snippet doc/src/snippets/code/src_qdbus_qdbusabstractinterface.cpp 1
+    \snippet code/src_qdbus_qdbusabstractinterface.cpp 1
 
     This example illustrates function calling with 0, 1 and 2 parameters and illustrates different
     parameter types passed in each (the first call to \c "ProcessWorkUnicode" will contain one

src/dbus/qdbusargument.cpp

@@ -190,13 +190,13 @@ bool QDBusArgumentPrivate::checkReadAndDetach(QDBusArgumentPrivate *&d)
     integer and a string can be constructed using the \l
     {qdbustypesystem.html}{QtDBus type system}:
 
-    \snippet doc/src/snippets/code/src_qdbus_qdbusargument.cpp 0
+    \snippet code/src_qdbus_qdbusargument.cpp 0
 
     The type has to be registered with qDBusRegisterMetaType() before
     it can be used with QDBusArgument. Therefore, somewhere in your
     program, you should add the following code:
 
-    \snippet doc/src/snippets/code/src_qdbus_qdbusargument.cpp 1
+    \snippet code/src_qdbus_qdbusargument.cpp 1
 
     Once registered, a type can be used in outgoing method calls
     (placed with QDBusAbstractInterface::call()), signal emissions
@@ -275,11 +275,11 @@ bool QDBusArgumentPrivate::checkReadAndDetach(QDBusArgumentPrivate *&d)
     Attempts to demarshall the contents of \a argument into the type
     \c{T}. For example:
 
-    \snippet doc/src/snippets/code/src_qdbus_qdbusargument.cpp 2
+    \snippet code/src_qdbus_qdbusargument.cpp 2
 
     Note that it is equivalent to the following:
 
-    \snippet doc/src/snippets/code/src_qdbus_qdbusargument.cpp 3
+    \snippet code/src_qdbus_qdbusargument.cpp 3
 */
 
 /*!
@@ -817,12 +817,12 @@ const QDBusArgument &QDBusArgument::operator>>(QByteArray &arg) const
     This function is used usually in \c{operator<<} streaming
     operators, as in the following example:
 
-    \snippet doc/src/snippets/code/src_qdbus_qdbusargument.cpp 4
+    \snippet code/src_qdbus_qdbusargument.cpp 4
 
     Structures can contain other structures, so the following code is
     also valid:
 
-    \snippet doc/src/snippets/code/src_qdbus_qdbusargument.cpp 5
+    \snippet code/src_qdbus_qdbusargument.cpp 5
 
     \sa endStructure(), beginArray(), beginMap()
 */
@@ -850,7 +850,7 @@ void QDBusArgument::endStructure()
     This function is used usually in \c{operator<<} streaming
     operators, as in the following example:
 
-    \snippet doc/src/snippets/code/src_qdbus_qdbusargument.cpp 6
+    \snippet code/src_qdbus_qdbusargument.cpp 6
 
     If the type you want to marshall is a QList, QVector or any of the
     Qt's \l {Container Classes} that take one template parameter,
@@ -889,7 +889,7 @@ void QDBusArgument::endArray()
     This function is used usually in \c{operator<<} streaming
     operators, as in the following example:
 
-    \snippet doc/src/snippets/code/src_qdbus_qdbusargument.cpp 7
+    \snippet code/src_qdbus_qdbusargument.cpp 7
 
     If the type you want to marshall is a QMap or QHash, you need not
     declare an \c{operator<<} function for it, since QtDBus provides
@@ -948,7 +948,7 @@ void QDBusArgument::endMapEntry()
     This function is used usually in \c{operator>>} streaming
     operators, as in the following example:
 
-    \snippet doc/src/snippets/code/src_qdbus_qdbusargument.cpp 8
+    \snippet code/src_qdbus_qdbusargument.cpp 8
 
     \sa endStructure(), beginArray(), beginMap()
 */
@@ -977,7 +977,7 @@ void QDBusArgument::endStructure() const
     This function is used usually in \c{operator>>} streaming
     operators, as in the following example:
 
-    \snippet doc/src/snippets/code/src_qdbus_qdbusargument.cpp 9
+    \snippet code/src_qdbus_qdbusargument.cpp 9
 
     If the type you want to demarshall is a QList, QVector or any of the
     Qt's \l {Container Classes} that take one template parameter, you
@@ -1013,7 +1013,7 @@ void QDBusArgument::endArray() const
     This function is used usually in \c{operator>>} streaming
     operators, as in the following example:
 
-    \snippet doc/src/snippets/code/src_qdbus_qdbusargument.cpp 10
+    \snippet code/src_qdbus_qdbusargument.cpp 10
 
     If the type you want to demarshall is a QMap or QHash, you need not
     declare an \c{operator>>} function for it, since QtDBus provides

src/dbus/qdbuscontext.cpp

@@ -90,7 +90,7 @@ QDBusContextPrivate *QDBusContextPrivate::set(QObject *obj, QDBusContextPrivate
     exported using QDBusConnection::registerObject(). The following
     example illustrates the usage:
 
-    \snippet doc/src/snippets/code/src_qdbus_qdbuscontext.cpp 0
+    \snippet code/src_qdbus_qdbuscontext.cpp 0
 
     The example illustrates the two typical uses, that of sending
     error replies and that of delayed replies.

src/dbus/qdbusextratypes.cpp

@@ -73,11 +73,11 @@ void QDBusSignature::doCheck()
     A D-Bus function that takes an integer, a D-Bus variant and a string as parameters
     can be called with the following argument list (see QDBusMessage::setArguments()):
 
-    \snippet doc/src/snippets/qdbusextratypes/qdbusextratypes.cpp 0
+    \snippet qdbusextratypes/qdbusextratypes.cpp 0
 
     When a D-Bus function returns a D-Bus variant, it can be retrieved as follows:
 
-    \snippet doc/src/snippets/qdbusextratypes/qdbusextratypes.cpp 1
+    \snippet qdbusextratypes/qdbusextratypes.cpp 1
 
     The QVariant within a QDBusVariant is required to distinguish between a normal
     D-Bus value and a value within a D-Bus variant.

src/dbus/qdbusinterface.cpp

@@ -196,7 +196,7 @@ QDBusInterfacePrivate::~QDBusInterfacePrivate()
     mathematical operation of \tt{"2 + 2"} in a remote application
     called \c com.example.Calculator, accessed via the session bus.
 
-    \snippet doc/src/snippets/code/src_qdbus_qdbusinterface.cpp 0
+    \snippet code/src_qdbus_qdbusinterface.cpp 0
 
     \sa {QtDBus XML compiler (qdbusxml2cpp)}
 */

src/dbus/qdbusmetatype.cpp

@@ -200,7 +200,7 @@ Q_GLOBAL_STATIC(QReadWriteLock, customTypesLock)
     Q_DECLARE_METATYPE() macro, and then registered as in the
     following example:
 
-    \snippet doc/src/snippets/code/src_qdbus_qdbusmetatype.cpp 0
+    \snippet code/src_qdbus_qdbusmetatype.cpp 0
 
     If \c{T} isn't a type derived from one of
     Qt's \l{container classes}, the \c{operator<<} and

src/dbus/qdbuspendingcall.cpp

@@ -97,7 +97,7 @@ QT_BEGIN_NAMESPACE
 
     It is usually used like the following example:
 
-    \snippet doc/src/snippets/code/src.qdbus.qdbuspendingcall.cpp 0
+    \snippet code/src_qdbus_qdbuspendingcall.cpp 0
 
     Note that it is not necessary to keep the original QDBusPendingCall
     object around since QDBusPendingCallWatcher inherits from that class
@@ -106,7 +106,7 @@ QT_BEGIN_NAMESPACE
     The slot connected to by the above code could be something similar
     to the following:
 
-    \snippet doc/src/snippets/code/src.qdbus.qdbuspendingcall.cpp 1
+    \snippet code/src_qdbus_qdbuspendingcall.cpp 1
 
     Note the use of QDBusPendingReply to validate the argument types in
     the reply. If the reply did not contain exactly two arguments

src/dbus/qdbuspendingreply.cpp

@@ -69,22 +69,22 @@
 
     Where with QDBusReply you would write:
 
-    \snippet doc/src/snippets/code/src_qdbus_qdbusreply.cpp 0
+    \snippet code/src_qdbus_qdbusreply.cpp 0
 
     with QDBusPendingReply, the equivalent code (including the blocking
     wait for the reply) would be:
 
-    \snippet doc/src/snippets/code/src.qdbus.qdbuspendingreply.cpp 0
+    \snippet code/src_qdbus_qdbuspendingreply.cpp 0
 
     For method calls that have more than one output argument, with
     QDBusReply, you would write:
 
-    \snippet doc/src/snippets/code/src_qdbus_qdbusreply.cpp 1
+    \snippet code/src_qdbus_qdbusreply.cpp 1
 
     whereas with QDBusPendingReply, all of the output arguments should
     be template parameters:
 
-    \snippet doc/src/snippets/code/src.qdbus.qdbuspendingreply.cpp 2
+    \snippet code/src_qdbus_qdbuspendingreply.cpp 2
 
     QDBusPendingReply objects can be associated with
     QDBusPendingCallWatcher objects, which emit signals when the reply

src/dbus/qdbusreply.cpp

@@ -61,10 +61,10 @@ QT_BEGIN_NAMESPACE
     argument.
 
     It can be used in the following manner:
-    \snippet doc/src/snippets/code/src_qdbus_qdbusreply.cpp 0
+    \snippet code/src_qdbus_qdbusreply.cpp 0
 
     If the remote method call cannot fail, you can skip the error checking:
-    \snippet doc/src/snippets/code/src_qdbus_qdbusreply.cpp 1
+    \snippet code/src_qdbus_qdbusreply.cpp 1
 
     However, if it does fail under those conditions, the value returned by QDBusReply::value() is
     a default-constructed value. It may be indistinguishable from a valid return value.

src/gui/accessible/qaccessible.cpp

@@ -460,7 +460,7 @@ static void qAccessibleCleanup()
     This is a typedef for a pointer to a function with the following
     signature:
 
-    \snippet doc/src/snippets/code/src_gui_accessible_qaccessible.cpp 1
+    \snippet code/src_gui_accessible_qaccessible.cpp 1
 
     The function receives a QString and a QObject pointer, where the
     QString is the key identifying the interface. The QObject is used