doc: Correct qdoc warnings in qobject.cpp and qmetatype.cpp

clang required adding template clauses to a few \fn commands.
There were also a few cases where Q_QDOC was changed to Q_CLANG_QDOC
and a few cases where special declarations for qdoc were removed in
favor of the actual declarations.

Unfortunately, a few qdoc warnings remain unfixed for classes
QObject and QMetaType, but these might be caused by minor bugs
in clang-qdoc itself, so they will be fixed there.

Change-Id: Ib586628cb6d2aa9cf4bcad303b5af09b412a7e57
Reviewed-by: Topi Reiniö <topi.reinio@qt.io>

5 files changed, 33 insertions, 40 deletions

diff --git a/src/corelib/kernel/qmetatype.cpp b/src/corelib/kernel/qmetatype.cpp
index e48807ea49..091dfa8d37 100644
--- a/src/corelib/kernel/qmetatype.cpp
+++ b/src/corelib/kernel/qmetatype.cpp
@@ -586,7 +586,7 @@ Q_GLOBAL_STATIC(QMetaTypeDebugStreamRegistry, customTypesDebugStreamRegistry)
 */
 
 /*!
-    \fn bool QMetaType::registerConverter(MemberFunction function)
+    \fn  template<typename MemberFunction, int> bool QMetaType::registerConverter(MemberFunction function)
     \since 5.2
     \overload
     Registers a method \a function like To From::function() const as converter from type From
@@ -594,7 +594,7 @@ Q_GLOBAL_STATIC(QMetaTypeDebugStreamRegistry, customTypesDebugStreamRegistry)
 */
 
 /*!
-    \fn bool QMetaType::registerConverter(MemberFunctionOk function)
+    \fn template<typename MemberFunctionOk, char> bool QMetaType::registerConverter(MemberFunctionOk function)
     \since 5.2
     \overload
     Registers a method \a function like To From::function(bool *ok) const as converter from type From
@@ -602,7 +602,7 @@ Q_GLOBAL_STATIC(QMetaTypeDebugStreamRegistry, customTypesDebugStreamRegistry)
 */
 
 /*!
-    \fn bool QMetaType::registerConverter(UnaryFunction function)
+    \fn template<typename UnaryFunction> bool QMetaType::registerConverter(UnaryFunction function)
     \since 5.2
     \overload
     Registers a unary function object \a function as converter from type From
diff --git a/src/corelib/kernel/qmetatype.h b/src/corelib/kernel/qmetatype.h
index 47c3a1c6f6..666949f41a 100644
--- a/src/corelib/kernel/qmetatype.h
+++ b/src/corelib/kernel/qmetatype.h
@@ -406,7 +406,7 @@ class Q_CORE_EXPORT QMetaType {
                          FlagsEx = 0x100, MetaObjectEx = 0x200
                        };
 public:
-#ifndef Q_QDOC
+#ifndef Q_CLANG_QDOC
     // The code that actually gets compiled.
     enum Type {
         // these are merged with QVariant
@@ -596,7 +596,7 @@ public:
         return registerConverter<From, To>(QtPrivate::convertImplicit<From, To>);
     }
 
-#ifdef Q_QDOC
+#ifdef Q_CLANG_QDOC
     template<typename MemberFunction, int>
     static bool registerConverter(MemberFunction function);
     template<typename MemberFunctionOk, char>
@@ -692,7 +692,7 @@ private:
 
 // ### Qt6: FIXME: Remove the special Q_CC_MSVC handling, it was introduced to maintain BC.
 #if !defined(Q_NO_TEMPLATE_FRIENDS) && !defined(Q_CC_MSVC)
-#ifndef Q_QDOC
+#ifndef Q_CLANG_QDOC
     template<typename, bool> friend struct QtPrivate::ValueTypeIsMetaType;
     template<typename, typename> friend struct QtPrivate::ConverterMemberFunction;
     template<typename, typename> friend struct QtPrivate::ConverterMemberFunctionOk;
@@ -1682,7 +1682,7 @@ namespace QtPrivate {
 
 template <typename T>
 int qRegisterNormalizedMetaType(const QT_PREPEND_NAMESPACE(QByteArray) &normalizedTypeName
-#ifndef Q_QDOC
+#ifndef Q_CLANG_QDOC
     , T * dummy = 0
     , typename QtPrivate::MetaTypeDefinedHelper<T, QMetaTypeId2<T>::Defined && !QMetaTypeId2<T>::IsBuiltIn>::DefinedType defined = QtPrivate::MetaTypeDefinedHelper<T, QMetaTypeId2<T>::Defined && !QMetaTypeId2<T>::IsBuiltIn>::Defined
 #endif
@@ -1719,7 +1719,7 @@ int qRegisterNormalizedMetaType(const QT_PREPEND_NAMESPACE(QByteArray) &normaliz
 
 template <typename T>
 int qRegisterMetaType(const char *typeName
-#ifndef Q_QDOC
+#ifndef Q_CLANG_QDOC
     , T * dummy = nullptr
     , typename QtPrivate::MetaTypeDefinedHelper<T, QMetaTypeId2<T>::Defined && !QMetaTypeId2<T>::IsBuiltIn>::DefinedType defined = QtPrivate::MetaTypeDefinedHelper<T, QMetaTypeId2<T>::Defined && !QMetaTypeId2<T>::IsBuiltIn>::Defined
 #endif
@@ -1736,7 +1736,7 @@ int qRegisterMetaType(const char *typeName
 #ifndef QT_NO_DATASTREAM
 template <typename T>
 void qRegisterMetaTypeStreamOperators(const char *typeName
-#ifndef Q_QDOC
+#ifndef Q_CLANG_QDOC
     , T * /* dummy */ = nullptr
 #endif
 )
