Align methods and docs for QScxmlStateMachine

qdoc can nowadays parse the complex method declarations in
qscxmlstatemachine.h, so we don't need to ifdef them out anymore.

Also, recognize that the context parameters to the connect methods can
all be const, as documented, and rename some parameters to match the
documentation.

Change-Id: Iad200f9d4719d5c34e74ad0cc002338322662e8f
Reviewed-by: Erik Verbruggen <erik.verbruggen@qt.io>

2 files changed, 63 insertions, 103 deletions

diff --git a/src/scxml/qscxmlstatemachine.cpp b/src/scxml/qscxmlstatemachine.cpp
index b477292..b7431ba 100644
--- a/src/scxml/qscxmlstatemachine.cpp
+++ b/src/scxml/qscxmlstatemachine.cpp
@@ -96,7 +96,7 @@ Q_LOGGING_CATEGORY(scxmlLog, "scxml.statemachine")
 /*!
     \fn template<typename PointerToMemberFunction> QMetaObject::Connection QScxmlStateMachine::connectToEvent(
                                            const QString &scxmlEventSpec,
-                                           const QObject *receiver,
+                                           const typename QtPrivate::FunctionPointer<PointerToMemberFunction>::Object *receiver,
                                            PointerToMemberFunction method,
                                            Qt::ConnectionType type)
 
@@ -114,7 +114,7 @@ Q_LOGGING_CATEGORY(scxmlLog, "scxml.statemachine")
 */
 
 /*!
-    \fn template<typename Functor> QMetaObject::Connection QScxmlStateMachine::connectToEvent(
+    \fn template<typename Functor> typename QtPrivate::QEnableIf<!QtPrivate::FunctionPointer<Functor>::IsPointerToMemberFunction && !std::is_same<const char*, Functor>::value, QMetaObject::Connection>::Type QScxmlStateMachine::connectToEvent(
                                            const QString &scxmlEventSpec,
                                            Functor functor,
                                            Qt::ConnectionType type)
@@ -133,7 +133,7 @@ Q_LOGGING_CATEGORY(scxmlLog, "scxml.statemachine")
 */
 
 /*!
-    \fn template<typename Functor> QMetaObject::Connection QScxmlStateMachine::connectToEvent(
+    \fn template<typename Functor> typename QtPrivate::QEnableIf<!QtPrivate::FunctionPointer<Functor>::IsPointerToMemberFunction && !std::is_same<const char*, Functor>::value, QMetaObject::Connection>::Type QScxmlStateMachine::connectToEvent(
                                            const QString &scxmlEventSpec,
                                            const QObject *context,
                                            Functor functor,
@@ -155,7 +155,7 @@ Q_LOGGING_CATEGORY(scxmlLog, "scxml.statemachine")
 /*!
     \fn template<typename PointerToMemberFunction> QMetaObject::Connection QScxmlStateMachine::connectToState(
                                            const QString &scxmlStateName,
-                                           const QObject *receiver,
+                                           const typename QtPrivate::FunctionPointer<PointerToMemberFunction>::Object *receiver,
                                            PointerToMemberFunction method,
                                            Qt::ConnectionType type)
 
@@ -168,9 +168,8 @@ Q_LOGGING_CATEGORY(scxmlLog, "scxml.statemachine")
     Returns a handle to the connection, which can be used later to disconnect.
 */
 
