QMetaType: Expand and clean up converter/view function documentation

This adds a few snippets to show how the functions can be used, and also
removes workarounds for oldver versions of qdoc that weren't clang based
- those workarounds also seem to have caused some bitrot.

Remove documentation for an overload of registerMutableView that
currently does not exist (for a member function with an ok parameter).

Fixes: QTBUG-96963
Pick-to: 6.2
Change-Id: Ibc867d08bcacbc7add8c965df9864d6f339a5d54
Reviewed-by: Thiago Macieira <thiago.macieira@intel.com>

2 files changed, 17 insertions, 30 deletions

diff --git a/src/corelib/kernel/qmetatype.cpp b/src/corelib/kernel/qmetatype.cpp
index 41b991580f..b2d280cf57 100644
--- a/src/corelib/kernel/qmetatype.cpp
+++ b/src/corelib/kernel/qmetatype.cpp
@@ -1600,30 +1600,42 @@ Q_GLOBAL_STATIC(QMetaTypeMutableViewRegistry, customTypesMutableViewRegistry)
     \since 5.2
     Registers the possibility of an implicit conversion from type From to type To in the meta
     type system. Returns \c true if the registration succeeded, otherwise false.
+
+    \snippet qmetatype/registerConverters.cpp [implicit]
 */
 
 /*!
-    \fn  template<typename MemberFunction, int> bool QMetaType::registerConverter(MemberFunction function)
+    \fn template<typename From, typename To> static bool registerConverter(To(From::*function)() const)
     \since 5.2
     \overload
     Registers a method \a function like To From::function() const as converter from type From
     to type To in the meta type system. Returns \c true if the registration succeeded, otherwise false.
+
+    \snippet qmetatype/registerConverters.cpp [member]
 */
 
 /*!
-    \fn template<typename MemberFunctionOk, char> bool QMetaType::registerConverter(MemberFunctionOk function)
+    \fn template<typename From, typename To> static bool registerConverter(To(From::*function)(bool*) const)
     \since 5.2
     \overload
     Registers a method \a function like To From::function(bool *ok) const as converter from type From
     to type To in the meta type system. Returns \c true if the registration succeeded, otherwise false.
+
+    The \a ok pointer can be used by the function to indicate whether the conversion succceeded.
+    \snippet qmetatype/registerConverters.cpp [memberOk]
+
 */
 
 /*!
-    \fn template<typename UnaryFunction> bool QMetaType::registerConverter(UnaryFunction function)
+    \fn template<typename From, typename To, typename UnaryFunction> static bool registerConverter(UnaryFunction function)
     \since 5.2
     \overload
     Registers a unary function object \a function as converter from type From
     to type To in the meta type system. Returns \c true if the registration succeeded, otherwise false.
+
+    \a function must take an instance of type \a From and return an instance of \a To. It can be a function
+    pointer, a lambda or a functor object.
+    \snippet qmetatype/registerConverters.cpp [unaryfunc]
 */
 
 /*!
@@ -1644,7 +1656,7 @@ bool QMetaType::registerConverterFunction(const ConverterFunction &f, QMetaType
 }
 
 /*!
-    \fn  template<typename MemberFunction, int> bool QMetaType::registerMutableView(MemberFunction function)
+    \fn template<typename From, typename To> static bool registerMutableView(To(From::*function)())
     \since 6.0
     \overload
     Registers a method \a function like \c {To From::function()} as mutable view of type \c {To} on
@@ -1653,16 +1665,7 @@ bool QMetaType::registerConverterFunction(const ConverterFunction &f, QMetaType
 */
 
 /*!
-    \fn template<typename MemberFunctionOk, char> bool QMetaType::registerMutableView(MemberFunctionOk function)
-    \since 6.0
-    \overload
-    Registers a method \a function like To From::function(bool *ok) as mutable view of type To on
-    type From in the meta type system. Returns \c true if the registration succeeded, otherwise
-    \c false.
-*/
-
-/*!
-    \fn template<typename UnaryFunction> bool QMetaType::registerMutableView(UnaryFunction function)
+    \fn template<typename From, typename To, typename UnaryFunction> static bool registerMutableView(UnaryFunction function)
     \since 6.0
     \overload
     Registers a unary function object \a function as mutable view of type To on type From
diff --git a/src/corelib/kernel/qmetatype.h b/src/corelib/kernel/qmetatype.h
index 9d4d7d3c88..327f918d6b 100644
--- a/src/corelib/kernel/qmetatype.h
+++ b/src/corelib/kernel/qmetatype.h
@@ -541,21 +541,6 @@ public:
         return registerConverter<From, To>(QtPrivate::convertImplicit<From, To>);
     }
 
-#ifdef Q_CLANG_QDOC
-    template<typename MemberFunction, int>
-    static bool registerConverter(MemberFunction function);
-    template<typename MemberFunctionOk, char>
-    static bool registerConverter(MemberFunctionOk function);
-    template<typename UnaryFunction>
-    static bool registerConverter(UnaryFunction function);
-
-    template<typename MemberFunction, int>
-    static bool registerMutableView(MemberFunction function);
-    template<typename MemberFunctionOk, char>
-    static bool registerMutableView(MemberFunctionOk function);
-    template<typename UnaryFunction>
-    static bool registerMutableView(UnaryFunction function);
-#else
     // member function as in "QString QFont::toString() const"
     template<typename From, typename To>
     static bool registerConverter(To(From::*function)() const)
@@ -675,7 +660,6 @@ private:
             return false;
         }
     }
-#endif // Q_CLANG_DOC
 public:
 
     static bool convert(QMetaType fromType, const void *from, QMetaType toType, void *to);