@@ -1760,7 +1760,7 @@ inline Q_DECL_CONSTEXPR int qRegisterMetaType()
     return qMetaTypeId<T>();
 }
 
-#if QT_DEPRECATED_SINCE(5, 1) && !defined(Q_QDOC)
+#if QT_DEPRECATED_SINCE(5, 1) && !defined(Q_CLANG_QDOC)
 // There used to be a T *dummy = 0 argument in Qt 4.0 to support MSVC6
 template <typename T>
 QT_DEPRECATED inline Q_DECL_CONSTEXPR int qMetaTypeId(T *)
@@ -1932,7 +1932,7 @@ QT_FOR_EACH_STATIC_WIDGETS_CLASS(QT_FORWARD_DECLARE_STATIC_TYPES_ITER)
 typedef QList<QVariant> QVariantList;
 typedef QMap<QString, QVariant> QVariantMap;
 typedef QHash<QString, QVariant> QVariantHash;
-#ifndef Q_QDOC
+#ifndef Q_CLANG_QDOC
 typedef QList<QByteArray> QByteArrayList;
 #endif
 
diff --git a/src/corelib/kernel/qobject.cpp b/src/corelib/kernel/qobject.cpp
index 30cae20359..e2459e4283 100644
--- a/src/corelib/kernel/qobject.cpp
+++ b/src/corelib/kernel/qobject.cpp
@@ -1044,7 +1044,7 @@ QObjectPrivate::Connection::~Connection()
 
 
 /*!
-    \fn QMetaObject *QObject::metaObject() const
+    \fn const QMetaObject *QObject::metaObject() const
 
     Returns a pointer to the meta-object of this object.
 
@@ -1092,7 +1092,7 @@ QObjectPrivate::Connection::~Connection()
     \sa metaObject()
 */
 
