From 4f6ccce6ad8b6df523fd354aac2bcd32a7a65bc4 Mon Sep 17 00:00:00 2001 From: David Boddie Date: Tue, 10 May 2011 19:52:50 +0200 Subject: Doc: Applied pending fixes to API documentation. --- src/corelib/global/qglobal.cpp | 8 ++--- src/corelib/io/qdatastream.cpp | 3 +- src/corelib/io/qfile.cpp | 2 ++ src/corelib/io/qfilesystemengine.cpp | 2 +- src/corelib/io/qfsfileengine.cpp | 2 +- src/corelib/io/qurl.cpp | 2 +- src/corelib/kernel/qobject.cpp | 56 ++++++++---------------------- src/corelib/kernel/qobject.h | 5 +++ src/corelib/kernel/qtimer.cpp | 9 +++++ src/corelib/kernel/qtranslator.cpp | 8 ++--- src/corelib/thread/qmutexpool.cpp | 3 +- src/corelib/tools/qlist.cpp | 4 +-- src/corelib/tools/qlocale.cpp | 2 +- src/corelib/tools/qscopedpointer.cpp | 5 ++- src/corelib/tools/qscopedvaluerollback.cpp | 4 +-- src/corelib/tools/qstring.cpp | 21 ++++++++++- src/corelib/tools/qstringbuilder.cpp | 2 +- src/corelib/tools/qvarlengtharray.qdoc | 18 ++++++++-- src/corelib/tools/qvector.cpp | 2 +- 19 files changed, 90 insertions(+), 68 deletions(-) diff --git a/src/corelib/global/qglobal.cpp b/src/corelib/global/qglobal.cpp index a6b9bdd..a0709d0 100644 --- a/src/corelib/global/qglobal.cpp +++ b/src/corelib/global/qglobal.cpp @@ -2883,8 +2883,8 @@ int qrand() \relates \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 \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 0361d18..56404d9 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 0ade573..01fb231 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 00c33bd..c4725e2 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 802d394..bf4308a 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 efd3f45..cdc84f5 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 357cfd3..772a865 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 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}(\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 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}(\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 *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 0ad73f5..f962fec 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 qFindChildren(const QObject *oobj, const QString &name = QString()); +QList qFindChildren(const QObject *o, const QRegExp &re); +#endif #ifdef QT_DEPRECATED template 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 3efeda2..b23da3a 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 22b06a5..440bc32 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 144fa35..f88b3a7 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 1501daf..747e756 100644 --- a/src/corelib/tools/qlist.cpp +++ b/src/corelib/tools/qlist.cpp @@ -590,10 +590,10 @@ void **QListData::erase(void **xi) \sa operator=() */ -/*! \fn QList::QList(std::initializer_list args) +/*! \fn inline QList::QList(std::initializer_list 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 c8ed94b..857cc21 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 60a5d70..2afa731 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 8933efc..00dcedf 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 5493ba9..f422b32 100644 --- a/src/corelib/tools/qstring.cpp +++ b/src/corelib/tools/qstring.cpp @@ -841,6 +841,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 @@ -9115,7 +9134,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 QStringRef::toUcs4() const { diff --git a/src/corelib/tools/qstringbuilder.cpp b/src/corelib/tools/qstringbuilder.cpp index a5dff88..8c745fc 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 3c80c1c..4c15ad0 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 06ed6bb..0d79215 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 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 */ -- cgit v0.12