From ec1548ae122af2febfc61c0242025ee52c8cbc30 Mon Sep 17 00:00:00 2001 From: Topi Reinio Date: Wed, 31 Oct 2018 13:49:14 +0100 Subject: Doc: Fix various documentation warnings These include typos, marking functions as \internal, documenting trivial things, and fixing the function signatures passed to the \fn command. Task-number: QTBUG-71502 Change-Id: I24a9e1f7e1cdb39e5c31b99202bdd593c6b789ff Reviewed-by: Martin Smith Reviewed-by: Paul Wicking Reviewed-by: Edward Welbourne --- src/corelib/global/qglobal.cpp | 2 +- src/corelib/global/qglobalstatic.qdoc | 10 ++++++---- src/corelib/io/qdir.cpp | 11 ++++++----- src/corelib/io/qprocess.cpp | 8 ++++---- src/corelib/kernel/qdeadlinetimer.cpp | 5 +++++ src/corelib/kernel/qeventdispatcher_cf.mm | 2 +- src/corelib/kernel/qtimer.cpp | 18 +++++++++--------- src/corelib/tools/qbytearray.cpp | 4 ++-- src/corelib/tools/qmap.cpp | 2 +- src/corelib/tools/qregularexpression.cpp | 4 ++-- src/corelib/tools/qshareddata.cpp | 7 +++++++ src/corelib/tools/qstring.cpp | 2 +- src/corelib/tools/qtimezone.cpp | 2 +- 13 files changed, 46 insertions(+), 31 deletions(-) (limited to 'src/corelib') diff --git a/src/corelib/global/qglobal.cpp b/src/corelib/global/qglobal.cpp index 5c1665fa00..88d4877be5 100644 --- a/src/corelib/global/qglobal.cpp +++ b/src/corelib/global/qglobal.cpp @@ -3796,7 +3796,7 @@ bool qunsetenv(const char *varName) dependent delayed translation in the given \a context with the given \a comment. The \a context is typically a class and also needs to be specified - as a string literal. The string literal \a disambiguation should be + as a string literal. The string literal \a comment should be a short semantic tag to tell apart otherwise identical strings. The macro tells lupdate to collect the string, and expands to an diff --git a/src/corelib/global/qglobalstatic.qdoc b/src/corelib/global/qglobalstatic.qdoc index dbea04ecab..e7935d5a9b 100644 --- a/src/corelib/global/qglobalstatic.qdoc +++ b/src/corelib/global/qglobalstatic.qdoc @@ -435,6 +435,7 @@ */ /*! + \keyword qglobalstatic-operator-type-ptr \fn template QGlobalStatic::operator Type*() This function returns the address of the contents of this global static. If @@ -476,10 +477,11 @@ by this function. If the contents have already been destroyed, this function will return a null pointer. - This function is equivalent to \l {operator Type *()}. It is provided for - compatibility with the private Q_GLOBAL_STATIC implementation that existed - in Qt 4.x and 5.0. New code should avoid using it and should instead treat - the object as a smart pointer. + This function is equivalent to \l {qglobalstatic-operator-type-ptr} + {operator Type *()}. It is provided for compatibility with the private + Q_GLOBAL_STATIC implementation that existed in Qt 4.x and 5.0. New code + should avoid using it and should instead treat the object as a smart + pointer. */ /*! diff --git a/src/corelib/io/qdir.cpp b/src/corelib/io/qdir.cpp index 75fd0f8e0a..7df461ddce 100644 --- a/src/corelib/io/qdir.cpp +++ b/src/corelib/io/qdir.cpp @@ -1040,7 +1040,8 @@ QStringList QDir::nameFilters() const list of filters specified by \a nameFilters. Each name filter is a wildcard (globbing) filter that understands - \c{*} and \c{?} wildcards. (See \l{QRegularExpression wildcard matching}.) + \c{*} and \c{?} wildcards. See \l{QRegularExpression#Wildcard matching} + {QRegularExpression Wildcard Matching}. For example, the following code sets three name filters on a QDir to ensure that only files with extensions typically used for C++ @@ -2120,8 +2121,8 @@ QString QDir::rootPath() patterns in the list of \a filters; otherwise returns \c false. The matching is case insensitive. - \sa {QRegularExpression Wildcard matching}, QRegularExpression::wildcardToRegularExpression(), - entryList(), entryInfoList() + \sa {QRegularExpression#Wildcard matching}{QRegularExpression Wildcard Matching}, + entryList(), entryInfoList() */ bool QDir::match(const QStringList &filters, const QString &fileName) { @@ -2143,8 +2144,8 @@ bool QDir::match(const QStringList &filters, const QString &fileName) contain multiple patterns separated by spaces or semicolons. The matching is case insensitive. - \sa {QRegularExpression wildcard matching}, QRegularExpression::wildcardToRegularExpression, - entryList(), entryInfoList() + \sa {QRegularExpression#Wildcard matching}{QRegularExpression Wildcard Matching}, + entryList(), entryInfoList() */ bool QDir::match(const QString &filter, const QString &fileName) { diff --git a/src/corelib/io/qprocess.cpp b/src/corelib/io/qprocess.cpp index 890867cd51..e1f4a3a311 100644 --- a/src/corelib/io/qprocess.cpp +++ b/src/corelib/io/qprocess.cpp @@ -112,12 +112,12 @@ QT_BEGIN_NAMESPACE \relates QProcess Disables the - \l {QProcess::start(const QString &, OpenMode)}{QProcess::start()} - overload taking a single string. + \l {QProcess::start(const QString &, QIODevice::OpenMode)} + {QProcess::start}() overload taking a single string. In most cases where it is used, the user intends for the first argument to be treated atomically as per the other overload. - \sa QProcess::start(const QString &command, OpenMode mode) + \sa QProcess::start(const QString &command, QIODevice::OpenMode mode) */ /*! @@ -2557,7 +2557,7 @@ bool QProcess::startDetached(const QString &program, After the \a command string has been split and unquoted, this function behaves like the overload which takes the arguments as a string list. - \sa start(const QString &command, OpenMode mode) + \sa start(const QString &command, QIODevice::OpenMode mode) */ bool QProcess::startDetached(const QString &command) { diff --git a/src/corelib/kernel/qdeadlinetimer.cpp b/src/corelib/kernel/qdeadlinetimer.cpp index 466056d513..6aa886cfe1 100644 --- a/src/corelib/kernel/qdeadlinetimer.cpp +++ b/src/corelib/kernel/qdeadlinetimer.cpp @@ -720,6 +720,11 @@ QDeadlineTimer QDeadlineTimer::addNSecs(QDeadlineTimer dt, qint64 nsecs) Q_DECL_ Returns the time remaining before the deadline. */ +/*! + \fn QPair QDeadlineTimer::_q_data() const + \internal +*/ + // the rest of the functions are in qelapsedtimer_xxx.cpp QT_END_NAMESPACE diff --git a/src/corelib/kernel/qeventdispatcher_cf.mm b/src/corelib/kernel/qeventdispatcher_cf.mm index 8881305b18..b7b379e2c1 100644 --- a/src/corelib/kernel/qeventdispatcher_cf.mm +++ b/src/corelib/kernel/qeventdispatcher_cf.mm @@ -58,7 +58,7 @@ QT_USE_NAMESPACE -/*! +/* During scroll view panning, and possibly other gestures, UIKit will request a switch to UITrackingRunLoopMode via GSEventPushRunLoopMode, which records the new runloop mode and stops the current runloop. diff --git a/src/corelib/kernel/qtimer.cpp b/src/corelib/kernel/qtimer.cpp index 90f29aa630..13f027074a 100644 --- a/src/corelib/kernel/qtimer.cpp +++ b/src/corelib/kernel/qtimer.cpp @@ -571,43 +571,43 @@ void QTimer::singleShot(int msec, Qt::TimerType timerType, const QObject *receiv */ /*! - \fn template QMetaObject::Connection callOnTimeout(Functor functor, Qt::ConnectionType connectionType = Qt::AutoConnection) + \fn template QMetaObject::Connection QTimer::callOnTimeout(Functor slot, Qt::ConnectionType connectionType = Qt::AutoConnection) \since 5.12 \overload - Creates a connection from the timeout() signal to \a functor, and returns a + Creates a connection from the timeout() signal to \a slot, and returns a handle to the connection. This method is provided for convenience. - It's equivalent to calling \c {QObject::connect(timer, &QTimer::timeout, timer, functor, connectionType)}. + It's equivalent to calling \c {QObject::connect(timer, &QTimer::timeout, timer, slot, connectionType)}. \sa QObject::connect(), timeout() */ /*! - \fn template QMetaObject::Connection callOnTimeout(QObject *context, Functor functor, Qt::ConnectionType connectionType = Qt::AutoConnection) + \fn template QMetaObject::Connection QTimer::callOnTimeout(const QObject *context, Functor slot, Qt::ConnectionType connectionType = Qt::AutoConnection) \since 5.12 \overload callOnTimeout() - Creates a connection from the timeout() signal to \a functor to be placed in a specific + Creates a connection from the timeout() signal to \a slot to be placed in a specific event loop of \a context, and returns a handle to the connection. This method is provided for convenience. It's equivalent to calling - \c {QObject::connect(timer, &QTimer::timeout, context, functor, connectionType)}. + \c {QObject::connect(timer, &QTimer::timeout, context, slot, connectionType)}. \sa QObject::connect(), timeout() */ /*! - \fn template QMetaObject::Connection callOnTimeout(QObject *receiver, PointerToMemberFunction method, Qt::ConnectionType connectionType = Qt::AutoConnection) + \fn template QMetaObject::Connection QTimer::callOnTimeout(const QObject *receiver, PointerToMemberFunction slot, Qt::ConnectionType connectionType = Qt::AutoConnection) \since 5.12 \overload callOnTimeout() - Creates a connection from the timeout() signal to the \a method in the \a receiver object. Returns + Creates a connection from the timeout() signal to the \a slot in the \a receiver object. Returns a handle to the connection. This method is provided for convenience. It's equivalent to calling - \c {QObject::connect(timer, &QTimer::timeout, receiver, method, connectionType)}. + \c {QObject::connect(timer, &QTimer::timeout, receiver, slot, connectionType)}. \sa QObject::connect(), timeout() */ diff --git a/src/corelib/tools/qbytearray.cpp b/src/corelib/tools/qbytearray.cpp index 8f2ad8c012..53ae7b9452 100644 --- a/src/corelib/tools/qbytearray.cpp +++ b/src/corelib/tools/qbytearray.cpp @@ -3076,7 +3076,7 @@ bool QByteArray::endsWith(const char *str) const return qstrncmp(d->data() + d->size - len, str, len) == 0; } -/*! +/* Returns true if \a c is an uppercase Latin1 letter. \note The multiplication sign 0xD7 and the sz ligature 0xDF are not treated as uppercase Latin1. @@ -3112,7 +3112,7 @@ bool QByteArray::isUpper() const return true; } -/*! +/* Returns true if \a c is an lowercase Latin1 letter. \note The division sign 0xF7 is not treated as lowercase Latin1, but the small y dieresis 0xFF is. diff --git a/src/corelib/tools/qmap.cpp b/src/corelib/tools/qmap.cpp index d7844f3128..5f7275c5f8 100644 --- a/src/corelib/tools/qmap.cpp +++ b/src/corelib/tools/qmap.cpp @@ -537,7 +537,7 @@ void QMapDataBase::freeData(QMapDataBase *d) \sa operator=() */ -/*! \fn template QMap::QMap(const std::map & other) +/*! \fn template QMap::QMap(const typename std::map & other) Constructs a copy of \a other. diff --git a/src/corelib/tools/qregularexpression.cpp b/src/corelib/tools/qregularexpression.cpp index fec5f620fc..908e7ff0d6 100644 --- a/src/corelib/tools/qregularexpression.cpp +++ b/src/corelib/tools/qregularexpression.cpp @@ -2000,8 +2000,8 @@ QString QRegularExpression::wildcardToRegularExpression(const QString &pattern) \since 5.12 - Returns the expression wrapped between the \c{\A} and \c{\z} anchors to be - used for exact matching. + Returns the \a expression wrapped between the \c{\A} and \c{\z} anchors to + be used for exact matching. \sa {Porting from QRegExp's Exact Matching} */ diff --git a/src/corelib/tools/qshareddata.cpp b/src/corelib/tools/qshareddata.cpp index bc4291e20f..c334f71fa0 100644 --- a/src/corelib/tools/qshareddata.cpp +++ b/src/corelib/tools/qshareddata.cpp @@ -579,6 +579,13 @@ QT_BEGIN_NAMESPACE the shared data object if the reference count became 0. */ +/*! \fn template T *QExplicitlySharedDataPointer::take() + \since 5.12 + + Returns a pointer to the shared object, and resets \e this to be null. + That is, this function sets the \e{d pointer} of \e this to \c nullptr. + */ + /*! \fn template QExplicitlySharedDataPointer::operator bool () const Returns \c true if the \e{d pointer} of \e this is \e not null. */ diff --git a/src/corelib/tools/qstring.cpp b/src/corelib/tools/qstring.cpp index c89635cfdb..fb7fb64223 100644 --- a/src/corelib/tools/qstring.cpp +++ b/src/corelib/tools/qstring.cpp @@ -254,7 +254,7 @@ inline RetType UnrollTailLoop<0>::exec(Number, RetType returnIfExited, Functor1, /*! * \internal * - * Searches for character \a \c in the string \a str and returns a pointer to + * Searches for character \a c in the string \a str and returns a pointer to * it. Unlike strchr() and wcschr() (but like glibc's strchrnul()), if the * character is not found, this function returns a pointer to the end of the * string -- that is, \c{str.end()}. diff --git a/src/corelib/tools/qtimezone.cpp b/src/corelib/tools/qtimezone.cpp index db6be581ec..cbc6b50c98 100644 --- a/src/corelib/tools/qtimezone.cpp +++ b/src/corelib/tools/qtimezone.cpp @@ -217,7 +217,7 @@ Q_GLOBAL_STATIC(QTimeZoneSingleton, global_tz); This class includes data obtained from the CLDR data files under the terms of the Unicode Data Files and Software License. See - \l{Unicode CLDR (Unicode Common Locale Data Repository)} for the details. + \l{Unicode Common Locale Data Repository (CLDR)} for details. \sa QDateTime */ -- cgit v1.2.3