Doc: Applied pending fixes to API documentation.

19 files changed, 90 insertions, 68 deletions

diff --git a/src/corelib/global/qglobal.cpp b/src/corelib/global/qglobal.cpp
index a6b9bddcc4..a0709d091e 100644
--- a/src/corelib/global/qglobal.cpp
+++ b/src/corelib/global/qglobal.cpp
@@ -2883,8 +2883,8 @@ int qrand()
     \relates <QtGlobal>
     \since 4.8
 
-    \brief Hints the compiler that the enclosed condition is likely to evaluate
-    to \c true.
+    \brief Hints to the compiler that the enclosed condition, \a expr, is
+    likely to evaluate to \c true.
 
     Use of this macro can help the compiler to optimize the code.
 
@@ -2900,8 +2900,8 @@ int qrand()
     \relates <QtGlobal>
     \since 4.8
 
-    \brief Hints the compiler that the enclosed condition is likely to evaluate
-    to \c false.
+    \brief Hints to the compiler that the enclosed condition, \a expr, is
+    likely to evaluate to \c false.
 
     Use of this macro can help the compiler to optimize the code.
 
diff --git a/src/corelib/io/qdatastream.cpp b/src/corelib/io/qdatastream.cpp
index 0361d180b2..56404d9046 100644
--- a/src/corelib/io/qdatastream.cpp
+++ b/src/corelib/io/qdatastream.cpp
@@ -584,8 +584,9 @@ void QDataStream::setByteOrder(ByteOrder bo)
     \value Qt_4_3 Version 9 (Qt 4.3)
     \value Qt_4_4 Version 10 (Qt 4.4)
     \value Qt_4_5 Version 11 (Qt 4.5)
-    \value Qt_4_6 Version 12 (Qt 4.6)
+    \value Qt_4_6 Version 12 (Qt 4.6, Qt 4.7, Qt 4.8)
     \value Qt_4_7 Same as Qt_4_6.
+    \value Qt_4_8 Same as Qt_4_6.
 
     \sa setVersion(), version()
 */
diff --git a/src/corelib/io/qfile.cpp b/src/corelib/io/qfile.cpp
index 0ade573ea4..01fb2315de 100644
--- a/src/corelib/io/qfile.cpp
+++ b/src/corelib/io/qfile.cpp
@@ -1656,6 +1656,8 @@ bool QFile::atEnd() const
 }
 
 /*!
+    \fn bool QFile::seek(qint64 pos)
+
     For random-access devices, this function sets the current position
     to \a pos, returning true on success, or false if an error occurred.
     For sequential devices, the default behavior is to do nothing and
diff --git a/src/corelib/io/qfilesystemengine.cpp b/src/corelib/io/qfilesystemengine.cpp
index 00c33bd797..c4725e2ff3 100644
--- a/src/corelib/io/qfilesystemengine.cpp
+++ b/src/corelib/io/qfilesystemengine.cpp
@@ -196,7 +196,7 @@ static bool _q_resolveEntryAndCreateLegacyEngine_recursive(QFileSystemEntry &ent
     Resolves the \a entry (see QDir::searchPaths) and returns an engine for
     it, but never a QFSFileEngine.
 
-    \returns a file engine that can be used to access the entry. Returns 0 if
+    Returns a file engine that can be used to access the entry. Returns 0 if
     QFileSystemEngine API should be used to query and interact with the file
     system object.
 */
diff --git a/src/corelib/io/qfsfileengine.cpp b/src/corelib/io/qfsfileengine.cpp
index 802d394af1..bf4308a1a3 100644
--- a/src/corelib/io/qfsfileengine.cpp
+++ b/src/corelib/io/qfsfileengine.cpp
@@ -472,10 +472,10 @@ qint64 QFSFileEngine::size() const
     return d->nativeSize();
 }
 
+#ifndef Q_OS_WIN
 /*!
     \internal
 */
