AuroraMiddleware/qt5base-lts
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

doc: Add template text to \fn commands in qglobal.cpp

Browse Source 
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 <martin.smith@qt.io>
This commit is contained in:
Martin Smith 2017-07-19 14:20:11 +02:00
parent efdcc88462
commit b2cad63cc1
2 changed files with 84 additions and 85 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

50
src/corelib/global/qflags.h
View File

@ -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 <typename E> friend QDataStream &operator>>(QDataStream &, QFlags<E> &);
template <typename E> friend QDataStream &operator<<(QDataStream &, QFlags<E>);
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<Enum> 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:

119
src/corelib/global/qglobal.cpp
View File

@ -182,28 +182,28 @@ Q_STATIC_ASSERT((std::is_same<qssize_t, qptrdiff>::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<qssize_t, qptrdiff>::value));
*/
/*!
\fn QFlags::QFlags(const QFlags &other)
\fn template<typename Enum> QFlags<Enum>::QFlags(const QFlags &other)
Constructs a copy of \a other.
*/
/*!
\fn QFlags::QFlags(Enum flag)
\fn template <typename Enum> QFlags<Enum>::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 <typename Enum> QFlags<Enum>::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 <typename Enum> QFlags<Enum>::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<qssize_t, qptrdiff>::value));
*/
/*!
\fn QFlags::QFlags(std::initializer_list<Enum> flags)
\fn template <typename Enum> QFlags<Enum>::QFlags(std::initializer_list<Enum> flags)
\since 5.4
Constructs a QFlags object initialized with all \a flags
@ -339,14 +338,14 @@ Q_STATIC_ASSERT((std::is_same<qssize_t, qptrdiff>::value));
*/
/*!
\fn QFlags &QFlags::operator=(const QFlags &other)
\fn template <typename Enum> QFlags &QFlags<Enum>::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 <typename Enum> QFlags &QFlags<Enum>::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<qssize_t, qptrdiff>::value));
*/
/*!
\fn QFlags &QFlags::operator&=(uint mask)
\fn template <typename Enum> QFlags &QFlags<Enum>::operator&=(uint mask)
\overload
*/
/*!
\fn QFlags &QFlags::operator&=(Enum mask)
\fn template <typename Enum> QFlags &QFlags<Enum>::operator&=(Enum mask)
\overload
*/
/*!
\fn QFlags &QFlags::operator|=(QFlags other)
\fn template <typename Enum> QFlags &QFlags<Enum>::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<qssize_t, qptrdiff>::value));
*/
/*!
\fn QFlags &QFlags::operator|=(Enum other)
\fn template <typename Enum> QFlags &QFlags<Enum>::operator|=(Enum other)
\overload
*/
/*!
\fn QFlags &QFlags::operator^=(QFlags other)
\fn template <typename Enum> QFlags &QFlags<Enum>::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<qssize_t, qptrdiff>::value));
*/
/*!
\fn QFlags &QFlags::operator^=(Enum other)
\fn template <typename Enum> QFlags &QFlags<Enum>::operator^=(Enum other)
\overload
*/
/*!
\fn QFlags::operator Int() const
\fn template <typename Enum> QFlags<Enum>::operator Int() const
Returns the value stored in the QFlags object as an integer.
@ -405,7 +404,7 @@ Q_STATIC_ASSERT((std::is_same<qssize_t, qptrdiff>::value));
*/
/*!
\fn QFlags QFlags::operator|(QFlags other) const
\fn template <typename Enum> QFlags QFlags<Enum>::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<qssize_t, qptrdiff>::value));
*/
/*!
\fn QFlags QFlags::operator|(Enum other) const
\fn template <typename Enum> QFlags QFlags<Enum>::operator|(Enum other) const
\overload
*/
/*!
\fn QFlags QFlags::operator^(QFlags other) const
\fn template <typename Enum> QFlags QFlags<Enum>::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<qssize_t, qptrdiff>::value));
*/
/*!
\fn QFlags QFlags::operator^(Enum other) const
\fn template <typename Enum> QFlags QFlags<Enum>::operator^(Enum other) const
\overload
*/
/*!
\fn QFlags QFlags::operator&(int mask) const
\fn template <typename Enum> QFlags QFlags<Enum>::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<qssize_t, qptrdiff>::value));
*/
/*!
\fn QFlags QFlags::operator&(uint mask) const
\fn template <typename Enum> QFlags QFlags<Enum>::operator&(uint mask) const
\overload
*/
/*!
\fn QFlags QFlags::operator&(Enum mask) const
\fn template <typename Enum> QFlags QFlags<Enum>::operator&(Enum mask) const
\overload
*/
/*!
\fn QFlags QFlags::operator~() const
\fn template <typename Enum> QFlags QFlags<Enum>::operator~() const
Returns a QFlags object that contains the bitwise negation of
this object.
@ -465,24 +464,24 @@ Q_STATIC_ASSERT((std::is_same<qssize_t, qptrdiff>::value));
*/
/*!
\fn bool QFlags::operator!() const
\fn template <typename Enum> bool QFlags<Enum>::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 <typename Enum> bool QFlags<Enum>::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 <typename Enum> QFlags QFlags<Enum>::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<qssize_t, qptrdiff>::value));
\sa quint64, qlonglong
*/
/*! \fn T qAbs(const T &value)
/*! \fn template <typename T> T qAbs(const T &t)
\relates <QtGlobal>
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<qssize_t, qptrdiff>::value));
\snippet code/src_corelib_global_qglobal.cpp 10
*/
/*! \fn int qRound(double value)
/*! \fn int qRound(double d)
\relates <QtGlobal>
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 <QtGlobal>
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 <QtGlobal>
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 <QtGlobal>
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 <typename T> const T &qMin(const T &a, const T &b)
\relates <QtGlobal>
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<qssize_t, qptrdiff>::value));
\sa qMax(), qBound()
*/
/*! \fn const T &qMax(const T &value1, const T &value2)
/*! \fn template <typename T> const T &qMax(const T &a, const T &b)
\relates <QtGlobal>
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<qssize_t, qptrdiff>::value));
\sa qMin(), qBound()
*/
/*! \fn const T &qBound(const T &min, const T &value, const T &max)
/*! \fn template <typename T> const T &qBound(const T &min, const T &val, const T &max)
\relates <QtGlobal>
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<qssize_t, qptrdiff>::value));
\sa qMin(), qMax()
*/
/*! \fn auto qOverload(T functionPointer)
/*! \fn template <typename T> auto qOverload(T functionPointer)
\relates <QtGlobal>
\since 5.7
@ -1031,7 +1030,7 @@ Q_STATIC_ASSERT((std::is_same<qssize_t, qptrdiff>::value));
and Functor-Based Connections}
*/
/*! \fn auto qConstOverload(T memberFunctionPointer)
/*! \fn template <typename T> auto qConstOverload(T memberFunctionPointer)
\relates <QtGlobal>
\since 5.7
@ -1043,7 +1042,7 @@ Q_STATIC_ASSERT((std::is_same<qssize_t, qptrdiff>::value));
and Functor-Based Connections}
*/
/*! \fn auto qNonConstOverload(T memberFunctionPointer)
/*! \fn template <typename T> auto qNonConstOverload(T memberFunctionPointer)
\relates <QtGlobal>
\since 5.7
@ -3105,10 +3104,10 @@ QByteArray QSysInfo::bootUniqueId()
*/
/*!
\fn T *q_check_ptr(T *pointer)
\fn template <typename T> T *q_check_ptr(T *p)
\relates <QtGlobal>
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 <typename T> qAsConst(T &t)
\relates <QtGlobal>
\since 5.7
@ -3655,7 +3654,7 @@ bool qunsetenv(const char *varName)
*/
/*!
\fn qAsConst(const T &&t)
\fn template <typename T> qAsConst(const T &&t)
\relates <QtGlobal>
\since 5.7
\overload