From 15942fe84483ff6aabf1008f3edc153b9ff31b4d Mon Sep 17 00:00:00 2001
From: Ulf Hermann <ulf.hermann@qt.io>
Date: Wed, 21 Sep 2016 18:36:11 +0200
Subject: Add missing documentation

Most of the methods marked as \internal or excluded via
"#ifndef Q_QDOC" so far are not actually internal as they are called
from compiled state machines. We have to document them.

Change-Id: Ib80268ae00f536e9ac2d337b565dcafbbdc31dea
Reviewed-by: Erik Verbruggen <erik.verbruggen@qt.io>
---
 src/scxml/qscxmlcppdatamodel.cpp        |  67 ++++++++++---
 src/scxml/qscxmlcppdatamodel.h          |   3 +-
 src/scxml/qscxmldatamodel.cpp           |  75 +++++++++++++-
 src/scxml/qscxmldatamodel.h             |   2 -
 src/scxml/qscxmlecmascriptdatamodel.cpp |  42 ++++++--
 src/scxml/qscxmlecmascriptdatamodel.h   |   2 -
 src/scxml/qscxmlexecutablecontent.cpp   | 169 ++++++++++++++++++++++++++++++++
 src/scxml/qscxmlexecutablecontent_p.h   |   2 +
 src/scxml/qscxmlinvokableservice.cpp    | 133 +++++++++++++++++++++++++
 src/scxml/qscxmlnulldatamodel.cpp       |  53 +++++++++-
 src/scxml/qscxmlnulldatamodel.h         |   2 -
 src/scxml/qscxmlstatemachine.cpp        |  25 +++--
 src/scxml/qscxmlstatemachine.h          |   4 -
 src/scxml/qscxmltabledata.cpp           |  73 ++++++++++++++
 14 files changed, 602 insertions(+), 50 deletions(-)

diff --git a/src/scxml/qscxmlcppdatamodel.cpp b/src/scxml/qscxmlcppdatamodel.cpp
index 060c220..23a7392 100644
--- a/src/scxml/qscxmlcppdatamodel.cpp
+++ b/src/scxml/qscxmlcppdatamodel.cpp
@@ -52,7 +52,7 @@ using namespace QScxmlExecutableContent;
 
    \sa QScxmlStateMachine QScxmlDataModel
 
-   The C++ data model for SCXML that lets you write C++ code for \e expr attributes and \c <script>
+   The C++ data model for SCXML lets you write C++ code for \e expr attributes and \c <script>
    elements. The \e {data part} of the data model is backed by a subclass of QScxmlCppDataModel, for
    which the Qt SCXML compiler (\c qscxmlc) will generate the dispatch methods. It cannot be used
    when loading an SCXML file at runtime.
@@ -69,6 +69,7 @@ using namespace QScxmlExecutableContent;
 
 class TheDataModel: public QScxmlCppDataModel
 {
+    Q_OBJECT
     Q_SCXML_DATAMODEL
 };
    \endcode
@@ -77,8 +78,6 @@ class TheDataModel: public QScxmlCppDataModel
    This macro expands to the declaration of some virtual
    methods whose implementation is generated by the Qt SCXML compiler.
 
-   \note You can of course inherit from both QScxmlCppDataModel and QObject.
-
    The Qt SCXML compiler will generate the various \c evaluateTo methods, and convert expressions and
    scripts into lambdas inside those methods. For example:
    \code
@@ -148,19 +147,41 @@ bool QScxmlCppDataModel::setup(const QVariantMap &initialDataValues)
     return true;
 }
 
-void QScxmlCppDataModel::evaluateAssignment(EvaluatorId id, bool *ok)
+/*!
+  \reimp
+
+  This method doesn't perform any action, ignores \a id, and sets \a ok to
+  \c false. Override it in your specific data model in order to implement
+  \c <assign>.
+ */
+void QScxmlCppDataModel::evaluateAssignment(QScxmlExecutableContent::EvaluatorId id, bool *ok)
 {
     Q_UNUSED(id);
     *ok = false;
 }
 
-void QScxmlCppDataModel::evaluateInitialization(EvaluatorId id, bool *ok)
+/*!
+  \reimp
+
+  This method doesn't perform any action, ignores \a id, and sets \a ok to
+  \c false. Override it in your specific data model in order to implement
+  \c <data>.
+ */
+void QScxmlCppDataModel::evaluateInitialization(QScxmlExecutableContent::EvaluatorId id, bool *ok)
 {
     Q_UNUSED(id);
     *ok = false;
 }
 