-
 /*!
-    \fn template<typename Functor> QMetaObject::Connection QScxmlStateMachine::connectToState(
+    \fn template<typename Functor> typename QtPrivate::QEnableIf<!QtPrivate::FunctionPointer<Functor>::IsPointerToMemberFunction && !std::is_same<const char*, Functor>::value, QMetaObject::Connection>::Type QScxmlStateMachine::connectToState(
                                            const QString &scxmlStateName,
                                            Functor functor,
                                            Qt::ConnectionType type)
@@ -185,7 +184,7 @@ Q_LOGGING_CATEGORY(scxmlLog, "scxml.statemachine")
 */
 
 /*!
-    \fn template<typename Functor> QMetaObject::Connection QScxmlStateMachine::connectToState(
+    \fn template<typename Functor> typename QtPrivate::QEnableIf<!QtPrivate::FunctionPointer<Functor>::IsPointerToMemberFunction && !std::is_same<const char*, Functor>::value, QMetaObject::Connection>::Type QScxmlStateMachine::connectToState(
                                            const QString &scxmlStateName,
                                            const QObject *context,
                                            Functor functor,
@@ -231,7 +230,8 @@ Q_LOGGING_CATEGORY(scxmlLog, "scxml.statemachine")
  */
 
 /*!
-    \fn template<typename Functor> QScxmlStateMachine::onEntry(Functor functor)
+    \fn template<typename Functor> std::function<void(bool)> QScxmlStateMachine::onEntry(
+            Functor functor)
 
     Returns a functor that accepts a boolean argument and calls the given
     \a functor if that argument is \c true. The given \a functor must not
@@ -242,7 +242,7 @@ Q_LOGGING_CATEGORY(scxmlLog, "scxml.statemachine")
  */
 
 /*!
-    \fn template<typename Functor> QScxmlStateMachine::onExit(Functor functor)
+    \fn template<typename Functor> std::function<void(bool)> QScxmlStateMachine::onExit(Functor functor)
 
     Returns a functor that accepts a boolean argument and calls the given
     \a functor if that argument is \c false. The given \a functor must not
@@ -253,8 +253,9 @@ Q_LOGGING_CATEGORY(scxmlLog, "scxml.statemachine")
  */
 
 /*!
-    \fn template<typename PointerToMemberFunction> QScxmlStateMachine::onEntry(
-            const QObject *receiver, PointerToMemberFunction method)
+    \fn template<typename PointerToMemberFunction> std::function<void(bool)> QScxmlStateMachine::onEntry(
+            const typename QtPrivate::FunctionPointer<PointerToMemberFunction>::Object *receiver,
+            PointerToMemberFunction method)
 
     Returns a functor that accepts a boolean argument and calls the given
     \a method on \a receiver if that argument is \c true and the \a receiver
@@ -266,8 +267,9 @@ Q_LOGGING_CATEGORY(scxmlLog, "scxml.statemachine")
  */
 
 /*!
-    \fn template<typename PointerToMemberFunction> QScxmlStateMachine::onExit(
-            const QObject *receiver, PointerToMemberFunction method)
+    \fn template<typename PointerToMemberFunction> std::function<void(bool)> QScxmlStateMachine::onExit(
+            const typename QtPrivate::FunctionPointer<PointerToMemberFunction>::Object *receiver,
+            PointerToMemberFunction method)
 
     Returns a functor that accepts a boolean argument and calls the given
     \a method on \a receiver if that argument is \c false and the \a receiver
diff --git a/src/scxml/qscxmlstatemachine.h b/src/scxml/qscxmlstatemachine.h
index 830238c..090a1b6 100644
--- a/src/scxml/qscxmlstatemachine.h
+++ b/src/scxml/qscxmlstatemachine.h
@@ -111,79 +111,49 @@ public:
     QMetaObject::Connection connectToState(const QString &scxmlStateName,
                                            const QObject *receiver, const char *method,
                                            Qt::ConnectionType type = Qt::AutoConnection);
-#ifdef Q_QDOC
-    template<typename PointerToMemberFunction>
-    QMetaObject::Connection connectToState(const QString &scxmlStateName,
-                                           const QObject *receiver, PointerToMemberFunction method,
-                                           Qt::ConnectionType type = Qt::AutoConnection);
-    template<typename Functor>
-    QMetaObject::Connection connectToState(const QString &scxmlStateName, Functor functor,
-                                           Qt::ConnectionType type = Qt::AutoConnection);
-    template<typename Functor>
-    QMetaObject::Connection connectToState(const QString &scxmlStateName,
-                                           const QObject *context, Functor functor,
-                                           Qt::ConnectionType type = Qt::AutoConnection);
-#else
 
     // connect state to a QObject slot
-    template <typename Func1>
+    template <typename PointerToMemberFunction>
     inline QMetaObject::Connection connectToState(
             const QString &scxmlStateName,
-            const typename QtPrivate::FunctionPointer<Func1>::Object *receiver, Func1 slot,
+            const typename QtPrivate::FunctionPointer<PointerToMemberFunction>::Object *receiver,
+            PointerToMemberFunction method,
             Qt::ConnectionType type = Qt::AutoConnection)
     {
-        typedef QtPrivate::FunctionPointer<Func1> SlotType;
+        typedef QtPrivate::FunctionPointer<PointerToMemberFunction> SlotType;
         return connectToStateImpl(
                     scxmlStateName, receiver, nullptr,
-                    new QtPrivate::QSlotObject<Func1, typename SlotType::Arguments, void>(slot),
+                    new QtPrivate::QSlotObject<PointerToMemberFunction,
+                    typename SlotType::Arguments, void>(method),
                     type);
     }
 
     // connect state to a functor or function pointer (without context)
-    template <typename Func1>
+    template <typename Functor>
     inline typename QtPrivate::QEnableIf<
-            !QtPrivate::FunctionPointer<Func1>::IsPointerToMemberFunction &&
-            !std::is_same<const char*, Func1>::value, QMetaObject::Connection>::Type
-    connectToState(const QString &scxmlStateName, Func1 slot,
+            !QtPrivate::FunctionPointer<Functor>::IsPointerToMemberFunction &&
+            !std::is_same<const char*, Functor>::value, QMetaObject::Connection>::Type
+    connectToState(const QString &scxmlStateName, Functor functor,
                    Qt::ConnectionType type = Qt::AutoConnection)
     {
         // Use this as context
-        return connectToState(scxmlStateName, this, slot, type);
+        return connectToState(scxmlStateName, this, functor, type);
     }
 
     // connectToState to a functor or function pointer (with context)
-    template <typename Func1>
+    template <typename Functor>
     inline typename QtPrivate::QEnableIf<
-            !QtPrivate::FunctionPointer<Func1>::IsPointerToMemberFunction &&
-            !std::is_same<const char*, Func1>::value, QMetaObject::Connection>::Type
-    connectToState(const QString &scxmlStateName, QObject *context, Func1 slot,
+            !QtPrivate::FunctionPointer<Functor>::IsPointerToMemberFunction &&
+            !std::is_same<const char*, Functor>::value, QMetaObject::Connection>::Type
+    connectToState(const QString &scxmlStateName, const QObject *context, Functor functor,
                    Qt::ConnectionType type = Qt::AutoConnection)
     {
-        QtPrivate::QSlotObjectBase *slotObj = new QtPrivate::QFunctorSlotObject<Func1, 1,
-                QtPrivate::List<bool>, void>(slot);
-        return connectToStateImpl(scxmlStateName, context, reinterpret_cast<void **>(&slot),
+        QtPrivate::QSlotObjectBase *slotObj = new QtPrivate::QFunctorSlotObject<Functor, 1,
+                QtPrivate::List<bool>, void>(functor);
+        return connectToStateImpl(scxmlStateName, context, reinterpret_cast<void **>(&functor),
                                   slotObj, type);
     }
-#endif
-
-#ifdef Q_QDOC
-    static std::function<void(bool)> onEntry(const QObject *receiver, const char *method);
-    static std::function<void(bool)> onExit(const QObject *receiver, const char *method);
-
-    template<typename Functor>
-    static std::function<void(bool)> onEntry(Functor functor);
-
-    template<typename Functor>
-    static std::function<void(bool)> onExit(Functor functor);
-
-    template<typename PointerToMemberFunction>
-    static std::function<void(bool)> onEntry(const QObject *receiver,
-                                             PointerToMemberFunction method);
 
-    template<typename PointerToMemberFunction>
-    static std::function<void(bool)> onExit(const QObject *receiver,
-                                            PointerToMemberFunction method);
-#else
     static std::function<void(bool)> onEntry(const QObject *receiver, const char *method)
     {
         const QPointer<QObject> receiverPointer(const_cast<QObject *>(receiver));
@@ -220,89 +190,77 @@ public:
         };
     }
 
-    template<typename Func1>
+    template<typename PointerToMemberFunction>
     static std::function<void(bool)> onEntry(
-            const typename QtPrivate::FunctionPointer<Func1>::Object *receiver, Func1 slot)
+            const typename QtPrivate::FunctionPointer<PointerToMemberFunction>::Object *receiver,
+            PointerToMemberFunction method)
     {
-        typedef typename QtPrivate::FunctionPointer<Func1>::Object Object;
+        typedef typename QtPrivate::FunctionPointer<PointerToMemberFunction>::Object Object;
         const QPointer<Object> receiverPointer(const_cast<Object *>(receiver));
-        return [receiverPointer, slot](bool isEnteringState) {
+        return [receiverPointer, method](bool isEnteringState) {
             if (isEnteringState && !receiverPointer.isNull())
-                (receiverPointer->*slot)();
+                (receiverPointer->*method)();
         };
     }
 
-    template<typename Func1>
+    template<typename PointerToMemberFunction>
     static std::function<void(bool)> onExit(
-            const typename QtPrivate::FunctionPointer<Func1>::Object *receiver, Func1 slot)
+            const typename QtPrivate::FunctionPointer<PointerToMemberFunction>::Object *receiver,
+            PointerToMemberFunction method)
     {
-        typedef typename QtPrivate::FunctionPointer<Func1>::Object Object;
+        typedef typename QtPrivate::FunctionPointer<PointerToMemberFunction>::Object Object;
         const QPointer<Object> receiverPointer(const_cast<Object *>(receiver));
-        return [receiverPointer, slot](bool isEnteringState) {
+        return [receiverPointer, method](bool isEnteringState) {
             if (!isEnteringState && !receiverPointer.isNull())
-                (receiverPointer->*slot)();
+                (receiverPointer->*method)();
         };
     }
-#endif // !Q_QDOC
 
     QMetaObject::Connection connectToEvent(const QString &scxmlEventSpec,
                                            const QObject *receiver, const char *method,
                                            Qt::ConnectionType type = Qt::AutoConnection);
 
-#ifdef Q_QDOC
-    template<typename PointerToMemberFunction>
-    QMetaObject::Connection connectToEvent(const QString &scxmlEventSpec,
-                                           const QObject *receiver, PointerToMemberFunction method,
-                                           Qt::ConnectionType type = Qt::AutoConnection);
-    template<typename Functor>
-    QMetaObject::Connection connectToEvent(const QString &scxmlEventSpec, Functor functor,
-                                           Qt::ConnectionType type = Qt::AutoConnection);
-    template<typename Functor>
-    QMetaObject::Connection connectToEvent(const QString &scxmlEventSpec,
-                                           const QObject *context, Functor functor,
-                                           Qt::ConnectionType type = Qt::AutoConnection);
-#else
-
     // connect state to a QObject slot
-    template <typename Func1>
+    template <typename PointerToMemberFunction>
     inline QMetaObject::Connection connectToEvent(
             const QString &scxmlEventSpec,
-            const typename QtPrivate::FunctionPointer<Func1>::Object *receiver, Func1 slot,
+            const typename QtPrivate::FunctionPointer<PointerToMemberFunction>::Object *receiver,
+            PointerToMemberFunction method,
             Qt::ConnectionType type = Qt::AutoConnection)
     {
-        typedef QtPrivate::FunctionPointer<Func1> SlotType;
+        typedef QtPrivate::FunctionPointer<PointerToMemberFunction> SlotType;
         return connectToEventImpl(
                     scxmlEventSpec, receiver, nullptr,
-                    new QtPrivate::QSlotObject<Func1, typename SlotType::Arguments, void>(slot),
+                    new QtPrivate::QSlotObject<PointerToMemberFunction,
+                    typename SlotType::Arguments, void>(method),
                     type);
     }
 
     // connect state to a functor or function pointer (without context)
-    template <typename Func1>
+    template <typename Functor>
     inline typename QtPrivate::QEnableIf<
-            !QtPrivate::FunctionPointer<Func1>::IsPointerToMemberFunction &&
-            !std::is_same<const char*, Func1>::value, QMetaObject::Connection>::Type
-    connectToEvent(const QString &scxmlEventSpec, Func1 slot,
+            !QtPrivate::FunctionPointer<Functor>::IsPointerToMemberFunction &&
+            !std::is_same<const char*, Functor>::value, QMetaObject::Connection>::Type
+    connectToEvent(const QString &scxmlEventSpec, Functor functor,
                    Qt::ConnectionType type = Qt::AutoConnection)
     {
         // Use this as context
-        return connectToEvent(scxmlEventSpec, this, slot, type);
+        return connectToEvent(scxmlEventSpec, this, functor, type);
     }
 
     // connectToEvent to a functor or function pointer (with context)
-    template <typename Func1>
+    template <typename Functor>
     inline typename QtPrivate::QEnableIf<
-            !QtPrivate::FunctionPointer<Func1>::IsPointerToMemberFunction &&
-            !std::is_same<const char*, Func1>::value, QMetaObject::Connection>::Type
-    connectToEvent(const QString &scxmlEventSpec, QObject *context, Func1 slot,
+            !QtPrivate::FunctionPointer<Functor>::IsPointerToMemberFunction &&
+            !std::is_same<const char*, Functor>::value, QMetaObject::Connection>::Type
+    connectToEvent(const QString &scxmlEventSpec, const QObject *context, Functor functor,
                    Qt::ConnectionType type = Qt::AutoConnection)
     {
-        QtPrivate::QSlotObjectBase *slotObj = new QtPrivate::QFunctorSlotObject<Func1, 1,
-                QtPrivate::List<QScxmlEvent>, void>(slot);
-        return connectToEventImpl(scxmlEventSpec, context, reinterpret_cast<void **>(&slot),
+        QtPrivate::QSlotObjectBase *slotObj = new QtPrivate::QFunctorSlotObject<Functor, 1,
+                QtPrivate::List<QScxmlEvent>, void>(functor);
+        return connectToEventImpl(scxmlEventSpec, context, reinterpret_cast<void **>(&functor),
                                   slotObj, type);
     }
-#endif
 
     Q_INVOKABLE void submitEvent(QScxmlEvent *event);
     Q_INVOKABLE void submitEvent(const QString &eventName);