-#ifndef Q_OS_WIN
 qint64 QFSFileEnginePrivate::sizeFdFh() const
 {
     Q_Q(const QFSFileEngine);
diff --git a/src/corelib/io/qurl.cpp b/src/corelib/io/qurl.cpp
index efd3f45ef0..cdc84f5db4 100644
--- a/src/corelib/io/qurl.cpp
+++ b/src/corelib/io/qurl.cpp
@@ -6088,7 +6088,7 @@ bool QUrl::isDetached() const
     "//servername/path/to/file.txt". Note that only certain platforms can
     actually open this file using QFile::open().
 
-    \sa toLocalFile(), isLocalFile(), QDir::toNativeSeparators
+    \sa toLocalFile(), isLocalFile(), QDir::toNativeSeparators()
 */
 QUrl QUrl::fromLocalFile(const QString &localFile)
 {
diff --git a/src/corelib/kernel/qobject.cpp b/src/corelib/kernel/qobject.cpp
index 357cfd3f33..772a8652e0 100644
--- a/src/corelib/kernel/qobject.cpp
+++ b/src/corelib/kernel/qobject.cpp
@@ -1790,6 +1790,7 @@ QObjectList QObject::queryList(const char *inheritsClass,
 /*!
     \fn T qFindChild(const QObject *obj, const QString &name)
     \relates QObject
+    \overload qFindChildren()
     \obsolete
 
     This function is equivalent to
@@ -1805,6 +1806,7 @@ QObjectList QObject::queryList(const char *inheritsClass,
 /*!
     \fn QList<T> qFindChildren(const QObject *obj, const QString &name)
     \relates QObject
+    \overload qFindChildren()
     \obsolete
 
     This function is equivalent to
@@ -1834,38 +1836,6 @@ QObjectList QObject::queryList(const char *inheritsClass,
 
 /*!
     \internal
-    \fn T qFindChild(const QObject *obj, const QString &name = QString(), T dummy = 0)
-    \relates QObject
-    \overload qFindChildren()
-
-    This function is equivalent to
-    \a{obj}->\l{QObject::findChild()}{findChild}<T>(\a name).
-
-    \note This function was provided as a workaround for MSVC 6
-    which did not support member template functions. It is advised
-    to use the other form in new code.
-
-    \sa QObject::findChild()
-*/
-
-/*!
-    \internal
-    \fn QList<T> qFindChildren(const QObject *obj, const QString &name = QString(), T dummy = 0)
-    \relates QObject
-    \overload qFindChildren()
-
-    This function is equivalent to
-    \a{obj}->\l{QObject::findChildren()}{findChildren}<T>(\a name).
-
-    \note This function was provided as a workaround for MSVC 6
-    which did not support member template functions. It is advised
-    to use the other form in new code.
-
-    \sa QObject::findChildren()
-*/
-
-/*!
-    \internal
 */
 void qt_qFindChildren_helper(const QObject *parent, const QString &name, const QRegExp *re,
                              const QMetaObject &mo, QList<void*> *list)
@@ -2419,20 +2389,22 @@ int QObject::receivers(const char *signal) const
     This helper function calculates signal and method index for the given
     member in the specified class.
 
-    \li If member.mobj is 0 then both signalIndex and methodIndex are set to -1.
+    \list
+    \o If member.mobj is 0 then both signalIndex and methodIndex are set to -1.
 
-    \li If specified member is not a member of obj instance class (or one of
+    \o If specified member is not a member of obj instance class (or one of
     its parent classes) then both signalIndex and methodIndex are set to -1.
+    \endlist
 
     This function is used by QObject::connect and QObject::disconnect which
     are working with QMetaMethod.
 
-    \param[out] signalIndex is set to the signal index of member. If the member
+    \a signalIndex is set to the signal index of member. If the member
     specified is not signal this variable is set to -1.
 
-    \param[out] methodIndex is set to the method index of the member. If the
-    member is not a method of the object specified by obj param this variable
-    is set to -1.
+    \a methodIndex is set to the method index of the member. If the
+    member is not a method of the object specified by the \a obj argument this
+    variable is set to -1.
 */
 void QMetaObjectPrivate::memberIndexes(const QObject *obj,
                                        const QMetaMethod &member,
@@ -2689,9 +2661,9 @@ bool QObject::connect(const QObject *sender, const char *signal,
             Qt::ConnectionType type)
     but it uses QMetaMethod to specify signal and method.
 
-    \see connect(const QObject *sender, const char *signal,
-                 const QObject *receiver, const char *method,
-                 Qt::ConnectionType type)
+    \sa connect(const QObject *sender, const char *signal,
+                const QObject *receiver, const char *method,
+                Qt::ConnectionType type)
  */
 bool QObject::connect(const QObject *sender, const QMetaMethod &signal,
                       const QObject *receiver, const QMetaMethod &method,
@@ -2987,7 +2959,7 @@ bool QObject::disconnect(const QObject *sender, const char *signal,
     In the same way 0 can be used for \a receiver in the meaning "any receiving object". In this case
     method shoud also be QMetaMethod(). \a sender parameter should be never 0.
 
-    \see disconnect(const QObject *sender, const char *signal, const QObject *receiver, const char *method)
+    \sa disconnect(const QObject *sender, const char *signal, const QObject *receiver, const char *method)
  */
 bool QObject::disconnect(const QObject *sender, const QMetaMethod &signal,
                          const QObject *receiver, const QMetaMethod &method)
diff --git a/src/corelib/kernel/qobject.h b/src/corelib/kernel/qobject.h
index 0ad73f5fe9..f962fec4f5 100644
--- a/src/corelib/kernel/qobject.h
+++ b/src/corelib/kernel/qobject.h
@@ -345,6 +345,11 @@ public:
 };
 #endif
 
+#ifdef qdoc
+T qFindChild(const QObject *o, const QString &name = QString());
+QList<T> qFindChildren(const QObject *oobj, const QString &name = QString());
+QList<T> qFindChildren(const QObject *o, const QRegExp &re);
+#endif
 #ifdef QT_DEPRECATED
 template<typename T>
 inline QT_DEPRECATED T qFindChild(const QObject *o, const QString &name = QString())
diff --git a/src/corelib/kernel/qtimer.cpp b/src/corelib/kernel/qtimer.cpp
index 3efeda229d..b23da3a971 100644
--- a/src/corelib/kernel/qtimer.cpp
+++ b/src/corelib/kernel/qtimer.cpp
@@ -205,6 +205,9 @@ QTimer::~QTimer()
 
     Starts or restarts the timer with the timeout specified in \l interval.
 
+    If the timer is already running, it will be
+    \l{QTimer::stop()}{stopped} and restarted.
+
     If \l singleShot is true, the timer will be activated only once.
 */
 void QTimer::start()
@@ -218,6 +221,12 @@ void QTimer::start()
 /*!
     Starts or restarts the timer with a timeout interval of \a msec
     milliseconds.
+
+    If the timer is already running, it will be
+    \l{QTimer::stop()}{stopped} and restarted.
+
+    If \l singleShot is true, the timer will be activated only once.
+
 */
 void QTimer::start(int msec)
 {
diff --git a/src/corelib/kernel/qtranslator.cpp b/src/corelib/kernel/qtranslator.cpp
index 22b06a56a6..440bc32bf1 100644
--- a/src/corelib/kernel/qtranslator.cpp
+++ b/src/corelib/kernel/qtranslator.cpp
@@ -600,7 +600,7 @@ static QString find_translation(const QLocale & locale,
 /*!
     \since 4.8
 
-    Loads \a filename + \a prefix + \a \l{QLocale::uiLanguages()}{ui language
+    Loads \a filename + \a prefix + \l{QLocale::uiLanguages()}{ui language
     name} + \a suffix (".qm" if the \a suffix is not specified), which may be
     an absolute file name or relative to \a directory. Returns true if the
     translation is successfully loaded; otherwise returns false.
@@ -618,7 +618,7 @@ static QString find_translation(const QLocale & locale,
     \endlist
 
     For example, an application running in the locale with the following
-    l{QLocale::uiLanguages()}{ui languages} - "es", "fr-CA", "de" might call
+    \l{QLocale::uiLanguages()}{ui languages} - "es", "fr-CA", "de" might call
     load(QLocale::system(), "foo", ".", "/opt/foolib", ".qm"). load() would
     replace '-' (dash) with '_' (underscore) in the ui language and then try to
     open the first existing readable file from this list:
@@ -637,8 +637,8 @@ static QString find_translation(const QLocale & locale,
     \o \c /opt/foolib/foo
     \endlist
 
-    For OSs where file system is case sensitive, QTranslator also tries to load
-    a lower-cased version of the locale name.
+    On operating systems where file system is case sensitive, QTranslator also
+    tries to load a lower-cased version of the locale name.
 */
 bool QTranslator::load(const QLocale & locale,
                        const QString & filename,
diff --git a/src/corelib/thread/qmutexpool.cpp b/src/corelib/thread/qmutexpool.cpp
index 144fa35137..f88b3a734f 100644
--- a/src/corelib/thread/qmutexpool.cpp
+++ b/src/corelib/thread/qmutexpool.cpp
@@ -123,7 +123,8 @@ QMutexPool *QMutexPool::instance()
     return globalMutexPool();
 }
 
-/*!  \fn QMutexPool::get(void *address)
+/*!
+    \fn QMutexPool::get(const void *address)
     Returns a QMutex from the pool. QMutexPool uses the value \a address
     to determine which mutex is returned from the pool.
 */
diff --git a/src/corelib/tools/qlist.cpp b/src/corelib/tools/qlist.cpp
index 90ed7293fd..ba79e01782 100644
--- a/src/corelib/tools/qlist.cpp
+++ b/src/corelib/tools/qlist.cpp
@@ -499,10 +499,10 @@ void **QListData::erase(void **xi)
     \sa operator=()
 */
 
-/*! \fn QList::QList(std::initializer_list<T> args)
+/*! \fn inline QList::QList(std::initializer_list<T> args)
     \since 4.8
 
-    Construct a list from a std::initilizer_list.
+    Construct a list from the std::initializer_list specified by \a args.
 
     This constructor is only enabled if the compiler supports C++0x
 */
diff --git a/src/corelib/tools/qlocale.cpp b/src/corelib/tools/qlocale.cpp
index c8ed94b35f..857cc21bb7 100644
--- a/src/corelib/tools/qlocale.cpp
+++ b/src/corelib/tools/qlocale.cpp
@@ -937,7 +937,7 @@ QLocale::Country QLocale::country() const
     name() will not contain it for compatibility reasons. Use bcp47Name() instead
     if you need a full locale name.
 
-    \sa QLocale(const QString &), language(), script(), country(), bcp47Name()
+    \sa QLocale(), language(), script(), country(), bcp47Name()
 */
 
 QString QLocale::name() const
diff --git a/src/corelib/tools/qscopedpointer.cpp b/src/corelib/tools/qscopedpointer.cpp
index 60a5d70632..2afa731a8f 100644
--- a/src/corelib/tools/qscopedpointer.cpp
+++ b/src/corelib/tools/qscopedpointer.cpp
@@ -252,10 +252,9 @@ QT_BEGIN_NAMESPACE
 */
 
 /*!
-    \fn QScopedArrayPointer::QScopedArrayPointer(T *p = 0)
+    \fn QScopedArrayPointer::QScopedArrayPointer()
 
-    Constructs this QScopedArrayPointer instance and sets its pointer
-    to \a p.
+    Constructs a QScopedArrayPointer instance.
 */
 
 /*!
diff --git a/src/corelib/tools/qscopedvaluerollback.cpp b/src/corelib/tools/qscopedvaluerollback.cpp
index 8933efc180..00dcedf6ff 100644
--- a/src/corelib/tools/qscopedvaluerollback.cpp
+++ b/src/corelib/tools/qscopedvaluerollback.cpp
@@ -45,7 +45,7 @@ QT_BEGIN_NAMESPACE
 
 /*!
     \class QScopedValueRollback
-    \brief The QScopedValueRollback resets a variable to its previous value on destruction
+    \brief The QScopedValueRollback class resets a variable to its previous value on destruction.
     \since 4.8
     \ingroup misc
 
@@ -65,7 +65,7 @@ QT_BEGIN_NAMESPACE
 /*!
     \fn QScopedValueRollback::QScopedValueRollback(T &var)
 
-    Stores the previous value of var internally, for revert on destruction.
+    Stores the previous value of \a var internally, for revert on destruction.
 */
 
 /*!
diff --git a/src/corelib/tools/qstring.cpp b/src/corelib/tools/qstring.cpp
index 3b3f715b9d..417adb69e5 100644
--- a/src/corelib/tools/qstring.cpp
+++ b/src/corelib/tools/qstring.cpp
@@ -837,6 +837,25 @@ int QString::grow(int size)
     \sa QString::const_iterator
 */
 
+/*!
+    \typedef QString::const_reference
+
+    The QString::const_reference typedef provides an STL-style
+    const reference for QString.
+*/
+/*!
+    \typedef QString::reference
+
+    The QString::const_reference typedef provides an STL-style
+    reference for QString.
+*/
+/*!
+    \typedef QString::value_type
+
+    The QString::const_reference typedef provides an STL-style
+    value type for QString.
+*/
+
 /*! \fn QString::iterator QString::begin()
 
     Returns an \l{STL-style iterator} pointing to the first character in
@@ -9111,7 +9130,7 @@ QByteArray QStringRef::toUtf8() const
     UCS-4 is a Unicode codec and is lossless. All characters from this string
     can be encoded in UCS-4.
 
-    \sa fromUtf8(), toAscii(), toLatin1(), toLocal8Bit(), QTextCodec, fromUcs4(), toWCharArray()
+    \sa toAscii(), toLatin1(), toLocal8Bit(), QTextCodec
 */
 QVector<uint> QStringRef::toUcs4() const
 {
diff --git a/src/corelib/tools/qstringbuilder.cpp b/src/corelib/tools/qstringbuilder.cpp
index a5dff88f43..8c745fc4b7 100644
--- a/src/corelib/tools/qstringbuilder.cpp
+++ b/src/corelib/tools/qstringbuilder.cpp
@@ -142,7 +142,7 @@ QT_BEGIN_NAMESPACE
   characters.
  */
 
-/*! \fn QStringBuilder::operator QString() const
+/*! \fn operator QStringBuilder::QString() const
  
     Converts the \c QLatin1Literal into a \c QString object.
 */
diff --git a/src/corelib/tools/qvarlengtharray.qdoc b/src/corelib/tools/qvarlengtharray.qdoc
index 3c80c1cbbd..4c15ad0d13 100644
--- a/src/corelib/tools/qvarlengtharray.qdoc
+++ b/src/corelib/tools/qvarlengtharray.qdoc
@@ -337,6 +337,20 @@
     Typedef for const T &. Provided for STL compatibility.
 */
 
+/*!
+    \typedef QVarLengthArray::const_iterator
+    \since 4.7
+
+    Typedef for const T *. Provided for STL compatibility.
+*/
+
+/*!
+    \typedef QVarLengthArray::iterator
+    \since 4.7
+
+    Typedef for T *. Provided for STL compatibility.
+*/
+
 /*! \fn void QVarLengthArray::prepend(const T &value)
 
     \since 4.8
@@ -501,7 +515,7 @@
 
     \relates QVarLengthArray
     \since 4.8
-    Returns true if the two array are equal;
+    Returns true if the two arrays, specified by \a left and \a right, are equal.
 
     Two arrays are considered equal if they contain the same values
     in the same order.
@@ -516,7 +530,7 @@
 
     \relates QVarLengthArray
     \since 4.8
-    Returns true if the two array are different;
+    Returns true if the two arrays, specified by \a left and \a right, are \e not equal.
 
     Two arrays are considered equal if they contain the same values
     in the same order.
diff --git a/src/corelib/tools/qvector.cpp b/src/corelib/tools/qvector.cpp
index 06ed6bb1a5..0d792153e6 100644
--- a/src/corelib/tools/qvector.cpp
+++ b/src/corelib/tools/qvector.cpp
@@ -277,7 +277,7 @@ int QVectorData::grow(int sizeofTypedData, int size, int sizeofT, bool excessive
 /*! \fn QVector::QVector(std::initializer_list<T> args)
     \since 4.8
 
-    Construct a vector from a std::initilizer_list.
+    Construct a vector from the std::initilizer_list given by \a args.
 
     This constructor is only enabled if the compiler supports C++0x
 */