Doc: Applied pending fixes to API documentation.

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.
 

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()
 */

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

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.
 */

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);

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)
 {

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
@@ -1832,38 +1834,6 @@ QObjectList QObject::queryList(const char *inheritsClass,
     \sa QObject::findChildren()
 */
 
-/*!
-    \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
 */
@@ -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)

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())

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)
 {

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,

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.
 */

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
 */

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

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.
 */
 
 /*!

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.
 */
 
 /*!

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
 {

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.
 */

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.

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
 */