-/*! \fn T *qobject_cast<T *>(QObject *object)
+/*! \fn template <class T> T *qobject_cast<T *>(QObject *object)
     \relates QObject
 
     Returns the given \a object cast to type T if the object is of type
@@ -1742,7 +1742,7 @@ void QObject::killTimer(int id)
 
 
 /*!
-    \fn T *QObject::findChild(const QString &name, Qt::FindChildOptions options) const
+    \fn template<typename T> T *QObject::findChild(const QString &name, Qt::FindChildOptions options) const
 
     Returns the child of this object that can be cast into type T and
     that is called \a name, or 0 if there is no such object.
@@ -1779,7 +1779,7 @@ void QObject::killTimer(int id)
 */
 
 /*!
-    \fn QList<T> QObject::findChildren(const QString &name, Qt::FindChildOptions options) const
+    \fn template<typename T> QList<T> QObject::findChildren(const QString &name, Qt::FindChildOptions options) const
 
     Returns all children of this object with the given \a name that can be
     cast to type T, or an empty list if there are no such objects.
@@ -1804,7 +1804,7 @@ void QObject::killTimer(int id)
 */
 
 /*!
-    \fn QList<T> QObject::findChildren(const QRegExp &regExp, Qt::FindChildOptions options) const
+    \fn template<typename T> QList<T> QObject::findChildren(const QRegExp &regExp, Qt::FindChildOptions options) const
     \overload findChildren()
 
     Returns the children of this object that can be cast to type T
@@ -1828,7 +1828,7 @@ void QObject::killTimer(int id)
 */
 
 /*!
-    \fn T qFindChild(const QObject *obj, const QString &name)
+    \fn template<typename T> T qFindChild(const QObject *obj, const QString &name)
     \relates QObject
     \overload qFindChildren()
     \obsolete
@@ -1844,7 +1844,7 @@ void QObject::killTimer(int id)
 */
 
 /*!
-    \fn QList<T> qFindChildren(const QObject *obj, const QString &name)
+    \fn template<typename T> QList<T> qFindChildren(const QObject *obj, const QString &name)
     \relates QObject
     \overload qFindChildren()
     \obsolete
@@ -1860,7 +1860,7 @@ void QObject::killTimer(int id)
 */
 
 /*!
-    \fn QList<T> qFindChildren(const QObject *obj, const QRegExp &regExp)
+    \fn template<typename T> QList<T> qFindChildren(const QObject *obj, const QRegExp &regExp)
     \relates QObject
     \overload qFindChildren()
 
@@ -2127,7 +2127,7 @@ void QObject::removeEventFilter(QObject *obj)
 
 
 /*!
-    \fn QObject::destroyed(QObject *obj)
+    \fn void QObject::destroyed(QObject *obj)
 
     This signal is emitted immediately before the object \a obj is
     destroyed, and can not be blocked.
@@ -4599,7 +4599,7 @@ void qDeleteInEventHandler(QObject *o)
 }
 
 /*!
-    \fn QMetaObject::Connection QObject::connect(const QObject *sender, PointerToMemberFunction signal, const QObject *receiver, PointerToMemberFunction method, Qt::ConnectionType type)
+    \fn template<typename PointerToMemberFunction> QMetaObject::Connection QObject::connect(const QObject *sender, PointerToMemberFunction signal, const QObject *receiver, PointerToMemberFunction method, Qt::ConnectionType type)
     \overload connect()
     \threadsafe
 
@@ -4663,7 +4663,7 @@ void qDeleteInEventHandler(QObject *o)
  */
 
 /*!
-    \fn QMetaObject::Connection QObject::connect(const QObject *sender, PointerToMemberFunction signal, Functor functor)
+    \fn template<typename PointerToMemberFunction, typename Functor> QMetaObject::Connection QObject::connect(const QObject *sender, PointerToMemberFunction signal, Functor functor)
 
     \threadsafe
     \overload connect()
@@ -4697,7 +4697,7 @@ void qDeleteInEventHandler(QObject *o)
  */
 
 /*!
-    \fn QMetaObject::Connection QObject::connect(const QObject *sender, PointerToMemberFunction signal, const QObject *context, Functor functor, Qt::ConnectionType type)
+    \fn template<typename PointerToMemberFunction, typename Functor> QMetaObject::Connection QObject::connect(const QObject *sender, PointerToMemberFunction signal, const QObject *context, Functor functor, Qt::ConnectionType type)
 
     \threadsafe
     \overload connect()
@@ -4895,7 +4895,7 @@ bool QObject::disconnect(const QMetaObject::Connection &connection)
     return true;
 }
 
-/*! \fn bool QObject::disconnect(const QObject *sender, PointerToMemberFunction signal, const QObject *receiver, PointerToMemberFunction method)
+/*! \fn template<typename PointerToMemberFunction> bool QObject::disconnect(const QObject *sender, PointerToMemberFunction signal, const QObject *receiver, PointerToMemberFunction method)
     \overload diconnect()
     \threadsafe
 
diff --git a/src/corelib/kernel/qobject.h b/src/corelib/kernel/qobject.h
index d297109acb..da9c422739 100644
--- a/src/corelib/kernel/qobject.h
+++ b/src/corelib/kernel/qobject.h
@@ -126,13 +126,11 @@ public:
     virtual bool event(QEvent *event);
     virtual bool eventFilter(QObject *watched, QEvent *event);
 
-#ifdef Q_QDOC
-    static QString tr(const char *sourceText, const char *comment = nullptr, int n = -1);
-    static QString trUtf8(const char *sourceText, const char *comment = nullptr, int n = -1);
+#ifdef Q_CLANG_QDOC
     virtual const QMetaObject *metaObject() const;
     static const QMetaObject staticMetaObject;
 #endif
-#ifdef QT_NO_TRANSLATION
+#if defined(QT_NO_TRANSLATION) || defined(Q_CLANG_QDOC)
     static QString tr(const char *sourceText, const char * = nullptr, int = -1)
         { return QString::fromUtf8(sourceText); }
 #if QT_DEPRECATED_SINCE(5, 0)
@@ -154,7 +152,7 @@ public:
     void moveToThread(QThread *thread);
 
     int startTimer(int interval, Qt::TimerType timerType = Qt::CoarseTimer);
-#if QT_HAS_INCLUDE(<chrono>) || defined(Q_QDOC)
+#if QT_HAS_INCLUDE(<chrono>)
     Q_ALWAYS_INLINE
     int startTimer(std::chrono::milliseconds time, Qt::TimerType timerType = Qt::CoarseTimer)
     {
@@ -220,7 +218,7 @@ public:
     inline QMetaObject::Connection connect(const QObject *sender, const char *signal,
                         const char *member, Qt::ConnectionType type = Qt::AutoConnection) const;
 
-#ifdef Q_QDOC
+#ifdef Q_CLANG_QDOC
     template<typename PointerToMemberFunction>
     static QMetaObject::Connection connect(const QObject *sender, PointerToMemberFunction signal, const QObject *receiver, PointerToMemberFunction method, Qt::ConnectionType type = Qt::AutoConnection);
     template<typename PointerToMemberFunction, typename Functor>
@@ -337,7 +335,7 @@ public:
                                 typename SignalType::ReturnType>(std::move(slot)),
                            type, types, &SignalType::Object::staticMetaObject);
     }
-#endif //Q_QDOC
+#endif //Q_CLANG_QDOC
 
     static bool disconnect(const QObject *sender, const char *signal,
                            const QObject *receiver, const char *member);
@@ -350,7 +348,7 @@ public:
         { return disconnect(this, nullptr, receiver, member); }
     static bool disconnect(const QMetaObject::Connection &);
 
-#ifdef Q_QDOC
+#ifdef Q_CLANG_QDOC
     template<typename PointerToMemberFunction>
     static bool disconnect(const QObject *sender, PointerToMemberFunction signal, const QObject *receiver, PointerToMemberFunction method);
 #else
@@ -383,7 +381,7 @@ public:
         return disconnectImpl(sender, reinterpret_cast<void **>(&signal), receiver, zero,
                               &SignalType::Object::staticMetaObject);
     }
-#endif //Q_QDOC
+#endif //Q_CLANG_QDOC
 
 
 #if QT_VERSION < QT_VERSION_CHECK(6, 0, 0)
@@ -479,11 +477,6 @@ public:
 };
 #endif
 
-#ifdef Q_QDOC
-T qFindChild(const QObject *o, const QString &name = QString());
-QList<T> qFindChildren(const QObject *oobj, const QString &name = QString());
-QList<T> qFindChildren(const QObject *o, const QRegExp &re);
-#endif
 #if QT_DEPRECATED_SINCE(5, 0)
 template<typename T>
 inline QT_DEPRECATED T qFindChild(const QObject *o, const QString &name = QString())
@@ -495,7 +488,7 @@ inline QT_DEPRECATED QList<T> qFindChildren(const QObject *o, const QString &nam
     return o->findChildren<T>(name);
 }
 
-#ifndef QT_NO_REGEXP
+#if !defined(QT_NO_REGEXP) || defined(Q_CLANG_QDOC)
 template<typename T>
 inline QT_DEPRECATED QList<T> qFindChildren(const QObject *o, const QRegExp &re)
 {
diff --git a/src/corelib/kernel/qobjectdefs.h b/src/corelib/kernel/qobjectdefs.h
index 7d2cc4dcbc..bc77c136e3 100644
--- a/src/corelib/kernel/qobjectdefs.h
+++ b/src/corelib/kernel/qobjectdefs.h
@@ -349,7 +349,7 @@ struct Q_CORE_EXPORT QMetaObject
     QObject *cast(QObject *obj) const;
     const QObject *cast(const QObject *obj) const;
 
-#ifndef QT_NO_TRANSLATION
+#if !defined(QT_NO_TRANSLATION) || defined(Q_CLANG_QDOC)
     QString tr(const char *s, const char *c, int n = -1) const;
 #endif // QT_NO_TRANSLATION