-void QScxmlCppDataModel::evaluateForeach(EvaluatorId id, bool *ok, ForeachLoopBody *body)
+/*!
+  \reimp
+
+  This method doesn't perform any action, ignores \a id and \a body, and sets
+  \a ok to \c false. Override it in your specific data model in order to
+  implement \c <foreach>.
+ */
+void QScxmlCppDataModel::evaluateForeach(QScxmlExecutableContent::EvaluatorId id, bool *ok,
+                                         ForeachLoopBody *body)
 {
     Q_UNUSED(id);
     Q_UNUSED(body);
@@ -168,9 +189,11 @@ void QScxmlCppDataModel::evaluateForeach(EvaluatorId id, bool *ok, ForeachLoopBo
 }
 
 /*!
- * Sets the \a event that will be processed next.
- *
- * \sa QScxmlCppDataModel::scxmlEvent
+  \reimp
+
+  Sets the \a event that will be processed next.
+
+  \sa QScxmlCppDataModel::scxmlEvent
  */
 void QScxmlCppDataModel::setScxmlEvent(const QScxmlEvent &event)
 {
@@ -197,7 +220,11 @@ const QScxmlEvent &QScxmlCppDataModel::scxmlEvent() const
 }
 
 /*!
- * \reimp
+  \reimp
+
+  This method always returns an empty QVariant and ignores \a name.
+  Override it to implement lookup of data model properties via the
+  \c location attribute of various elements.
  */
 QVariant QScxmlCppDataModel::scxmlProperty(const QString &name) const
 {
@@ -206,7 +233,11 @@ QVariant QScxmlCppDataModel::scxmlProperty(const QString &name) const
 }
 
 /*!
- * \reimp
+  \reimp
+
+  This method always returns false and ignores \a name.
+  Override it to implement lookup of data model properties via the
+  \c location attribute of various elements.
  */
 bool QScxmlCppDataModel::hasScxmlProperty(const QString &name) const
 {
@@ -215,9 +246,15 @@ bool QScxmlCppDataModel::hasScxmlProperty(const QString &name) const
 }
 
 /*!
- * \reimp
+  \reimp
+
+  This method always returns false and ignores \a name, \a value, and
+  \a context.
+  Override it to implement lookup of data model properties via the
+  \c location attribute of various elements.
  */
-bool QScxmlCppDataModel::setScxmlProperty(const QString &name, const QVariant &value, const QString &context)
+bool QScxmlCppDataModel::setScxmlProperty(const QString &name, const QVariant &value,
+                                          const QString &context)
 {
     Q_UNUSED(name);
     Q_UNUSED(value);
@@ -226,8 +263,8 @@ bool QScxmlCppDataModel::setScxmlProperty(const QString &name, const QVariant &v
 }
 
 /*!
- * Returns \c true if the state machine is in the state specified by \a stateName, \c false
- * otherwise.
+  Returns \c true if the state machine is in the state specified by
+  \a stateName, \c false otherwise.
  */
 bool QScxmlCppDataModel::inState(const QString &stateName) const
 {
diff --git a/src/scxml/qscxmlcppdatamodel.h b/src/scxml/qscxmlcppdatamodel.h
index a491326..244259f 100644
--- a/src/scxml/qscxmlcppdatamodel.h
+++ b/src/scxml/qscxmlcppdatamodel.h
@@ -62,11 +62,10 @@ public:
 
     Q_INVOKABLE bool setup(const QVariantMap &initialDataValues) Q_DECL_OVERRIDE;
 
-#ifndef Q_QDOC
     void evaluateAssignment(QScxmlExecutableContent::EvaluatorId id, bool *ok) Q_DECL_OVERRIDE;
     void evaluateInitialization(QScxmlExecutableContent::EvaluatorId id, bool *ok) Q_DECL_OVERRIDE;
     void evaluateForeach(QScxmlExecutableContent::EvaluatorId id, bool *ok, ForeachLoopBody *body) Q_DECL_OVERRIDE;
-#endif // Q_QDOC
+
     void setScxmlEvent(const QScxmlEvent &scxmlEvent) Q_DECL_OVERRIDE Q_DECL_FINAL;
     const QScxmlEvent &scxmlEvent() const;
 
diff --git a/src/scxml/qscxmldatamodel.cpp b/src/scxml/qscxmldatamodel.cpp
index 570289d..bf84ef8 100644
--- a/src/scxml/qscxmldatamodel.cpp
+++ b/src/scxml/qscxmldatamodel.cpp
@@ -45,13 +45,26 @@
 QT_BEGIN_NAMESPACE
 
 /*!
- * \class QScxmlDataModel::ForeachLoopBody
- * \internal
+  \class QScxmlDataModel::ForeachLoopBody
+  \brief The ForeachLoopBody class represents a function to be executed on
+  each iteration of an SCXML foreach loop.
+  \since 5.8
+  \inmodule QtScxml
  */
 
+/*!
+  Destroys a ForeachLoopBody
+ */
 QScxmlDataModel::ForeachLoopBody::~ForeachLoopBody()
 {}
 
+/*!
+  \fn QScxmlDataModel::ForeachLoopBody::run(bool *ok)
+
+  Function to be executed on each iteration. If the execution fails \a ok is
+  set to \c false, otherwise it is set to \c true.
+ */
+
 /*!
  * \class QScxmlDataModel
  * \brief The QScxmlDataModel class is the data model base class for a Qt SCXML
@@ -89,7 +102,8 @@ QScxmlDataModel::QScxmlDataModel(QObject *parent)
 }
 
 /*!
- * \internal
+  Creates a new QScxmlDataModel from a private object \a dd with parent
+  object \a parent.
  */
 QScxmlDataModel::QScxmlDataModel(QScxmlDataModelPrivate &dd, QObject *parent) :
     QObject(dd, parent)
@@ -184,4 +198,59 @@ QScxmlDataModel *QScxmlDataModelPrivate::instantiateDataModel(DocumentModel::Scx
  * Returns \c true if successful or \c false if an error occurred.
  */
 
+/*!
+ * \fn QScxmlDataModel::evaluateToString(
+ *           QScxmlExecutableContent::EvaluatorId id, bool *ok)
+ * Evaluates the executable content pointed to by \a id, and sets \a ok to
+ * \c false if there was an error, or to \c true if there wasn't.
+ * Returns the result of the evaluation as a QString.
+ */
+
+/*!
+ * \fn QScxmlDataModel::evaluateToBool(QScxmlExecutableContent::EvaluatorId id,
+ *                                     bool *ok)
+ * Evaluates the executable content pointed to by \a id, and sets \a ok to
+ * \c false if there was an error, or to \c true if there wasn't.
+ * Returns the result of the evaluation as a bool.
+ */
+
+/*!
+ * \fn QScxmlDataModel::evaluateToVariant(
+ *           QScxmlExecutableContent::EvaluatorId id, bool *ok)
+ * Evaluates the executable content pointed to by \a id, and sets \a ok to
+ * \c false if there was an error, or to \c true if there wasn't.
+ * Returns the result of the evaluation as a QVariant.
+ */
+
+/*!
+ * \fn QScxmlDataModel::evaluateToVoid(QScxmlExecutableContent::EvaluatorId id,
+ *                                     bool *ok)
+ * Evaluates the executable content pointed to by \a id, and sets \a ok to
+ * \c false if there was an error, or to \c true if there wasn't.
+ * The execution is expected to return no result.
+ */
+
+/*!
+ * \fn QScxmlDataModel::evaluateAssignment(
+ *           QScxmlExecutableContent::EvaluatorId id, bool *ok)
+ * Evaluates the assignement pointed to by \a id, and sets \a ok to
+ * \c false if there was an error, or to \c true if there wasn't.
+ */
+
+/*!
+ * \fn QScxmlDataModel::evaluateInitialization(
+ *           QScxmlExecutableContent::EvaluatorId id, bool *ok)
+ * Evaluates the initialization pointed to by \a id, and sets \a ok to
+ * \c false if there was an error, or to \c true if there wasn't.
+ */
+
+/*!
+ * \fn QScxmlDataModel::evaluateForeach(
+ *           QScxmlExecutableContent::EvaluatorId id, bool *ok,
+ *           ForeachLoopBody *body)
+ * Evaluates the foreach loop pointed to by \a id, and sets \a ok to
+ * \c false if there was an error, or to \c true if there wasn't. The
+ * \a body is executed on each iteration.
+ */
+
 QT_END_NAMESPACE
diff --git a/src/scxml/qscxmldatamodel.h b/src/scxml/qscxmldatamodel.h
index e16f2f7..d34a84a 100644
--- a/src/scxml/qscxmldatamodel.h
+++ b/src/scxml/qscxmldatamodel.h
@@ -75,7 +75,6 @@ public:
 
     Q_INVOKABLE virtual bool setup(const QVariantMap &initialDataValues) = 0;
 
-#ifndef Q_QDOC
     virtual QString evaluateToString(QScxmlExecutableContent::EvaluatorId id, bool *ok) = 0;
     virtual bool evaluateToBool(QScxmlExecutableContent::EvaluatorId id, bool *ok) = 0;
     virtual QVariant evaluateToVariant(QScxmlExecutableContent::EvaluatorId id, bool *ok) = 0;
@@ -83,7 +82,6 @@ public:
     virtual void evaluateAssignment(QScxmlExecutableContent::EvaluatorId id, bool *ok) = 0;
     virtual void evaluateInitialization(QScxmlExecutableContent::EvaluatorId id, bool *ok) = 0;
     virtual void evaluateForeach(QScxmlExecutableContent::EvaluatorId id, bool *ok, ForeachLoopBody *body) = 0;
-#endif // Q_QDOC
 
     virtual void setScxmlEvent(const QScxmlEvent &event) = 0;
 
diff --git a/src/scxml/qscxmlecmascriptdatamodel.cpp b/src/scxml/qscxmlecmascriptdatamodel.cpp
index 869afec..e517989 100644
--- a/src/scxml/qscxmlecmascriptdatamodel.cpp
+++ b/src/scxml/qscxmlecmascriptdatamodel.cpp
@@ -393,7 +393,11 @@ bool QScxmlEcmaScriptDataModel::setup(const QVariantMap &initialDataValues)
     return ok;
 }
 
-QString QScxmlEcmaScriptDataModel::evaluateToString(EvaluatorId id, bool *ok)
+/*!
+  \reimp
+ */
+QString QScxmlEcmaScriptDataModel::evaluateToString(QScxmlExecutableContent::EvaluatorId id,
+                                                    bool *ok)
 {
     Q_D(QScxmlEcmaScriptDataModel);
     const EvaluatorInfo &info = d->m_stateMachine->tableData()->evaluatorInfo(id);
@@ -401,7 +405,11 @@ QString QScxmlEcmaScriptDataModel::evaluateToString(EvaluatorId id, bool *ok)
     return d->evalStr(d->string(info.expr), d->string(info.context), ok);
 }
 
-bool QScxmlEcmaScriptDataModel::evaluateToBool(EvaluatorId id, bool *ok)
+/*!
+  \reimp
+ */
+bool QScxmlEcmaScriptDataModel::evaluateToBool(QScxmlExecutableContent::EvaluatorId id,
+                                               bool *ok)
 {
     Q_D(QScxmlEcmaScriptDataModel);
     const EvaluatorInfo &info = d->m_stateMachine->tableData()->evaluatorInfo(id);
@@ -409,7 +417,11 @@ bool QScxmlEcmaScriptDataModel::evaluateToBool(EvaluatorId id, bool *ok)
     return d->evalBool(d->string(info.expr), d->string(info.context), ok);
 }
 
-QVariant QScxmlEcmaScriptDataModel::evaluateToVariant(EvaluatorId id, bool *ok)
+/*!
+  \reimp
+ */
+QVariant QScxmlEcmaScriptDataModel::evaluateToVariant(QScxmlExecutableContent::EvaluatorId id,
+                                                      bool *ok)
 {
     Q_D(QScxmlEcmaScriptDataModel);
     const EvaluatorInfo &info = d->m_stateMachine->tableData()->evaluatorInfo(id);
@@ -417,7 +429,11 @@ QVariant QScxmlEcmaScriptDataModel::evaluateToVariant(EvaluatorId id, bool *ok)
     return d->evalJSValue(d->string(info.expr), d->string(info.context), ok).toVariant();
 }
 
-void QScxmlEcmaScriptDataModel::evaluateToVoid(EvaluatorId id, bool *ok)
+/*!
+  \reimp
+ */
+void QScxmlEcmaScriptDataModel::evaluateToVoid(QScxmlExecutableContent::EvaluatorId id,
+                                               bool *ok)
 {
     Q_D(QScxmlEcmaScriptDataModel);
     const EvaluatorInfo &info = d->m_stateMachine->tableData()->evaluatorInfo(id);
@@ -425,7 +441,11 @@ void QScxmlEcmaScriptDataModel::evaluateToVoid(EvaluatorId id, bool *ok)
     d->eval(d->string(info.expr), d->string(info.context), ok);
 }
 
-void QScxmlEcmaScriptDataModel::evaluateAssignment(EvaluatorId id, bool *ok)
+/*!
+  \reimp
+ */
+void QScxmlEcmaScriptDataModel::evaluateAssignment(QScxmlExecutableContent::EvaluatorId id,
+                                                   bool *ok)
 {
     Q_D(QScxmlEcmaScriptDataModel);
     Q_ASSERT(ok);
@@ -445,7 +465,11 @@ void QScxmlEcmaScriptDataModel::evaluateAssignment(EvaluatorId id, bool *ok)
     }
 }
 
-void QScxmlEcmaScriptDataModel::evaluateInitialization(EvaluatorId id, bool *ok)
+/*!
+  \reimp
+ */
+void QScxmlEcmaScriptDataModel::evaluateInitialization(QScxmlExecutableContent::EvaluatorId id,
+                                                       bool *ok)
 {
     Q_D(QScxmlEcmaScriptDataModel);
     const AssignmentInfo &info = d->m_stateMachine->tableData()->assignmentInfo(id);
@@ -458,7 +482,11 @@ void QScxmlEcmaScriptDataModel::evaluateInitialization(EvaluatorId id, bool *ok)
     evaluateAssignment(id, ok);
 }
 
-void QScxmlEcmaScriptDataModel::evaluateForeach(EvaluatorId id, bool *ok, ForeachLoopBody *body)
+/*!
+  \reimp
+ */
+void QScxmlEcmaScriptDataModel::evaluateForeach(QScxmlExecutableContent::EvaluatorId id, bool *ok,
+                                                ForeachLoopBody *body)
 {
     Q_D(QScxmlEcmaScriptDataModel);
     Q_ASSERT(ok);
diff --git a/src/scxml/qscxmlecmascriptdatamodel.h b/src/scxml/qscxmlecmascriptdatamodel.h
index 81041c7..7c22044 100644
--- a/src/scxml/qscxmlecmascriptdatamodel.h
+++ b/src/scxml/qscxmlecmascriptdatamodel.h
@@ -55,7 +55,6 @@ public:
 
     Q_INVOKABLE bool setup(const QVariantMap &initialDataValues) Q_DECL_OVERRIDE;
 
-#ifndef Q_QDOC
     QString evaluateToString(QScxmlExecutableContent::EvaluatorId id, bool *ok) Q_DECL_OVERRIDE Q_DECL_FINAL;
     bool evaluateToBool(QScxmlExecutableContent::EvaluatorId id, bool *ok) Q_DECL_OVERRIDE Q_DECL_FINAL;
     QVariant evaluateToVariant(QScxmlExecutableContent::EvaluatorId id, bool *ok) Q_DECL_OVERRIDE Q_DECL_FINAL;
@@ -63,7 +62,6 @@ public:
     void evaluateAssignment(QScxmlExecutableContent::EvaluatorId id, bool *ok) Q_DECL_OVERRIDE Q_DECL_FINAL;
     void evaluateInitialization(QScxmlExecutableContent::EvaluatorId id, bool *ok) Q_DECL_OVERRIDE Q_DECL_FINAL;
     void evaluateForeach(QScxmlExecutableContent::EvaluatorId id, bool *ok, ForeachLoopBody *body) Q_DECL_OVERRIDE Q_DECL_FINAL;
-#endif // Q_QDOC
 
     void setScxmlEvent(const QScxmlEvent &event) Q_DECL_OVERRIDE;
 
diff --git a/src/scxml/qscxmlexecutablecontent.cpp b/src/scxml/qscxmlexecutablecontent.cpp
index 9fbcd15..bbe304d 100644
--- a/src/scxml/qscxmlexecutablecontent.cpp
+++ b/src/scxml/qscxmlexecutablecontent.cpp
@@ -46,6 +46,175 @@ QT_BEGIN_NAMESPACE
 
 using namespace QScxmlExecutableContent;
 
+/*!
+    \namespace QScxmlExecutableContent
+    \inmodule QtScxml
+    \since 5.8
+    \brief The QScxmlExecutableContent namespace contains various types used
+    to interpret executable content in state machines.
+ */
+
+/*!
+    \typedef QScxmlExecutableContent::ContainerId
+    \inmodule QtScxml
+    \since 5.8
+    \brief ID for a container holding executable content
+ */
+
+/*!
+    \typedef QScxmlExecutableContent::EvaluatorId
+    \inmodule QtScxml
+    \since 5.8
+    \brief ID for a unit of executable content
+ */
+
+/*!
+    \typedef QScxmlExecutableContent::InstructionId
+    \inmodule QtScxml
+    \since 5.8
+    \brief ID for an instruction of executable content
+ */
+
+/*!
+    \typedef QScxmlExecutableContent::StringId
+    \inmodule QtScxml
+    \since 5.8
+    \brief ID for a string contained in executable content
+ */
+
+/*!
+    \class QScxmlExecutableContent::EvaluatorInfo
+    \brief Representation of a unit of executable content
+    \since 5.8
+    \inmodule QtScxml
+ */
+
+/*!
+    \variable QScxmlExecutableContent::EvaluatorInfo::expr
+    \brief Expression to be evaluated
+ */
+
+/*!
+    \variable QScxmlExecutableContent::EvaluatorInfo::context
+    \brief Context for evaluating the expression
+ */
+
+/*!
+    \class QScxmlExecutableContent::AssignmentInfo
+    \brief Representation of a data assignment
+    \since 5.8
+    \inmodule QtScxml
+ */
+
+/*!
+    \variable QScxmlExecutableContent::AssignmentInfo::expr
+    \brief Expression to be evaluated
+ */
+
+/*!
+    \variable QScxmlExecutableContent::AssignmentInfo::context
+    \brief Context for evaluating the expression
+ */
+
+/*!
+    \variable QScxmlExecutableContent::AssignmentInfo::dest
+    \brief Name of the data item to assign to
+ */
+
+/*!
+    \class QScxmlExecutableContent::ForeachInfo
+    \brief Representation of a foreach construct
+    \since 5.8
+    \inmodule QtScxml
+ */
+
+/*!
+    \variable QScxmlExecutableContent::ForeachInfo::array
+    \brief Name of the array we are iterating over
+ */
+
+/*!
+    \variable QScxmlExecutableContent::ForeachInfo::item
+    \brief Name of the iteration variable
+ */
+
+/*!
+    \variable QScxmlExecutableContent::ForeachInfo::index
+    \brief Name of the index variable
+ */
+
+/*!
+    \variable QScxmlExecutableContent::ForeachInfo::context
+    \brief Context for evaluating the expression
+ */
+
+/*!
+    \class QScxmlExecutableContent::ParameterInfo
+    \brief Representation of a parameter to a service invocation
+    \since 5.8
+    \inmodule QtScxml
+ */
+
+/*!
+    \variable QScxmlExecutableContent::ParameterInfo::name
+    \brief Name of the parameter
+ */
+
+/*!
+    \variable QScxmlExecutableContent::ParameterInfo::expr
+    \brief Expression to be evaluated
+ */
+
+/*!
+    \variable QScxmlExecutableContent::ParameterInfo::location
+    \brief Data model name of the item to be passed as parameter
+ */
+
+/*!
+    \class QScxmlExecutableContent::InvokeInfo
+    \brief Representation of a service invocation
+    \since 5.8
+    \inmodule QtScxml
+ */
+
+/*!
+    \variable QScxmlExecutableContent::InvokeInfo::id
+    \brief the ID specified by the id attribute in the invoke element
+ */
+
+/*!
+    \variable QScxmlExecutableContent::InvokeInfo::prefix
+    \brief Unique prefix for this invocation in the context of the state from
+    which it is called
+ */
+
+/*!
+    \variable QScxmlExecutableContent::InvokeInfo::location
+    \brief Data model location to write the invocation ID to
+ */
+
+/*!
+    \variable QScxmlExecutableContent::InvokeInfo::context
+    \brief The context to interpret the location in
+ */
+
+/*!
+    \variable QScxmlExecutableContent::InvokeInfo::expr
+    \brief The expression representing the srcexpr of the invoke element
+ */
+
+/*!
+    \variable QScxmlExecutableContent::InvokeInfo::finalize
+    \brief An ID of a container of executable content to be run on finalizing the invocation
+ */
+
+/*!
+    \variable QScxmlExecutableContent::InvokeInfo::autoforward
+    \brief Whether events should automatically be forwarded to the invoked
+    service
+ */
+
+
 #ifndef BUILD_QSCXMLC
 static int parseTime(const QString &t, bool *ok = 0)
 {
diff --git a/src/scxml/qscxmlexecutablecontent_p.h b/src/scxml/qscxmlexecutablecontent_p.h
index 98461fe..cfaec55 100644
--- a/src/scxml/qscxmlexecutablecontent_p.h
+++ b/src/scxml/qscxmlexecutablecontent_p.h
@@ -61,6 +61,7 @@
 #include <QtScxml/qscxmlstatemachine.h>
 #endif // BUILD_QSCXMLC
 
+#ifndef Q_QDOC
 QT_BEGIN_NAMESPACE
 
 namespace QScxmlExecutableContent {
@@ -509,5 +510,6 @@ private:
 };
 
 QT_END_NAMESPACE
+#endif // Q_QDOC
 
 #endif // QSCXMLEXECUTABLECONTENT_P_H
diff --git a/src/scxml/qscxmlinvokableservice.cpp b/src/scxml/qscxmlinvokableservice.cpp
index 9dfda21..35cd924 100644
--- a/src/scxml/qscxmlinvokableservice.cpp
+++ b/src/scxml/qscxmlinvokableservice.cpp
@@ -43,6 +43,111 @@
 
 QT_BEGIN_NAMESPACE
 
+/*!
+ * \class QScxmlInvokableService
+ * \brief Service invoked from \l{SCXML Specification}{SCXML}
+ * \since 5.8
+ * \inmodule QtScxml
+ *
+ * QScxmlInvokableService is the base class for services called from state
+ * machines via the mechanism described in
+ * \l {SCXML Specification - 6.4 <invoke>}. This represents an actual instance
+ * of an invoked service.
+ */
+
+/*!
+ * \class QScxmlInvokableServiceFactory
+ * \brief Factory for creating instances of QScxmlInvokableService
+ * \since 5.8
+ * \inmodule QtScxml
+ *
+ * A factory for creating instances of QScxmlInvokableService. This reperesents
+ * an \c <invoke> element in the SCXML document. Each time the service is
+ * actually invoked a new instance of QScxmlInvokableService is created.
+ */
+
+/*!
+  \property QScxmlInvokableServiceFactory::invokeInfo
+
+  The QScxmlExecutableContent::InvokeInfo passed to the constructor.
+ */
+
+/*!
+  \property QScxmlInvokableServiceFactory::names
+
+  The QVector<QScxmlExecutableContent::StringId> of names passed to the
+  constructor.
+ */
+
+/*!
+  \property QScxmlInvokableServiceFactory::parameters
+
+  The QVector<QScxmlExecutableContent::ParameterInfo> passed to the
+  constructor.
+ */
+
+/*!
+ * \class QScxmlStaticScxmlServiceFactory
+ * \brief Factory for creating QScxmlScxmlService instances from precompiled
+ *        documents
+ * \since 5.8
+ * \inmodule QtScxml
+ *
+ * A factory for instantiating QScxmlStateMachines from files known at compile
+ * time, that is files specified via the \c src attribute in \c <invoke>
+ */
+
+/*!
+ * \class QScxmlDynamicScxmlServiceFactory
+ * \brief Factory for QScxmlScxmlService instances created from documents
+ *        loaded at run time
+ * \since 5.8
+ * \inmodule QtScxml
+ *
+ * A QScxmlScxmlServiceFactory for creating dynamically resolved services. This
+ * is used when loading \l{SCXML Specification}{SCXML} content from files a
+ * parent state machine requests at runtime, via the \c srcexpr attribute in
+ * \c <invoke>.
+ */
+
+/*!
+ * \property QScxmlInvokableService::parentStateMachine
+ *
+ * The QScxmlStateMachine that invoked the service.
+ */
+
+/*!
+ * \property QScxmlInvokableService::id
+ *
+ * The id specified in the \c id attribute of the \c <invoke> element.
+ */
+
+/*!
+ * \property QScxmlInvokableService::name
+ *
+ * The name of the service being invoked.
+ */
+
+/*!
+ * \fn QScxmlInvokableService::postEvent(QScxmlEvent *event)
+ *
+ * Sends an \a event to the service.
+ */
+
+/*!
+ * \fn QScxmlInvokableService::start()
+ *
+ * Starts the invokable service. Returns \c true on success, or \c false if the
+ * invocation fails.
+ */
+
+/*!
+ * \fn QScxmlInvokableServiceFactory::invoke(QScxmlStateMachine *parentStateMachine)
+ *
+ * Invoke the service with the parameters given in the contructor, passing
+ * \a parentStateMachine as parent. Returns the new QScxmlInvokableService.
+ */
+
 QScxmlInvokableServicePrivate::QScxmlInvokableServicePrivate(QScxmlStateMachine *parentStateMachine)
     : parentStateMachine(parentStateMachine)
 {
@@ -216,6 +321,10 @@ QScxmlScxmlService::~QScxmlScxmlService()
     delete stateMachine;
 }
 
+/*!
+  Create a QScxmlScxmlService wrapping \a stateMachine, invoked from
+  \a parentStateMachine, as child of \a parent.
+ */
 QScxmlScxmlService::QScxmlScxmlService(QScxmlStateMachine *stateMachine,
                                        QScxmlStateMachine *parentStateMachine,
                                        QScxmlInvokableServiceFactory *factory)
@@ -224,6 +333,9 @@ QScxmlScxmlService::QScxmlScxmlService(QScxmlStateMachine *stateMachine,
     QScxmlStateMachinePrivate::get(stateMachine)->m_parentStateMachine = parentStateMachine;
 }
 
+/*!
+ * \reimp
+ */
 bool QScxmlScxmlService::start()
 {
     Q_D(QScxmlInvokableService);
@@ -254,21 +366,36 @@ bool QScxmlScxmlService::start()
     return false;
 }
 
+/*!
+  \reimp
+ */
 QString QScxmlScxmlService::id() const
 {
     return stateMachine->sessionId();
 }
 
+/*!
+  \reimp
+ */
 QString QScxmlScxmlService::name() const
 {
     return stateMachine->name();
 }
 
+/*!
+  \reimp
+ */
 void QScxmlScxmlService::postEvent(QScxmlEvent *event)
 {
     QScxmlStateMachinePrivate::get(stateMachine)->postEvent(event);
 }
 
+/*!
+  Create a QScxmlDynamicScxmlServiceFactory, passing the attributes of the
+  \c <invoke> element as \a invokeInfo, any \c <param> child elements as
+  \a parameters, the content of the \c names attribute as \a names, and the
+  QObject parent \a parent.
+ */
 QScxmlDynamicScxmlServiceFactory::QScxmlDynamicScxmlServiceFactory(
         const QScxmlExecutableContent::InvokeInfo &invokeInfo,
         const QVector<QScxmlExecutableContent::StringId> &names,
@@ -277,6 +404,9 @@ QScxmlDynamicScxmlServiceFactory::QScxmlDynamicScxmlServiceFactory(
     : QScxmlInvokableServiceFactory(invokeInfo, names, parameters, parent)
 {}
 
+/*!
+  \reimp
+ */
 QScxmlInvokableService *QScxmlDynamicScxmlServiceFactory::invoke(
         QScxmlStateMachine *parentStateMachine)
 {
@@ -299,6 +429,9 @@ QScxmlStaticScxmlServiceFactory::QScxmlStaticScxmlServiceFactory(
 {
 }
 
+/*!
+  \reimp
+ */
 QScxmlInvokableService *QScxmlStaticScxmlServiceFactory::invoke(
         QScxmlStateMachine *parentStateMachine)
 {
diff --git a/src/scxml/qscxmlnulldatamodel.cpp b/src/scxml/qscxmlnulldatamodel.cpp
index d7b64d0..d3e9942 100644
--- a/src/scxml/qscxmlnulldatamodel.cpp
+++ b/src/scxml/qscxmlnulldatamodel.cpp
@@ -122,19 +122,22 @@ private:
  * This class implements the null data model as described in the
  * \l {SCXML Specification - B.1 The Null Data Model}. Using the value \c "null"
  * for the \e datamodel attribute of the \c <scxml> element means that there is
- * no underlying data model.
+ * no underlying data model, but some executable content, like \c In(...) or
+ * \c <log> can still be used.
  *
  * \sa QScxmlStateMachine QScxmlDataModel
  */
 
 /*!
- * Creates a new Qt SCXML data model, with the parent object \a parent.
+ * Creates a new Qt SCXML null data model, with the parent object \a parent.
  */
 QScxmlNullDataModel::QScxmlNullDataModel(QObject *parent)
     : QScxmlDataModel(*(new QScxmlNullDataModelPrivate), parent)
 {}
 
-/*! \internal */
+/*!
+  Destroys the data model.
+ */
 QScxmlNullDataModel::~QScxmlNullDataModel()
 {
 }
@@ -149,6 +152,13 @@ bool QScxmlNullDataModel::setup(const QVariantMap &initialDataValues)
     return true;
 }
 
+/*!
+  \reimp
+  Evaluates the executable content pointed to by \a id, and records in \a ok
+  if there was an error. returns the result of the evaluation as a string. The
+  null data model can evaluate "<log>", so this might result in an actual
+  value, rather than an error
+ */
 QString QScxmlNullDataModel::evaluateToString(QScxmlExecutableContent::EvaluatorId id, bool *ok)
 {
     Q_D(QScxmlNullDataModel);
@@ -160,12 +170,25 @@ QString QScxmlNullDataModel::evaluateToString(QScxmlExecutableContent::Evaluator
     return td->string(info.expr);
 }
 
+/*!
+  \reimp
+  Evaluates the executable content pointed to by \a id, and records in \a ok
+  if there was an error. returns the result of the evaluation as a bool. The
+  null data model can evaluate the instruction "In(...)", so this might result
+  in an actual value, rather than an error.
+ */
 bool QScxmlNullDataModel::evaluateToBool(QScxmlExecutableContent::EvaluatorId id, bool *ok)
 {
     Q_D(QScxmlNullDataModel);
     return d->evalBool(id, ok);
 }
 
+/*!
+  \reimp
+  Evaluates the executable content pointed to by \a id, and records in \a ok
+  if there was an error. As this is the null data model, any evaluation will in
+  fact result in an error, with \a ok set to \c false. Returns an empty QVariant.
+ */
 QVariant QScxmlNullDataModel::evaluateToVariant(QScxmlExecutableContent::EvaluatorId id, bool *ok)
 {
     Q_UNUSED(id);
@@ -176,6 +199,12 @@ QVariant QScxmlNullDataModel::evaluateToVariant(QScxmlExecutableContent::Evaluat
     return QVariant();
 }
 
+/*!
+  \reimp
+  Evaluates the executable content pointed to by \a id, and records in \a ok
+  if there was an error. As this is the null data model, any evaluation will in
+  fact result in an error, with \a ok set to \c false.
+ */
 void QScxmlNullDataModel::evaluateToVoid(QScxmlExecutableContent::EvaluatorId id, bool *ok)
 {
     Q_UNUSED(id);
@@ -185,6 +214,11 @@ void QScxmlNullDataModel::evaluateToVoid(QScxmlExecutableContent::EvaluatorId id
                 QStringLiteral("Cannot evaluate expressions on a null data model"));
 }
 
+/*!
+  \reimp
+  Throws an error and sets \a ok to \c false because the null data model cannot evaluate
+  assignments.
+ */
 void QScxmlNullDataModel::evaluateAssignment(QScxmlExecutableContent::EvaluatorId id, bool *ok)
 {
     Q_UNUSED(id);
@@ -194,6 +228,10 @@ void QScxmlNullDataModel::evaluateAssignment(QScxmlExecutableContent::EvaluatorI
                 QStringLiteral("Cannot assign values on a null data model"));
 }
 
+/*!
+  \reimp
+  Throws an error and sets \a ok to \c false because the null data model cannot initialize data.
+ */
 void QScxmlNullDataModel::evaluateInitialization(QScxmlExecutableContent::EvaluatorId id, bool *ok)
 {
     Q_UNUSED(id);
@@ -203,7 +241,13 @@ void QScxmlNullDataModel::evaluateInitialization(QScxmlExecutableContent::Evalua
                 QStringLiteral("Cannot initialize values on a null data model"));
 }
 
-void QScxmlNullDataModel::evaluateForeach(QScxmlExecutableContent::EvaluatorId id, bool *ok, ForeachLoopBody *body)
+/*!
+  \reimp
+  Throws an error and sets \a ok to \c false because the null data model cannot evaluate <foreach>
+  blocks.
+ */
+void QScxmlNullDataModel::evaluateForeach(QScxmlExecutableContent::EvaluatorId id, bool *ok,
+                                          ForeachLoopBody *body)
 {
     Q_UNUSED(id);
     Q_UNUSED(body);
@@ -215,6 +259,7 @@ void QScxmlNullDataModel::evaluateForeach(QScxmlExecutableContent::EvaluatorId i
 
 /*!
  * \reimp
+ * Does not actually set the \a event, because the null data model does not handle events.
  */
 void QScxmlNullDataModel::setScxmlEvent(const QScxmlEvent &event)
 {
diff --git a/src/scxml/qscxmlnulldatamodel.h b/src/scxml/qscxmlnulldatamodel.h
index 098adcf..830162f 100644
--- a/src/scxml/qscxmlnulldatamodel.h
+++ b/src/scxml/qscxmlnulldatamodel.h
@@ -55,7 +55,6 @@ public:
 
     Q_INVOKABLE bool setup(const QVariantMap &initialDataValues) Q_DECL_OVERRIDE;
 
-#ifndef Q_QDOC
     QString evaluateToString(QScxmlExecutableContent::EvaluatorId id, bool *ok) Q_DECL_OVERRIDE Q_DECL_FINAL;
     bool evaluateToBool(QScxmlExecutableContent::EvaluatorId id, bool *ok) Q_DECL_OVERRIDE Q_DECL_FINAL;
     QVariant evaluateToVariant(QScxmlExecutableContent::EvaluatorId id, bool *ok) Q_DECL_OVERRIDE Q_DECL_FINAL;
@@ -63,7 +62,6 @@ public:
     void evaluateAssignment(QScxmlExecutableContent::EvaluatorId id, bool *ok) Q_DECL_OVERRIDE Q_DECL_FINAL;
     void evaluateInitialization(QScxmlExecutableContent::EvaluatorId id, bool *ok) Q_DECL_OVERRIDE Q_DECL_FINAL;
     void evaluateForeach(QScxmlExecutableContent::EvaluatorId id, bool *ok, ForeachLoopBody *body) Q_DECL_OVERRIDE Q_DECL_FINAL;
-#endif // Q_QDOC
 
     void setScxmlEvent(const QScxmlEvent &event) Q_DECL_OVERRIDE;
 
diff --git a/src/scxml/qscxmlstatemachine.cpp b/src/scxml/qscxmlstatemachine.cpp
index d71755b..41d47ba 100644
--- a/src/scxml/qscxmlstatemachine.cpp
+++ b/src/scxml/qscxmlstatemachine.cpp
@@ -589,21 +589,21 @@ void QScxmlStateMachinePrivate::submitDelayedEvent(QScxmlEvent *event)
 }
 
 /*!
- * \internal
- * \brief Submits an error event to the external event queue of this state machine.
+ * Submits an error event to the external event queue of this state machine.
  *
- * \param type The error message type, e.g. "error.execution". The type has to start with "error.".
- * \param msg A string describing the nature of the error. This is passed to the event as the
- *            errorMessage
- * \param sendid The sendid of the message causing the error, if it has one.
+ * The error is of \a type, e.g. "error.execution". The type has to start with "error.". An
+ * \a message is specified, describing the nature of the error. This is passed to the event as the
+ * \c errorMessage property. The \a sendId of the message causing the error is specified, if it has
+ * one.
  */
-void QScxmlStateMachinePrivate::submitError(const QString &type, const QString &msg, const QString &sendid)
+void QScxmlStateMachinePrivate::submitError(const QString &type, const QString &message,
+                                            const QString &sendId)
 {
     Q_Q(QScxmlStateMachine);
-    qCDebug(qscxmlLog) << q << "had error" << type << ":" << msg;
+    qCDebug(qscxmlLog) << q << "had error" << type << ":" << message;
     if (!type.startsWith(QStringLiteral("error.")))
         qCWarning(qscxmlLog) << q << "Message type of error message does not start with 'error.'!";
-    q->submitEvent(QScxmlEventBuilder::errorEvent(q, type, msg, sendid));
+    q->submitEvent(QScxmlEventBuilder::errorEvent(q, type, message, sendId));
 }
 
 void QScxmlStateMachinePrivate::start()
@@ -2067,6 +2067,13 @@ void QScxmlStateMachine::stop()
     d->pause();
 }
 
+/*!
+  Returns \c true if the state with ID \a stateIndex is active.
+
+  This method is part of the interface to the compiled representation of SCXML
+  state machines. It should only be used internally and by state machines
+  compiled from SCXML documents.
+ */
 bool QScxmlStateMachine::isActive(int stateIndex) const
 {
     Q_D(const QScxmlStateMachine);
diff --git a/src/scxml/qscxmlstatemachine.h b/src/scxml/qscxmlstatemachine.h
index da8de50..d4435f7 100644
--- a/src/scxml/qscxmlstatemachine.h
+++ b/src/scxml/qscxmlstatemachine.h
@@ -78,10 +78,8 @@ class Q_SCXML_EXPORT QScxmlStateMachine: public QObject
     Q_PROPERTY(QScxmlTableData *tableData READ tableData WRITE setTableData NOTIFY tableDataChanged)
 
 protected:
-#ifndef Q_QDOC
     explicit QScxmlStateMachine(const QMetaObject *metaObject, QObject *parent = nullptr);
     QScxmlStateMachine(QScxmlStateMachinePrivate &dd, QObject *parent = nullptr);
-#endif // Q_QDOC
 
 public:
     static QScxmlStateMachine *fromFile(const QString &fileName);
@@ -341,10 +339,8 @@ protected: // methods for friends:
     friend class QScxmlInvokableServicePrivate;
     friend class QScxmlExecutionEngine;
 
-#ifndef Q_QDOC
     // The methods below are used by the compiled state machines.
     bool isActive(int stateIndex) const;
-#endif // Q_QDOC
 
 private:
     QMetaObject::Connection connectToStateImpl(const QString &scxmlStateName,
diff --git a/src/scxml/qscxmltabledata.cpp b/src/scxml/qscxmltabledata.cpp
index 2457840..fc2bbb7 100644
--- a/src/scxml/qscxmltabledata.cpp
+++ b/src/scxml/qscxmltabledata.cpp
@@ -43,6 +43,75 @@
 
 QT_USE_NAMESPACE
 
+/*!
+    \class QScxmlTableData
+    \since 5.8
+    \inmodule QtScxml
+    \brief The QScxmlTableData class is used by compiled state machines.
+
+    QScxmlTableData is the interface to the compiled representation of SCXML
+    state machines. It should only be used internally and by state machines
+    compiled from SCXML documents.
+ */
+
+/*!
+    \fn QScxmlTableData::string(QScxmlExecutableContent::StringId id) const
+    Returns a QString for the given \a id.
+ */
+
+/*!
+    \fn QScxmlTableData::instructions() const
+    Returns a pointer to the instructions of executable content contained in
+    the state machine.
+ */
+
+/*!
+    \fn QScxmlTableData::evaluatorInfo(QScxmlExecutableContent::EvaluatorId evaluatorId) const
+    Returns the QScxmlExecutableContent::EvaluatorInfo object for the given \a evaluatorId.
+ */
+
+/*!
+    \fn QScxmlTableData::assignmentInfo(QScxmlExecutableContent::EvaluatorId assignmentId) const
+    Returns the QScxmlExecutableContent::AssignmentInfo object for the given \a assignmentId.
+ */
+
+/*!
+    \fn QScxmlTableData::foreachInfo(QScxmlExecutableContent::EvaluatorId foreachId) const
+    Returns the QScxmlExecutableContent::ForeachInfo object for the given \a foreachId.
+ */
+
+/*!
+    \fn QScxmlTableData::dataNames(int *count) const
+    Retrieves the string IDs for names of data items in the data model. The
+    number of strings is saved into \a count and a pointer to an array of
+    string IDs is returned.
+
+    Returns a pointer to an array of string IDs.
+ */
+
+/*!
+    \fn QScxmlTableData::initialSetup() const
+    Initializes the table data. Returns the ID of the container with
+    instructions to be executed when initializing the state machine.
+ */
+
+/*!
+    \fn QScxmlTableData::name() const
+    Returns the name of the state machine.
+ */
+
+/*!
+    \fn QScxmlTableData::stateMachineTable() const
+    Returns a pointer to the complete state table, expressed as an opaque
+    sequence of integers.
+ */
+
+/*!
+    \fn QScxmlTableData::serviceFactory(int id) const
+    Returns the service factory that creates invokable services for the state
+    with the ID \a id.
+ */
+
 using namespace QScxmlInternal;
 
 namespace {
@@ -898,6 +967,10 @@ private:
 
 } // anonymous namespace
 
+/*!
+    \fn QScxmlTableData::~QScxmlTableData()
+    Destroys a QScxmlTableData.
+ */
 QScxmlTableData::~QScxmlTableData()
 {}
 
-- 
cgit v1.2.3