From 95aec76e3169d37d4d6ba908d8a96ce578cb45e2 Mon Sep 17 00:00:00 2001 From: Topi Reinio Date: Fri, 14 Feb 2020 17:45:45 +0100 Subject: [PATCH] Doc: Fix documentation warnings for Qt Core - QCborError: Classes cannot relate to header files; use \inheaderfile instead and link to the class from header file documentation. - QRecursiveMutex: QDoc doesn't allow shared documentation comments for duplicating \fn docs between the base and deriving classes. Remove the sharing, the function documentation is available under 'All Members' doc for QRecursiveMutex. - QMultiMap: unite() and one overload of insert() were not recognized because their definitions in the same header file interfered with QDoc - use Q_CLANG_QDOC macro to comment them out, and tag \fn comments to ensure that the function documentation is matched. Change-Id: Ic96869904a72d92453e4ffa6901000147571969b Reviewed-by: Paul Wicking --- src/corelib/global/qnamespace.qdoc | 2 ++ src/corelib/kernel/qmetatype.cpp | 2 +- src/corelib/serialization/qcborcommon.cpp | 4 +++- src/corelib/text/qstringview.cpp | 6 +++--- src/corelib/thread/qmutex.cpp | 6 ------ src/corelib/time/qdatetime.cpp | 8 +++----- src/corelib/tools/qmap.cpp | 5 +++-- src/corelib/tools/qmap.h | 6 +++++- src/corelib/tools/qvarlengtharray.qdoc | 2 +- 9 files changed, 21 insertions(+), 20 deletions(-) diff --git a/src/corelib/global/qnamespace.qdoc b/src/corelib/global/qnamespace.qdoc index 708ecb11ab..cfa86888b2 100644 --- a/src/corelib/global/qnamespace.qdoc +++ b/src/corelib/global/qnamespace.qdoc @@ -3339,6 +3339,8 @@ This is a dummy type, designed to help users transition from certain deprecated APIs to their replacement APIs. + \omitvalue ReturnByValue + \sa QCursor::bitmap() \sa QCursor::mask() \sa QLabel::picture() diff --git a/src/corelib/kernel/qmetatype.cpp b/src/corelib/kernel/qmetatype.cpp index a2b7fec5cd..71eec11e01 100644 --- a/src/corelib/kernel/qmetatype.cpp +++ b/src/corelib/kernel/qmetatype.cpp @@ -523,7 +523,7 @@ struct DefinedTypesFilter { as the QMetaType \a b, otherwise returns \c false. */ -/*! \fn bool operator!=(const QMetaType &a, const QMetaType &c) +/*! \fn bool operator!=(const QMetaType &a, const QMetaType &b) \since 5.15 \relates QMetaType \overload diff --git a/src/corelib/serialization/qcborcommon.cpp b/src/corelib/serialization/qcborcommon.cpp index 37fb198744..5fc47fa399 100644 --- a/src/corelib/serialization/qcborcommon.cpp +++ b/src/corelib/serialization/qcborcommon.cpp @@ -54,6 +54,8 @@ QT_BEGIN_NAMESPACE \brief The header contains definitions common to both the streaming classes (QCborStreamReader and QCborStreamWriter) and to QCborValue. + + \sa QCborError */ /*! @@ -203,7 +205,7 @@ QDataStream &operator>>(QDataStream &ds, QCborSimpleType &st) /*! \class QCborError \inmodule QtCore - \relates + \inheaderfile \reentrant \since 5.12 diff --git a/src/corelib/text/qstringview.cpp b/src/corelib/text/qstringview.cpp index c4ddb06ea4..08dade7e68 100644 --- a/src/corelib/text/qstringview.cpp +++ b/src/corelib/text/qstringview.cpp @@ -528,9 +528,9 @@ QT_BEGIN_NAMESPACE */ /*! - \fn QString QStringView::arg(Args &&...args) const - \fn QString QLatin1String::arg(Args &&...args) const - \fn QString QString::arg(Args &&...args) const + \fn template QString QStringView::arg(Args &&...args) const + \fn template QString QLatin1String::arg(Args &&...args) const + \fn template QString QString::arg(Args &&...args) const \since 5.14 Replaces occurrences of \c{%N} in this string with the corresponding diff --git a/src/corelib/thread/qmutex.cpp b/src/corelib/thread/qmutex.cpp index 0508932d68..9bfd50f2d9 100644 --- a/src/corelib/thread/qmutex.cpp +++ b/src/corelib/thread/qmutex.cpp @@ -212,7 +212,6 @@ QMutex::~QMutex() } /*! \fn void QMutex::lock() - \fn QRecursiveMutex::lock() Locks the mutex. If another thread has locked the mutex then this call will block until that thread has unlocked it. @@ -237,7 +236,6 @@ void QMutex::lock() QT_MUTEX_LOCK_NOEXCEPT } /*! \fn bool QMutex::tryLock(int timeout) - \fn bool QRecursiveMutex::tryLock(int timeout) Attempts to lock the mutex. This function returns \c true if the lock was obtained; otherwise it returns \c false. If another thread has @@ -272,7 +270,6 @@ bool QMutex::tryLock(int timeout) QT_MUTEX_LOCK_NOEXCEPT } /*! \fn bool QMutex::try_lock() - \fn bool QRecursiveMutex::try_lock() \since 5.8 Attempts to lock the mutex. This function returns \c true if the lock @@ -286,7 +283,6 @@ bool QMutex::tryLock(int timeout) QT_MUTEX_LOCK_NOEXCEPT */ /*! \fn template bool QMutex::try_lock_for(std::chrono::duration duration) - \fn template bool QRecursiveMutex::try_lock_for(std::chrono::duration duration) \since 5.8 Attempts to lock the mutex. This function returns \c true if the lock @@ -311,7 +307,6 @@ bool QMutex::tryLock(int timeout) QT_MUTEX_LOCK_NOEXCEPT */ /*! \fn template bool QMutex::try_lock_until(std::chrono::time_point timePoint) - \fn template bool QRecursiveMutex::try_lock_until(std::chrono::time_point timePoint) \since 5.8 Attempts to lock the mutex. This function returns \c true if the lock @@ -336,7 +331,6 @@ bool QMutex::tryLock(int timeout) QT_MUTEX_LOCK_NOEXCEPT */ /*! \fn void QMutex::unlock() - \fn void QRecursiveMutex::unlock() Unlocks the mutex. Attempting to unlock a mutex in a different thread to the one that locked it results in an error. Unlocking a diff --git a/src/corelib/time/qdatetime.cpp b/src/corelib/time/qdatetime.cpp index 45c6ecbf23..86c08058fc 100644 --- a/src/corelib/time/qdatetime.cpp +++ b/src/corelib/time/qdatetime.cpp @@ -1127,9 +1127,7 @@ static QString toStringIsoDate(QDate date) \overload Returns the date as a string. The \a format parameter determines the format - of the string. If \a cal is supplied, it determines the calendar used to - represent the date; it defaults to Gregorian and only affects the - locale-specific formats. + of the string. If the \a format is Qt::TextDate, the string is formatted in the default way. The day and month names will be localized names using the system @@ -1236,7 +1234,7 @@ QT_WARNING_POP \fn QString QDate::toString(QStringView format, QCalendar cal) const Returns the date as a string. The \a format parameter determines the format - of the result string. If \cal is supplied, it determines the calendar used + of the result string. If \a cal is supplied, it determines the calendar used to represent the date; it defaults to Gregorian. These expressions may be used: @@ -4437,7 +4435,7 @@ QT_WARNING_POP \fn QString QDateTime::toString(QStringView format, QCalendar cal) const Returns the datetime as a string. The \a format parameter determines the - format of the result string. If \cal is supplied, it determines the calendar + format of the result string. If \a cal is supplied, it determines the calendar used to represent the date; it defaults to Gregorian. See QTime::toString() and QDate::toString() for the supported specifiers for time and date, respectively. diff --git a/src/corelib/tools/qmap.cpp b/src/corelib/tools/qmap.cpp index 9b9c67e42b..6d2b8f7a3e 100644 --- a/src/corelib/tools/qmap.cpp +++ b/src/corelib/tools/qmap.cpp @@ -1999,7 +1999,7 @@ void QMapDataBase::freeData(QMapDataBase *d) \sa replace() */ -/*! \fn template typename QMultiMap::iterator QMultiMap::insert(typename QMultiMap::const_iterator pos, const Key &key, const T &value) +/*! \fn [qmultimap-insert-pos] template typename QMultiMap::iterator QMultiMap::insert(typename QMultiMap::const_iterator pos, const Key &key, const T &value) \since 5.1 Inserts a new item with the key \a key and value \a value and with hint \a pos @@ -2128,7 +2128,8 @@ void QMapDataBase::freeData(QMapDataBase *d) once in the returned list. */ -/*! \fn template QMultiMap &QMultiMap::unite(const QMultiMap &other) +/*! + \fn [qmultimap-unite] template QMultiMap &QMultiMap::unite(const QMultiMap &other) Inserts all the items in the \a other map into this map. If a key is common to both maps, the resulting map will contain the diff --git a/src/corelib/tools/qmap.h b/src/corelib/tools/qmap.h index 2abdc5e60e..427a4ad5a0 100644 --- a/src/corelib/tools/qmap.h +++ b/src/corelib/tools/qmap.h @@ -1115,9 +1115,11 @@ public: inline typename QMap::iterator replace(const Key &key, const T &value) { return QMap::insert(key, value); } typename QMap::iterator insert(const Key &key, const T &value); + //! [qmultimap-insert-pos] typename QMap::iterator insert(typename QMap::const_iterator pos, - const Key &keyi, const T &value); + const Key &key, const T &value); + //! [qmultimap-unite] QMultiMap &unite(const QMultiMap &other); inline QMultiMap &operator+=(const QMultiMap &other) { return unite(other); } @@ -1222,6 +1224,7 @@ Q_INLINE_TEMPLATE typename QMap::iterator QMultiMap::insert(cons return typename QMap::iterator(z); } +#ifndef Q_CLANG_QDOC template typename QMap::iterator QMultiMap::insert(typename QMap::const_iterator pos, const Key &akey, const T &avalue) @@ -1287,6 +1290,7 @@ Q_INLINE_TEMPLATE QMultiMap &QMultiMap::unite(const QMultiMap Q_INLINE_TEMPLATE bool QMultiMap::contains(const Key &key, const T &value) const diff --git a/src/corelib/tools/qvarlengtharray.qdoc b/src/corelib/tools/qvarlengtharray.qdoc index e5ba47b8ef..3dab41dd22 100644 --- a/src/corelib/tools/qvarlengtharray.qdoc +++ b/src/corelib/tools/qvarlengtharray.qdoc @@ -904,7 +904,7 @@ */ /*! - template uint qHash(const QVarLengthArray &key, uint seed = 0) + \fn template uint qHash(const QVarLengthArray &key, uint seed = 0) \relates QVarLengthArray \since 5.14