From b2cad63cc1560d1f0dbcd10b79270c6d87712961 Mon Sep 17 00:00:00 2001 From: Martin Smith Date: Wed, 19 Jul 2017 14:20:11 +0200 Subject: 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/qglobal.cpp | 119 ++++++++++++++++++++--------------------- 1 file changed, 59 insertions(+), 60 deletions(-) (limited to 'src/corelib/global/qglobal.cpp') 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 -- cgit v1.2.3