Various qt documentation fixes (wk 43)

Fixes for bugs: QTBUG-21073, QTBUG-8625, QTBUG-1231, QTBUG-19808,
QTBUG-8939, QTBUG-20399, QTBUG-20944, QTBUG-12096, QTBUG-12389,
QTBUG-6151, QTBUG-16667, QTBUG-7542, QTBUG-22095, QTBUG-11278 and
QTBUG-15653

14 files changed, 53 insertions, 95 deletions

diff --git a/src/corelib/global/qnamespace.qdoc b/src/corelib/global/qnamespace.qdoc
index 99f82fa..ca81d70 100644
--- a/src/corelib/global/qnamespace.qdoc
+++ b/src/corelib/global/qnamespace.qdoc
@@ -514,7 +514,7 @@
 
     When using signals and slots with multiple threads, see \l{Signals and Slots Across Threads}.
 
-    \sa {Thread Support in Qt}, QObject::connect(), qRegisterMetaType()
+    \sa {Thread Support in Qt}, QObject::connect(), qRegisterMetaType(), Q_DECLARE_METATYPE()
 */
 
 /*!
diff --git a/src/corelib/io/qurl.cpp b/src/corelib/io/qurl.cpp
index 3f49cc6..24117a0 100644
--- a/src/corelib/io/qurl.cpp
+++ b/src/corelib/io/qurl.cpp
@@ -4128,6 +4128,7 @@ QString QUrlPrivate::createErrorString()
     Constructs a URL by parsing \a url. \a url is assumed to be in human
     readable representation, with no percent encoding. QUrl will automatically
     percent encode all characters that are not allowed in a URL.
+    The default parsing mode is TolerantMode.
 
     Example:
 
@@ -4148,7 +4149,8 @@ QUrl::QUrl(const QString &url) : d(0)
 /*!
     \overload
 
-    Parses the \a url using the parser mode \a parsingMode.
+    Parses the \a url using the parser mode \a parsingMode. 
+    The default parsing mode is TolerantMode.
 
     \sa setUrl()
 */
diff --git a/src/corelib/kernel/qabstracteventdispatcher.cpp b/src/corelib/kernel/qabstracteventdispatcher.cpp
index e0ee10e..67e2502 100644
--- a/src/corelib/kernel/qabstracteventdispatcher.cpp
+++ b/src/corelib/kernel/qabstracteventdispatcher.cpp
@@ -230,7 +230,7 @@ void QAbstractEventDispatcherPrivate::releaseTimerId(int timerId)
 
     QAbstractEventDispatcher also allows the integration of an
     external event loop with the Qt event loop. For example, the
