From b2cad63cc1560d1f0dbcd10b79270c6d87712961 Mon Sep 17 00:00:00 2001 From: Martin Smith Date: Wed, 19 Jul 2017 14:20:11 +0200 Subject: [PATCH] doc: Add template text to \fn commands in qglobal.cpp This update corrects many qdoc warnings in qglobal.cpp caused by incomplete \fn commands. It also corrects many undocumented parameter errors caused by clang's requirement that the formal parameter names be the same in both the declaration in the include file and the \fn command. Some formal parameter names were changed in the declarations in the header file. Change-Id: I4cd38f30461c585b97ec11923cdbc81a41fe00b8 Reviewed-by: Martin Smith --- src/corelib/global/qflags.h | 50 +++++++------- src/corelib/global/qglobal.cpp | 119 ++++++++++++++++----------------- 2 files changed, 84 insertions(+), 85 deletions(-) diff --git a/src/corelib/global/qflags.h b/src/corelib/global/qflags.h index c22c22d10a..e9fee5f23e 100644 --- a/src/corelib/global/qflags.h +++ b/src/corelib/global/qflags.h @@ -54,20 +54,20 @@ class QFlag { int i; public: - Q_DECL_CONSTEXPR inline QFlag(int ai) Q_DECL_NOTHROW : i(ai) {} + Q_DECL_CONSTEXPR inline QFlag(int value) Q_DECL_NOTHROW : i(value) {} Q_DECL_CONSTEXPR inline operator int() const Q_DECL_NOTHROW { return i; } #if !defined(Q_CC_MSVC) // Microsoft Visual Studio has buggy behavior when it comes to // unsigned enums: even if the enum is unsigned, the enum tags are // always signed -# if !defined(__LP64__) && !defined(Q_QDOC) - Q_DECL_CONSTEXPR inline QFlag(long ai) Q_DECL_NOTHROW : i(int(ai)) {} - Q_DECL_CONSTEXPR inline QFlag(ulong ai) Q_DECL_NOTHROW : i(int(long(ai))) {} +# if !defined(__LP64__) && !defined(Q_CLANG_QDOC) + Q_DECL_CONSTEXPR inline QFlag(long value) Q_DECL_NOTHROW : i(int(value)) {} + Q_DECL_CONSTEXPR inline QFlag(ulong value) Q_DECL_NOTHROW : i(int(long(value))) {} # endif - Q_DECL_CONSTEXPR inline QFlag(uint ai) Q_DECL_NOTHROW : i(int(ai)) {} - Q_DECL_CONSTEXPR inline QFlag(short ai) Q_DECL_NOTHROW : i(int(ai)) {} - Q_DECL_CONSTEXPR inline QFlag(ushort ai) Q_DECL_NOTHROW : i(int(uint(ai))) {} + Q_DECL_CONSTEXPR inline QFlag(uint value) Q_DECL_NOTHROW : i(int(value)) {} + Q_DECL_CONSTEXPR inline QFlag(short value) Q_DECL_NOTHROW : i(int(value)) {} + Q_DECL_CONSTEXPR inline QFlag(ushort value) Q_DECL_NOTHROW : i(int(uint(value))) {} Q_DECL_CONSTEXPR inline operator uint() const Q_DECL_NOTHROW { return uint(i); } #endif }; @@ -82,7 +82,7 @@ public: }; Q_DECLARE_TYPEINFO(QIncompatibleFlag, Q_PRIMITIVE_TYPE); -Q_DECL_CONSTEXPR inline QIncompatibleFlag::QIncompatibleFlag(int ai) Q_DECL_NOTHROW : i(ai) {} +Q_DECL_CONSTEXPR inline QIncompatibleFlag::QIncompatibleFlag(int value) Q_DECL_NOTHROW : i(value) {} #ifndef Q_NO_TYPESAFE_FLAGS @@ -100,7 +100,7 @@ class QFlags template friend QDataStream &operator>>(QDataStream &, QFlags &); template friend QDataStream &operator<<(QDataStream &, QFlags); public: -#if defined(Q_CC_MSVC) || defined(Q_QDOC) +#if defined(Q_CC_MSVC) || defined(Q_CLANG_QDOC) // see above for MSVC // the definition below is too complex for qdoc typedef int Int; @@ -113,13 +113,13 @@ public: #endif typedef Enum enum_type; // compiler-generated copy/move ctor/assignment operators are fine! -#ifdef Q_QDOC +#ifdef Q_CLANG_QDOC Q_DECL_CONSTEXPR inline QFlags(const QFlags &other); Q_DECL_CONSTEXPR inline QFlags &operator=(const QFlags &other); #endif - Q_DECL_CONSTEXPR inline QFlags(Enum f) Q_DECL_NOTHROW : i(Int(f)) {} - Q_DECL_CONSTEXPR inline QFlags(Zero = nullptr) Q_DECL_NOTHROW : i(0) {} - Q_DECL_CONSTEXPR inline QFlags(QFlag f) Q_DECL_NOTHROW : i(f) {} + Q_DECL_CONSTEXPR inline QFlags(Enum flags) Q_DECL_NOTHROW : i(Int(flags)) {} + Q_DECL_CONSTEXPR inline QFlags(Zero = Q_NULLPTR) Q_DECL_NOTHROW : i(0) {} + Q_DECL_CONSTEXPR inline QFlags(QFlag flag) Q_DECL_NOTHROW : i(flag) {} #ifdef Q_COMPILER_INITIALIZER_LISTS Q_DECL_CONSTEXPR inline QFlags(std::initializer_list flags) Q_DECL_NOTHROW @@ -129,28 +129,28 @@ public: Q_DECL_RELAXED_CONSTEXPR inline QFlags &operator&=(int mask) Q_DECL_NOTHROW { i &= mask; return *this; } Q_DECL_RELAXED_CONSTEXPR inline QFlags &operator&=(uint mask) Q_DECL_NOTHROW { i &= mask; return *this; } Q_DECL_RELAXED_CONSTEXPR inline QFlags &operator&=(Enum mask) Q_DECL_NOTHROW { i &= Int(mask); return *this; } - Q_DECL_RELAXED_CONSTEXPR inline QFlags &operator|=(QFlags f) Q_DECL_NOTHROW { i |= f.i; return *this; } - Q_DECL_RELAXED_CONSTEXPR inline QFlags &operator|=(Enum f) Q_DECL_NOTHROW { i |= Int(f); return *this; } - Q_DECL_RELAXED_CONSTEXPR inline QFlags &operator^=(QFlags f) Q_DECL_NOTHROW { i ^= f.i; return *this; } - Q_DECL_RELAXED_CONSTEXPR inline QFlags &operator^=(Enum f) Q_DECL_NOTHROW { i ^= Int(f); return *this; } + Q_DECL_RELAXED_CONSTEXPR inline QFlags &operator|=(QFlags other) Q_DECL_NOTHROW { i |= other.i; return *this; } + Q_DECL_RELAXED_CONSTEXPR inline QFlags &operator|=(Enum other) Q_DECL_NOTHROW { i |= Int(other); return *this; } + Q_DECL_RELAXED_CONSTEXPR inline QFlags &operator^=(QFlags other) Q_DECL_NOTHROW { i ^= other.i; return *this; } + Q_DECL_RELAXED_CONSTEXPR inline QFlags &operator^=(Enum other) Q_DECL_NOTHROW { i ^= Int(other); return *this; } Q_DECL_CONSTEXPR inline operator Int() const Q_DECL_NOTHROW { return i; } - Q_DECL_CONSTEXPR inline QFlags operator|(QFlags f) const Q_DECL_NOTHROW { return QFlags(QFlag(i | f.i)); } - Q_DECL_CONSTEXPR inline QFlags operator|(Enum f) const Q_DECL_NOTHROW { return QFlags(QFlag(i | Int(f))); } - Q_DECL_CONSTEXPR inline QFlags operator^(QFlags f) const Q_DECL_NOTHROW { return QFlags(QFlag(i ^ f.i)); } - Q_DECL_CONSTEXPR inline QFlags operator^(Enum f) const Q_DECL_NOTHROW { return QFlags(QFlag(i ^ Int(f))); } + Q_DECL_CONSTEXPR inline QFlags operator|(QFlags other) const Q_DECL_NOTHROW { return QFlags(QFlag(i | other.i)); } + Q_DECL_CONSTEXPR inline QFlags operator|(Enum other) const Q_DECL_NOTHROW { return QFlags(QFlag(i | Int(other))); } + Q_DECL_CONSTEXPR inline QFlags operator^(QFlags other) const Q_DECL_NOTHROW { return QFlags(QFlag(i ^ other.i)); } + Q_DECL_CONSTEXPR inline QFlags operator^(Enum other) const Q_DECL_NOTHROW { return QFlags(QFlag(i ^ Int(other))); } Q_DECL_CONSTEXPR inline QFlags operator&(int mask) const Q_DECL_NOTHROW { return QFlags(QFlag(i & mask)); } Q_DECL_CONSTEXPR inline QFlags operator&(uint mask) const Q_DECL_NOTHROW { return QFlags(QFlag(i & mask)); } - Q_DECL_CONSTEXPR inline QFlags operator&(Enum f) const Q_DECL_NOTHROW { return QFlags(QFlag(i & Int(f))); } + Q_DECL_CONSTEXPR inline QFlags operator&(Enum other) const Q_DECL_NOTHROW { return QFlags(QFlag(i & Int(other))); } Q_DECL_CONSTEXPR inline QFlags operator~() const Q_DECL_NOTHROW { return QFlags(QFlag(~i)); } Q_DECL_CONSTEXPR inline bool operator!() const Q_DECL_NOTHROW { return !i; } - Q_DECL_CONSTEXPR inline bool testFlag(Enum f) const Q_DECL_NOTHROW { return (i & Int(f)) == Int(f) && (Int(f) != 0 || i == Int(f) ); } - Q_DECL_RELAXED_CONSTEXPR inline QFlags &setFlag(Enum f, bool on = true) Q_DECL_NOTHROW + Q_DECL_CONSTEXPR inline bool testFlag(Enum flag) const Q_DECL_NOTHROW { return (i & Int(flag)) == Int(flag) && (Int(flag) != 0 || i == Int(flag) ); } + Q_DECL_RELAXED_CONSTEXPR inline QFlags &setFlag(Enum flag, bool on = true) Q_DECL_NOTHROW { - return on ? (*this |= f) : (*this &= ~Int(f)); + return on ? (*this |= flag) : (*this &= ~Int(flag)); } private: diff --git a/src/corelib/global/qglobal.cpp b/src/corelib/global/qglobal.cpp index e60002d405..c3b074c59f 100644 --- a/src/corelib/global/qglobal.cpp +++ b/src/corelib/global/qglobal.cpp @@ -182,28 +182,28 @@ Q_STATIC_ASSERT((std::is_same::value)); /*! \fn QFlag::QFlag(int value) - Constructs a QFlag object that stores the given \a value. + Constructs a QFlag object that stores the \a value. */ /*! \fn QFlag::QFlag(uint value) \since 5.3 - Constructs a QFlag object that stores the given \a value. + Constructs a QFlag object that stores the \a value. */ /*! \fn QFlag::QFlag(short value) \since 5.3 - Constructs a QFlag object that stores the given \a value. + Constructs a QFlag object that stores the \a value. */ /*! \fn QFlag::QFlag(ushort value) \since 5.3 - Constructs a QFlag object that stores the given \a value. + Constructs a QFlag object that stores the \a value. */ /*! @@ -298,29 +298,28 @@ Q_STATIC_ASSERT((std::is_same::value)); */ /*! - \fn QFlags::QFlags(const QFlags &other) + \fn template QFlags::QFlags(const QFlags &other) Constructs a copy of \a other. */ /*! - \fn QFlags::QFlags(Enum flag) + \fn template QFlags::QFlags(Enum flags) - Constructs a QFlags object storing the given \a flag. + Constructs a QFlags object storing the \a flags. */ /*! - \fn QFlags::QFlags(Zero zero) + \fn template QFlags::QFlags(Zero) - Constructs a QFlags object with no flags set. \a zero must be a + Constructs a QFlags object with no flags set. The parameter must be a literal 0 value. */ /*! - \fn QFlags::QFlags(QFlag value) + \fn template QFlags::QFlags(QFlag flag) - Constructs a QFlags object initialized with the given integer \a - value. + Constructs a QFlags object initialized with the integer \a flag. The QFlag type is a helper type. By using it here instead of \c int, we effectively ensure that arbitrary enum values cannot be @@ -329,7 +328,7 @@ Q_STATIC_ASSERT((std::is_same::value)); */ /*! - \fn QFlags::QFlags(std::initializer_list flags) + \fn template QFlags::QFlags(std::initializer_list flags) \since 5.4 Constructs a QFlags object initialized with all \a flags @@ -339,14 +338,14 @@ Q_STATIC_ASSERT((std::is_same::value)); */ /*! - \fn QFlags &QFlags::operator=(const QFlags &other) + \fn template QFlags &QFlags::operator=(const QFlags &other) Assigns \a other to this object and returns a reference to this object. */ /*! - \fn QFlags &QFlags::operator&=(int mask) + \fn template QFlags &QFlags::operator&=(int mask) Performs a bitwise AND operation with \a mask and stores the result in this QFlags object. Returns a reference to this object. @@ -355,19 +354,19 @@ Q_STATIC_ASSERT((std::is_same::value)); */ /*! - \fn QFlags &QFlags::operator&=(uint mask) + \fn template QFlags &QFlags::operator&=(uint mask) \overload */ /*! - \fn QFlags &QFlags::operator&=(Enum mask) + \fn template QFlags &QFlags::operator&=(Enum mask) \overload */ /*! - \fn QFlags &QFlags::operator|=(QFlags other) + \fn template QFlags &QFlags::operator|=(QFlags other) Performs a bitwise OR operation with \a other and stores the result in this QFlags object. Returns a reference to this object. @@ -376,13 +375,13 @@ Q_STATIC_ASSERT((std::is_same::value)); */ /*! - \fn QFlags &QFlags::operator|=(Enum other) + \fn template QFlags &QFlags::operator|=(Enum other) \overload */ /*! - \fn QFlags &QFlags::operator^=(QFlags other) + \fn template QFlags &QFlags::operator^=(QFlags other) Performs a bitwise XOR operation with \a other and stores the result in this QFlags object. Returns a reference to this object. @@ -391,13 +390,13 @@ Q_STATIC_ASSERT((std::is_same::value)); */ /*! - \fn QFlags &QFlags::operator^=(Enum other) + \fn template QFlags &QFlags::operator^=(Enum other) \overload */ /*! - \fn QFlags::operator Int() const + \fn template QFlags::operator Int() const Returns the value stored in the QFlags object as an integer. @@ -405,7 +404,7 @@ Q_STATIC_ASSERT((std::is_same::value)); */ /*! - \fn QFlags QFlags::operator|(QFlags other) const + \fn template QFlags QFlags::operator|(QFlags other) const Returns a QFlags object containing the result of the bitwise OR operation on this object and \a other. @@ -414,13 +413,13 @@ Q_STATIC_ASSERT((std::is_same::value)); */ /*! - \fn QFlags QFlags::operator|(Enum other) const + \fn template QFlags QFlags::operator|(Enum other) const \overload */ /*! - \fn QFlags QFlags::operator^(QFlags other) const + \fn template QFlags QFlags::operator^(QFlags other) const Returns a QFlags object containing the result of the bitwise XOR operation on this object and \a other. @@ -429,13 +428,13 @@ Q_STATIC_ASSERT((std::is_same::value)); */ /*! - \fn QFlags QFlags::operator^(Enum other) const + \fn template QFlags QFlags::operator^(Enum other) const \overload */ /*! - \fn QFlags QFlags::operator&(int mask) const + \fn template QFlags QFlags::operator&(int mask) const Returns a QFlags object containing the result of the bitwise AND operation on this object and \a mask. @@ -444,19 +443,19 @@ Q_STATIC_ASSERT((std::is_same::value)); */ /*! - \fn QFlags QFlags::operator&(uint mask) const + \fn template QFlags QFlags::operator&(uint mask) const \overload */ /*! - \fn QFlags QFlags::operator&(Enum mask) const + \fn template QFlags QFlags::operator&(Enum mask) const \overload */ /*! - \fn QFlags QFlags::operator~() const + \fn template QFlags QFlags::operator~() const Returns a QFlags object that contains the bitwise negation of this object. @@ -465,24 +464,24 @@ Q_STATIC_ASSERT((std::is_same::value)); */ /*! - \fn bool QFlags::operator!() const + \fn template bool QFlags::operator!() const Returns \c true if no flag is set (i.e., if the value stored by the QFlags object is 0); otherwise returns \c false. */ /*! - \fn bool QFlags::testFlag(Enum flag) const + \fn template bool QFlags::testFlag(Enum flag) const \since 4.2 - Returns \c true if the \a flag is set, otherwise \c false. + Returns \c true if the flag \a flag is set, otherwise \c false. */ /*! - \fn QFlags QFlags::setFlag(Enum flag, bool on) + \fn template QFlags QFlags::setFlag(Enum flag, bool on) \since 5.7 - Sets the indicated \a flag if \a on is \c true or unsets it if + Sets the flag \a flag if \a on is \c true or unsets it if \a on is \c false. Returns a reference to this object. */ @@ -920,11 +919,11 @@ Q_STATIC_ASSERT((std::is_same::value)); \sa quint64, qlonglong */ -/*! \fn T qAbs(const T &value) +/*! \fn template T qAbs(const T &t) \relates - Compares \a value to the 0 of type T and returns the absolute - value. Thus if T is \e {double}, then \a value is compared to + Compares \a t to the 0 of type T and returns the absolute + value. Thus if T is \e {double}, then \a t is compared to \e{(double) 0}. Example: @@ -932,50 +931,50 @@ Q_STATIC_ASSERT((std::is_same::value)); \snippet code/src_corelib_global_qglobal.cpp 10 */ -/*! \fn int qRound(double value) +/*! \fn int qRound(double d) \relates - Rounds \a value to the nearest integer. + Rounds \a d to the nearest integer. Example: \snippet code/src_corelib_global_qglobal.cpp 11A */ -/*! \fn int qRound(float value) +/*! \fn int qRound(float d) \relates - Rounds \a value to the nearest integer. + Rounds \a d to the nearest integer. Example: \snippet code/src_corelib_global_qglobal.cpp 11B */ -/*! \fn qint64 qRound64(double value) +/*! \fn qint64 qRound64(double d) \relates - Rounds \a value to the nearest 64-bit integer. + Rounds \a d to the nearest 64-bit integer. Example: \snippet code/src_corelib_global_qglobal.cpp 12A */ -/*! \fn qint64 qRound64(float value) +/*! \fn qint64 qRound64(float d) \relates - Rounds \a value to the nearest 64-bit integer. + Rounds \a d to the nearest 64-bit integer. Example: \snippet code/src_corelib_global_qglobal.cpp 12B */ -/*! \fn const T &qMin(const T &value1, const T &value2) +/*! \fn template const T &qMin(const T &a, const T &b) \relates - Returns the minimum of \a value1 and \a value2. + Returns the minimum of \a a and \a b. Example: @@ -984,10 +983,10 @@ Q_STATIC_ASSERT((std::is_same::value)); \sa qMax(), qBound() */ -/*! \fn const T &qMax(const T &value1, const T &value2) +/*! \fn template const T &qMax(const T &a, const T &b) \relates - Returns the maximum of \a value1 and \a value2. + Returns the maximum of \a a and \a b. Example: @@ -996,11 +995,11 @@ Q_STATIC_ASSERT((std::is_same::value)); \sa qMin(), qBound() */ -/*! \fn const T &qBound(const T &min, const T &value, const T &max) +/*! \fn template const T &qBound(const T &min, const T &val, const T &max) \relates - Returns \a value bounded by \a min and \a max. This is equivalent - to qMax(\a min, qMin(\a value, \a max)). + Returns \a val bounded by \a min and \a max. This is equivalent + to qMax(\a min, qMin(\a val, \a max)). Example: @@ -1009,7 +1008,7 @@ Q_STATIC_ASSERT((std::is_same::value)); \sa qMin(), qMax() */ -/*! \fn auto qOverload(T functionPointer) +/*! \fn template auto qOverload(T functionPointer) \relates \since 5.7 @@ -1031,7 +1030,7 @@ Q_STATIC_ASSERT((std::is_same::value)); and Functor-Based Connections} */ -/*! \fn auto qConstOverload(T memberFunctionPointer) +/*! \fn template auto qConstOverload(T memberFunctionPointer) \relates \since 5.7 @@ -1043,7 +1042,7 @@ Q_STATIC_ASSERT((std::is_same::value)); and Functor-Based Connections} */ -/*! \fn auto qNonConstOverload(T memberFunctionPointer) +/*! \fn template auto qNonConstOverload(T memberFunctionPointer) \relates \since 5.7 @@ -3105,10 +3104,10 @@ QByteArray QSysInfo::bootUniqueId() */ /*! - \fn T *q_check_ptr(T *pointer) + \fn template T *q_check_ptr(T *p) \relates - Uses Q_CHECK_PTR on \a pointer, then returns \a pointer. + Uses Q_CHECK_PTR on \a p, then returns \a p. This can be used as an inline version of Q_CHECK_PTR. */ @@ -3603,7 +3602,7 @@ bool qunsetenv(const char *varName) */ /*! - \fn qAsConst(T &t) + \fn template qAsConst(T &t) \relates \since 5.7 @@ -3655,7 +3654,7 @@ bool qunsetenv(const char *varName) */ /*! - \fn qAsConst(const T &&t) + \fn template qAsConst(const T &&t) \relates \since 5.7 \overload