-    \l{Qt Solutions}{Motif Extension Qt Solution} includes a
+    \l{ftp://ftp.qt.nokia.com/pub/qt/solutions/lgpl/qtmotifextension-2.7_1-opensource.tar.gz}{Motif Extension} includes a
     reimplementation of QAbstractEventDispatcher that merges Qt and
     Motif events together.
 
diff --git a/src/corelib/kernel/qmetaobject.cpp b/src/corelib/kernel/qmetaobject.cpp
index 71f375f..8e6f14e 100644
--- a/src/corelib/kernel/qmetaobject.cpp
+++ b/src/corelib/kernel/qmetaobject.cpp
@@ -1337,7 +1337,30 @@ const char *QMetaMethod::typeName() const
     Returns the tag associated with this method.
 
     Tags are special macros recognized by \c moc that make it
-    possible to add extra information about a method. For the moment,
+    possible to add extra information about a method. 
+    
+    Tag information can be added in the following
+    way in the function declaration:
+
+    \code
+    #define THISISTESTTAG // tag text
+    ...
+    private slots:
+    THISISTESTTAG void testFunc();
+    \endcode
+
+    and the information can be accessed by using:
+
+    \code
+    MainWindow win;
+    win.show();
+
+    int functionIndex = win.metaObject()->indexOfSlot("testFunc()");
+    QMetaMethod mm = metaObject()->method(functionIndex);
+    qDebug() << mm.tag(); // prints THISISTESTTAG
+    \endcode
+
+    For the moment,
     \c moc doesn't support any special tags.
 */
 const char *QMetaMethod::tag() const
diff --git a/src/corelib/kernel/qobject.cpp b/src/corelib/kernel/qobject.cpp
index 57449bd..9261fef 100644
--- a/src/corelib/kernel/qobject.cpp
+++ b/src/corelib/kernel/qobject.cpp
@@ -2453,7 +2453,7 @@ int QObject::receivers(const char *signal) const
     call qRegisterMetaType() to register the data type before you
     establish the connection.
 
-    \sa disconnect(), sender(), qRegisterMetaType()
+    \sa disconnect(), sender(), qRegisterMetaType(), Q_DECLARE_METATYPE()
 */
 
 bool QObject::connect(const QObject *sender, const char *signal,
diff --git a/src/corelib/tools/qlocale.cpp b/src/corelib/tools/qlocale.cpp
index 09c6d70..5c5048b 100644
--- a/src/corelib/tools/qlocale.cpp
+++ b/src/corelib/tools/qlocale.cpp
@@ -2089,7 +2089,6 @@ QDataStream &operator>>(QDataStream &ds, QLocale &l)
     \value Yugoslavia
     \value Zambia
     \value Zimbabwe
-    \value SerbiaAndMontenegro
     \value Montenegro
     \value Serbia
     \value SaintBarthelemy
diff --git a/src/corelib/tools/qregexp.cpp b/src/corelib/tools/qregexp.cpp
index 678f3d2..bfdcc33 100644
--- a/src/corelib/tools/qregexp.cpp
+++ b/src/corelib/tools/qregexp.cpp
@@ -424,7 +424,7 @@ int qFindString(const QChar *haystack, int haystackLen, int from,
 
     For historical reasons, quantifiers (e.g. \bold{*}) that apply to
     capturing parentheses are more "greedy" than other quantifiers.
-    For example, \bold{a*(a)*} will match "aaa" with cap(1) == "aaa".
+    For example, \bold{a*(a*)} will match "aaa" with cap(1) == "aaa".
     This behavior is different from what other regexp engines do
     (notably, Perl). To obtain a more intuitive capturing behavior,
     specify QRegExp::RegExp2 to the QRegExp constructor or call
diff --git a/src/gui/dialogs/qabstractprintdialog.cpp b/src/gui/dialogs/qabstractprintdialog.cpp
index 4b495d1..6c9c61e 100644
--- a/src/gui/dialogs/qabstractprintdialog.cpp
+++ b/src/gui/dialogs/qabstractprintdialog.cpp
@@ -79,7 +79,7 @@ class QPrintDialogPrivate : public QAbstractPrintDialogPrivate
     \value AllPages All pages should be printed.
     \value Selection Only the selection should be printed.
     \value PageRange The specified page range should be printed.
-    \value CurrentPage Only the currently visible page should be printed.
+    \value CurrentPage Only the currently visible page should be printed. (This value was introduced in 4.7.)
 
     \sa QPrinter::PrintRange
 */
@@ -95,7 +95,7 @@ class QPrintDialogPrivate : public QAbstractPrintDialogPrivate
     \value PrintPageRange The page range selection option is enabled.
     \value PrintShowPageSize  Show the page size + margins page only if this is enabled.
     \value PrintCollateCopies The collate copies option is enabled
-    \value PrintCurrentPage The print current page option is enabled
+    \value PrintCurrentPage The print current page option is enabled (This value was introduced in 4.7.)
 
     This value is obsolete and does nothing since Qt 4.5:
 
diff --git a/src/gui/graphicsview/qgraphicsitem.cpp b/src/gui/graphicsview/qgraphicsitem.cpp
index 9e1fd09..abf9d44 100644
--- a/src/gui/graphicsview/qgraphicsitem.cpp
+++ b/src/gui/graphicsview/qgraphicsitem.cpp
@@ -11050,9 +11050,9 @@ QGraphicsItemGroup::~QGraphicsItemGroup()
 }
 
 /*!
-    Adds the given \a item to this item group. The item will be
-    reparented to this group, but its position and transformation
-    relative to the scene will stay intact.
+    Adds the given \a item and item's child items to this item group. 
+    The item and child items will be reparented to this group, 
+    but its position and transformation relative to the scene will stay intact.
 
     \sa removeFromGroup(), QGraphicsScene::createItemGroup()
 */
diff --git a/src/gui/graphicsview/qgraphicslayout.cpp b/src/gui/graphicsview/qgraphicslayout.cpp
index f983955..5f0883f 100644
--- a/src/gui/graphicsview/qgraphicslayout.cpp
+++ b/src/gui/graphicsview/qgraphicslayout.cpp
@@ -102,6 +102,10 @@ QT_BEGIN_NAMESPACE
     any way, but for a linear layout, the order is essential. When writing your own
     layout subclass, you are free to choose the API that best suits your layout.
 
+    For adding layout items to the custom layout, the QGraphicsLayout provides
+    convenience function addChildLayoutItem(). The function will take care of
+    automatically reparenting graphics items, if needed.
+    
     \section1 Activating the Layout
 
     When the layout's geometry changes, QGraphicsLayout immediately rearranges
diff --git a/src/multimedia/audio/qaudiodeviceinfo.cpp b/src/multimedia/audio/qaudiodeviceinfo.cpp
index 603c388..c46fa7f 100644
--- a/src/multimedia/audio/qaudiodeviceinfo.cpp
+++ b/src/multimedia/audio/qaudiodeviceinfo.cpp
@@ -114,9 +114,9 @@ public:
     supported format that is as close as possible to the format with
     nearestFormat(). For instance:
 
-    \snippet doc/src/snippets/audio/main.cpp 1
+    \snippet doc/src/snippets/audio/main.cpp 6
     \dots 8
-    \snippet doc/src/snippets/audio/main.cpp 2
+    \snippet doc/src/snippets/audio/main.cpp 7
 
     A QAudioDeviceInfo is used by Qt to construct
     classes that communicate with the device--such as
diff --git a/src/multimedia/audio/qaudioinput.cpp b/src/multimedia/audio/qaudioinput.cpp
index e209dd1..d22f66d 100644
--- a/src/multimedia/audio/qaudioinput.cpp
+++ b/src/multimedia/audio/qaudioinput.cpp
@@ -76,37 +76,9 @@ QT_BEGIN_NAMESPACE
     with a QIODevice opened for writing. For instance, to record to a
     file, you can:
 
-    \code
-      QFile outputFile;   // class member.
-      QAudioInput* audio; // class member.
-    \endcode
-
-    \code
-    {
-      outputFile.setFileName("/tmp/test.raw");
-      outputFile.open( QIODevice::WriteOnly | QIODevice::Truncate );
-
-      QAudioFormat format;
-      // set up the format you want, eg.
-      format.setFrequency(8000);
-      format.setChannels(1);
-      format.setSampleSize(8);
-      format.setCodec("audio/pcm");
-      format.setByteOrder(QAudioFormat::LittleEndian);
-      format.setSampleType(QAudioFormat::UnSignedInt);
-
-      QAudioDeviceInfo info = QAudioDeviceInfo::defaultInputDevice();
-      if (!info.isFormatSupported(format)) {
-          qWarning()<<"default format not supported try to use nearest";
-          format = info.nearestFormat(format);
-      }
-
-      audio = new QAudioInput(format, this);
-      QTimer::singleShot(3000, this, SLOT(stopRecording()));
-      audio->start(&outputFile);
-      // Records audio for 3000ms
-    }
-    \endcode
+    \snippet doc/src/snippets/audio/main.cpp 3
+    \dots 4
+    \snippet doc/src/snippets/audio/main.cpp 0
 
     This will start recording if the format specified is supported by
     the input device (you can check this with
@@ -114,14 +86,7 @@ QT_BEGIN_NAMESPACE
     snags, use the error() function to check what went wrong. We stop
     recording in the \c stopRecording() slot.
 
-    \code
-    void stopRecording()
-    {
-      audio->stop();
-      outputFile->close();
-      delete audio;
-    }
-    \endcode
+    \snippet doc/src/snippets/audio/main.cpp 1
 
     At any point in time, QAudioInput will be in one of four states:
     active, suspended, stopped, or idle. These states are specified by
@@ -143,7 +108,7 @@ QT_BEGIN_NAMESPACE
     an error is encountered.  Connect to the stateChanged() signal to
     handle the error:
 
-    \snippet doc/src/snippets/audio/main.cpp 0
+    \snippet doc/src/snippets/audio/main.cpp 2
 
     \sa QAudioOutput, QAudioDeviceInfo
 
diff --git a/src/multimedia/audio/qaudiooutput.cpp b/src/multimedia/audio/qaudiooutput.cpp
index 1abdc58..5420574 100644
--- a/src/multimedia/audio/qaudiooutput.cpp
+++ b/src/multimedia/audio/qaudiooutput.cpp
@@ -72,35 +72,9 @@ QT_BEGIN_NAMESPACE
     needs from the io device. So playing back an audio file is as
     simple as:
 
-    \code
-      QFile inputFile;     // class member.
-      QAudioOutput* audio; // class member.
-    \endcode
-
-    \code
-      inputFile.setFileName("/tmp/test.raw");
-      inputFile.open(QIODevice::ReadOnly);
-
-      QAudioFormat format;
-      // Set up the format, eg.
-      format.setFrequency(8000);
-      format.setChannels(1);
-      format.setSampleSize(8);
-      format.setCodec("audio/pcm");
-      format.setByteOrder(QAudioFormat::LittleEndian);
-      format.setSampleType(QAudioFormat::UnSignedInt);
-
-      QAudioDeviceInfo info(QAudioDeviceInfo::defaultOutputDevice());
-      if (!info.isFormatSupported(format)) {
-          qWarning()<<"raw audio format not supported by backend, cannot play audio.";
-          return;
-      }
-
-      audio = new QAudioOutput(format, this);
-      connect(audio,SIGNAL(stateChanged(QAudio::State)),SLOT(finishedPlaying(QAudio::State)));
-      audio->start(&inputFile);
-
-    \endcode
+    \snippet doc/src/snippets/audio/main.cpp 9
+    \dots 4
+    \snippet doc/src/snippets/audio/main.cpp 4
 
     The file will start playing assuming that the audio system and
     output device support it. If you run out of luck, check what's
@@ -108,16 +82,7 @@ QT_BEGIN_NAMESPACE
 
     After the file has finished playing, we need to stop the device:
 
-    \code
-      void finishedPlaying(QAudio::State state)
-      {
-        if(state == QAudio::IdleState) {
-          audio->stop();
-          inputFile.close();
-          delete audio;
-        }
-      }
-    \endcode
+    \snippet doc/src/snippets/audio/main.cpp 5
 
     At any given time, the QAudioOutput will be in one of four states:
     active, suspended, stopped, or idle. These states are described
@@ -145,7 +110,7 @@ QT_BEGIN_NAMESPACE
     You can check for errors by connecting to the stateChanged()
     signal:
 
-    \snippet doc/src/snippets/audio/main.cpp 3
+    \snippet doc/src/snippets/audio/main.cpp 8
 
     \sa QAudioInput, QAudioDeviceInfo
 */
diff --git a/src/xml/dom/qdom.cpp b/src/xml/dom/qdom.cpp
index 7c7cafc..db5306e 100644
--- a/src/xml/dom/qdom.cpp
+++ b/src/xml/dom/qdom.cpp
@@ -2959,7 +2959,7 @@ QDomElement QDomNode::firstChildElement(const QString &tagName) const
 
 /*!
     Returns the last child element with tag name \a tagName if tagName is non-empty;
-    otherwise returns the first child element. Returns a null element if no
+    otherwise returns the last child element. Returns a null element if no
     such child exists.
 
     \sa firstChildElement() previousSiblingElement() nextSiblingElement()