Doc: Edit the docs for grammar and style

Fix an external link and add \brief commands for properties.

Change-Id: I84477f0cfddb27bbb4d807f8f1b000601af245c9
Reviewed-by: Ulf Hermann <ulf.hermann@qt.io>

8 files changed, 117 insertions, 105 deletions

diff --git a/src/scxml/doc/external-resources.qdoc b/src/scxml/doc/external-resources.qdoc
index 3cbdc6f..39a1c3b 100644
--- a/src/scxml/doc/external-resources.qdoc
+++ b/src/scxml/doc/external-resources.qdoc
@@ -45,6 +45,11 @@
 */
 
 /*!
+    \externalpage https://www.w3.org/TR/scxml/#invoke
+    \title SCXML Specification - 6.4 <invoke>
+*/
+
+/*!
     \externalpage https://www.w3.org/TR/scxml/#minimal-profile
     \title SCXML Specification - B.1 The Null Data Model
 */
diff --git a/src/scxml/qscxmlcppdatamodel.cpp b/src/scxml/qscxmlcppdatamodel.cpp
index 23a7392..ba18cc7 100644
--- a/src/scxml/qscxmlcppdatamodel.cpp
+++ b/src/scxml/qscxmlcppdatamodel.cpp
@@ -150,7 +150,7 @@ bool QScxmlCppDataModel::setup(const QVariantMap &initialDataValues)
 /*!
   \reimp
 
-  This method doesn't perform any action, ignores \a id, and sets \a ok to
+  This method does not 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>.
  */
@@ -163,7 +163,7 @@ void QScxmlCppDataModel::evaluateAssignment(QScxmlExecutableContent::EvaluatorId
 /*!
   \reimp
 
-  This method doesn't perform any action, ignores \a id, and sets \a ok to
+  This method does not 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>.
  */
@@ -176,7 +176,7 @@ void QScxmlCppDataModel::evaluateInitialization(QScxmlExecutableContent::Evaluat
 /*!
   \reimp
 
-  This method doesn't perform any action, ignores \a id and \a body, and sets
+  This method does not 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>.
  */
@@ -223,7 +223,7 @@ const QScxmlEvent &QScxmlCppDataModel::scxmlEvent() const
   \reimp
 
   This method always returns an empty QVariant and ignores \a name.
-  Override it to implement lookup of data model properties via the
+  Override it to implement the lookup of data model properties via the
   \c location attribute of various elements.
  */
 QVariant QScxmlCppDataModel::scxmlProperty(const QString &name) const
@@ -235,8 +235,8 @@ QVariant QScxmlCppDataModel::scxmlProperty(const QString &name) const
 /*!
   \reimp
 
-  This method always returns false and ignores \a name.
-  Override it to implement lookup of data model properties via the
+  This method always returns \c false and ignores \a name.
+  Override it to implement the lookup of data model properties via the
   \c location attribute of various elements.
  */
 bool QScxmlCppDataModel::hasScxmlProperty(const QString &name) const
@@ -248,9 +248,9 @@ bool QScxmlCppDataModel::hasScxmlProperty(const QString &name) const
 /*!
   \reimp
 
-  This method always returns false and ignores \a name, \a value, and
+  This method always returns \c false and ignores \a name, \a value, and
   \a context.
-  Override it to implement lookup of data model properties via the
+  Override it to implement the lookup of data model properties via the
   \c location attribute of various elements.
  */
 bool QScxmlCppDataModel::setScxmlProperty(const QString &name, const QVariant &value,
diff --git a/src/scxml/qscxmldatamodel.cpp b/src/scxml/qscxmldatamodel.cpp
index bf84ef8..f7a7bb2 100644
--- a/src/scxml/qscxmldatamodel.cpp
+++ b/src/scxml/qscxmldatamodel.cpp
@@ -53,7 +53,7 @@ QT_BEGIN_NAMESPACE
  */
 
 /*!
-  Destroys a ForeachLoopBody
+  Destroys a foreach loop body.
  */
 QScxmlDataModel::ForeachLoopBody::~ForeachLoopBody()
 {}
@@ -61,7 +61,7 @@ QScxmlDataModel::ForeachLoopBody::~ForeachLoopBody()
 /*!
   \fn QScxmlDataModel::ForeachLoopBody::run(bool *ok)
 
-  Function to be executed on each iteration. If the execution fails \a ok is
+  This function is executed on each iteration. If the execution fails, \a ok is
   set to \c false, otherwise it is set to \c true.
  */
 
@@ -102,7 +102,7 @@ QScxmlDataModel::QScxmlDataModel(QObject *parent)
 }
 
 /*!
-  Creates a new QScxmlDataModel from a private object \a dd with parent
+  Creates a new data model from the private object \a dd, with the parent
   object \a parent.
  */
 QScxmlDataModel::QScxmlDataModel(QScxmlDataModelPrivate &dd, QObject *parent) :
@@ -201,55 +201,55 @@ QScxmlDataModel *QScxmlDataModelPrivate::instantiateDataModel(DocumentModel::Scx
 /*!
  * \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.
+ * 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 was not.
  * 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.
+ * 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 was not.
+ * Returns the result of the evaluation as a boolean value.
  */
 
 /*!
  * \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.
+ * 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 was not.
  * 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.
+ * 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 was not.
  * 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.
+ * Evaluates the assignment pointed to by \a id and sets \a ok to
+ * \c false if there was an error or to \c true if there was not.
  */
 
 /*!
  * \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.
+ * 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 was not.
  */
 
 /*!
  * \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
+ * 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 was not. The
  * \a body is executed on each iteration.
  */
 
diff --git a/src/scxml/qscxmlexecutablecontent.cpp b/src/scxml/qscxmlexecutablecontent.cpp
index bbe304d..682ea47 100644
--- a/src/scxml/qscxmlexecutablecontent.cpp
+++ b/src/scxml/qscxmlexecutablecontent.cpp
@@ -58,139 +58,140 @@ using namespace QScxmlExecutableContent;
     \typedef QScxmlExecutableContent::ContainerId
     \inmodule QtScxml
     \since 5.8
-    \brief ID for a container holding executable content
+    \brief ID for a container holding executable content.
  */
 
 /*!
     \typedef QScxmlExecutableContent::EvaluatorId
     \inmodule QtScxml
     \since 5.8
-    \brief ID for a unit of executable content
+    \brief ID for a unit of executable content.
  */
 
 /*!
     \typedef QScxmlExecutableContent::InstructionId
     \inmodule QtScxml
     \since 5.8
-    \brief ID for an instruction of executable content
+    \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
+    \brief ID for a string contained in executable content.
  */
 
 /*!
     \class QScxmlExecutableContent::EvaluatorInfo
-    \brief Representation of a unit of executable content
+    \brief The EvaluatorInfo class represents a unit of executable content.
     \since 5.8
     \inmodule QtScxml
  */
 
 /*!
     \variable QScxmlExecutableContent::EvaluatorInfo::expr
-    \brief Expression to be evaluated
+    \brief The expression to be evaluated
  */
 
 /*!
     \variable QScxmlExecutableContent::EvaluatorInfo::context
-    \brief Context for evaluating the expression
+    \brief The context for evaluating the expression
  */
 
 /*!
     \class QScxmlExecutableContent::AssignmentInfo
-    \brief Representation of a data assignment
+    \brief The AssingmentInfo class represents a data assignment.
     \since 5.8
     \inmodule QtScxml
  */
 
 /*!
     \variable QScxmlExecutableContent::AssignmentInfo::expr
-    \brief Expression to be evaluated
+    \brief The expression to be evaluated
  */
 
 /*!
     \variable QScxmlExecutableContent::AssignmentInfo::context
-    \brief Context for evaluating the expression
+    \brief The context for evaluating the expression
  */
 
 /*!
     \variable QScxmlExecutableContent::AssignmentInfo::dest
-    \brief Name of the data item to assign to
+    \brief The name of the data item to assign to
  */
 
 /*!
     \class QScxmlExecutableContent::ForeachInfo
-    \brief Representation of a foreach construct
+    \brief The ForeachInfo class represents a foreach construct.
     \since 5.8
     \inmodule QtScxml
  */
 
 /*!
     \variable QScxmlExecutableContent::ForeachInfo::array
-    \brief Name of the array we are iterating over
+    \brief The name of the array that is iterated over
  */
 
 /*!
     \variable QScxmlExecutableContent::ForeachInfo::item
-    \brief Name of the iteration variable
+    \brief The name of the iteration variable
  */
 
 /*!
     \variable QScxmlExecutableContent::ForeachInfo::index
-    \brief Name of the index variable
+    \brief The name of the index variable
  */
 
 /*!
     \variable QScxmlExecutableContent::ForeachInfo::context
-    \brief Context for evaluating the expression
+    \brief The context for evaluating the expression
  */
 
 /*!
     \class QScxmlExecutableContent::ParameterInfo
-    \brief Representation of a parameter to a service invocation
+    \brief The ParameterInfo class represents a parameter to a service
+    invocation.
     \since 5.8
     \inmodule QtScxml
  */
 
 /*!
     \variable QScxmlExecutableContent::ParameterInfo::name
-    \brief Name of the parameter
+    \brief The name of the parameter
  */
 
 /*!
     \variable QScxmlExecutableContent::ParameterInfo::expr
-    \brief Expression to be evaluated
+    \brief The expression to be evaluated
  */
 
 /*!
     \variable QScxmlExecutableContent::ParameterInfo::location
-    \brief Data model name of the item to be passed as parameter
+    \brief The data model name of the item to be passed as a parameter
  */
 
 /*!
     \class QScxmlExecutableContent::InvokeInfo
-    \brief Representation of a service invocation
+    \brief The InvokeInfo class represents a service invocation.
     \since 5.8
     \inmodule QtScxml
  */
 
 /*!
     \variable QScxmlExecutableContent::InvokeInfo::id
-    \brief the ID specified by the id attribute in the invoke element
+    \brief The ID specified by the \c id attribute in the \c <invoke> element.
  */
 
 /*!
     \variable QScxmlExecutableContent::InvokeInfo::prefix
-    \brief Unique prefix for this invocation in the context of the state from
-    which it is called
+    \brief The 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
+    \brief The data model location to write the invocation ID to
  */
 
 /*!
@@ -205,7 +206,8 @@ using namespace QScxmlExecutableContent;
 
 /*!
     \variable QScxmlExecutableContent::InvokeInfo::finalize
-    \brief An ID of a container of executable content to be run on finalizing the invocation
+    \brief The ID of the container of executable content to be run on finalizing
+    the invocation
  */
 
 /*!
diff --git a/src/scxml/qscxmlinvokableservice.cpp b/src/scxml/qscxmlinvokableservice.cpp
index 35cd924..a897eaa 100644
--- a/src/scxml/qscxmlinvokableservice.cpp
+++ b/src/scxml/qscxmlinvokableservice.cpp
@@ -45,87 +45,88 @@ QT_BEGIN_NAMESPACE
 
 /*!
  * \class QScxmlInvokableService
- * \brief Service invoked from \l{SCXML Specification}{SCXML}
+ * \brief The QScxmlInvokableService class is the base class for services called
+ * from state machines.
  * \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.
+ * The services are called from state machines via the mechanism described in
+ * \l {SCXML Specification - 6.4 <invoke>}. This class represents an actual
+ * instance of an invoked service.
  */
 
 /*!
  * \class QScxmlInvokableServiceFactory
- * \brief Factory for creating instances of QScxmlInvokableService
+ * \brief The QScxmlInvokableServiceFactory class creates invokable service
+ * instances.
  * \since 5.8
  * \inmodule QtScxml
  *
- * A factory for creating instances of QScxmlInvokableService. This reperesents
+ * Each service instance represents
  * an \c <invoke> element in the SCXML document. Each time the service is
- * actually invoked a new instance of QScxmlInvokableService is created.
+ * actually invoked, a new instance of QScxmlInvokableService is created.
  */
 
 /*!
   \property QScxmlInvokableServiceFactory::invokeInfo
 
-  The QScxmlExecutableContent::InvokeInfo passed to the constructor.
+  \brief The QScxmlExecutableContent::InvokeInfo passed to the constructor.
  */
 
 /*!
   \property QScxmlInvokableServiceFactory::names
 
-  The QVector<QScxmlExecutableContent::StringId> of names passed to the
-  constructor.
+  \brief The names passed to the constructor.
  */
 
 /*!
   \property QScxmlInvokableServiceFactory::parameters
 
-  The QVector<QScxmlExecutableContent::ParameterInfo> passed to the
-  constructor.
+  \brief The parameters passed to the constructor.
  */
 
 /*!
  * \class QScxmlStaticScxmlServiceFactory
- * \brief Factory for creating QScxmlScxmlService instances from precompiled
- *        documents
+ * \brief The QScxmlStaticScxmlServiceFactory class creates SCXML service
+ * 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>
+ * A factory for instantiating SCXML state machines 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
+ * \brief The QScxmlDynamicScxmlServiceFactory class creates SCXML service
+ * instances from documents loaded at runtime.
  * \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
+ * Dynamically resolved services are used when loading \l{SCXML Specification}
+ * {SCXML} content from files that a
  * parent state machine requests at runtime, via the \c srcexpr attribute in
- * \c <invoke>.
+ * the \c <invoke> element.
  */
 
 /*!
  * \property QScxmlInvokableService::parentStateMachine
  *
- * The QScxmlStateMachine that invoked the service.
+ * \brief The SCXML state machine that invoked the service.
  */
 
 /*!
  * \property QScxmlInvokableService::id
  *
- * The id specified in the \c id attribute of the \c <invoke> element.
+ * \brief The ID of the invokable service.
+ *
+ * The ID is specified by the \c id attribute of the \c <invoke> element.
  */
 
 /*!
  * \property QScxmlInvokableService::name
  *
- * The name of the service being invoked.
+ * \brief The name of the service being invoked.
  */
 
 /*!
@@ -144,8 +145,8 @@ QT_BEGIN_NAMESPACE
 /*!
  * \fn QScxmlInvokableServiceFactory::invoke(QScxmlStateMachine *parentStateMachine)
  *
- * Invoke the service with the parameters given in the contructor, passing
- * \a parentStateMachine as parent. Returns the new QScxmlInvokableService.
+ * Invokes the service with the parameters given in the constructor, passing
+ * \a parentStateMachine as the parent. Returns the new invokable service.
  */
 
 QScxmlInvokableServicePrivate::QScxmlInvokableServicePrivate(QScxmlStateMachine *parentStateMachine)
@@ -322,8 +323,8 @@ QScxmlScxmlService::~QScxmlScxmlService()
 }
 
 /*!
-  Create a QScxmlScxmlService wrapping \a stateMachine, invoked from
-  \a parentStateMachine, as child of \a parent.
+  Creates a SCXML service wrapping \a stateMachine, invoked from
+  \a parentStateMachine, as a child of \a factory.
  */
 QScxmlScxmlService::QScxmlScxmlService(QScxmlStateMachine *stateMachine,
                                        QScxmlStateMachine *parentStateMachine,
@@ -391,8 +392,8 @@ void QScxmlScxmlService::postEvent(QScxmlEvent *event)
 }
 
 /*!
-  Create a QScxmlDynamicScxmlServiceFactory, passing the attributes of the
-  \c <invoke> element as \a invokeInfo, any \c <param> child elements as
+  Creates a factory for dynamically resolved services, 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.
  */
diff --git a/src/scxml/qscxmlnulldatamodel.cpp b/src/scxml/qscxmlnulldatamodel.cpp
index d3e9942..3054383 100644
--- a/src/scxml/qscxmlnulldatamodel.cpp
+++ b/src/scxml/qscxmlnulldatamodel.cpp
@@ -154,10 +154,10 @@ bool QScxmlNullDataModel::setup(const QVariantMap &initialDataValues)
 
 /*!
   \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
+  Evaluates the executable content pointed to by \a id and records in \a ok
+  whether there was an error. Returns the result of the evaluation as a string.
+  The null data model can evaluate the \c <log> element, so this might result in
+  an actual value, rather than an error
  */
 QString QScxmlNullDataModel::evaluateToString(QScxmlExecutableContent::EvaluatorId id, bool *ok)
 {
@@ -172,10 +172,10 @@ QString QScxmlNullDataModel::evaluateToString(QScxmlExecutableContent::Evaluator
 
 /*!
   \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.
+  Evaluates the executable content pointed to by \a id and records in \a ok
+  whether there was an error. Returns the result of the evaluation as a boolean
+  value. The null data model can evaluate the instruction \c In(...), so this
+  might result in an actual value, rather than an error.
  */
 bool QScxmlNullDataModel::evaluateToBool(QScxmlExecutableContent::EvaluatorId id, bool *ok)
 {
@@ -185,8 +185,8 @@ bool QScxmlNullDataModel::evaluateToBool(QScxmlExecutableContent::EvaluatorId id
 
 /*!
   \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
+  Evaluates the executable content pointed to by \a id and records in \a ok
+  whether 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)
@@ -201,8 +201,8 @@ QVariant QScxmlNullDataModel::evaluateToVariant(QScxmlExecutableContent::Evaluat
 
 /*!
   \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
+  Evaluates the executable content pointed to by \a id and records in \a ok
+  whether 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)
@@ -216,7 +216,7 @@ void QScxmlNullDataModel::evaluateToVoid(QScxmlExecutableContent::EvaluatorId id
 
 /*!
   \reimp
-  Throws an error and sets \a ok to \c false because the null data model cannot evaluate
+  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)
@@ -230,7 +230,8 @@ void QScxmlNullDataModel::evaluateAssignment(QScxmlExecutableContent::EvaluatorI
 
 /*!
   \reimp
-  Throws an error and sets \a ok to \c false because the null data model cannot initialize data.
+  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)
 {
@@ -243,8 +244,8 @@ void QScxmlNullDataModel::evaluateInitialization(QScxmlExecutableContent::Evalua
 
 /*!
   \reimp
-  Throws an error and sets \a ok to \c false because the null data model cannot evaluate <foreach>
-  blocks.
+  Throws an error and sets \a ok to \c false, because the null data model cannot
+  evaluate \c <foreach> blocks.
  */
 void QScxmlNullDataModel::evaluateForeach(QScxmlExecutableContent::EvaluatorId id, bool *ok,
                                           ForeachLoopBody *body)
diff --git a/src/scxml/qscxmlstatemachine.cpp b/src/scxml/qscxmlstatemachine.cpp
index 41d47ba..61a37ef 100644
--- a/src/scxml/qscxmlstatemachine.cpp
+++ b/src/scxml/qscxmlstatemachine.cpp
@@ -591,8 +591,9 @@ void QScxmlStateMachinePrivate::submitDelayedEvent(QScxmlEvent *event)
 /*!
  * Submits an error event to the external event queue of this state machine.
  *
- * 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
+ * The type of the error is specified by \a type. The value of type has to begin
+ * with the string \e error. For example \c {error.execution}. The message,
+ * \a message, decribes the error and 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.
  */
@@ -1544,7 +1545,9 @@ QScxmlStateMachine::QScxmlStateMachine(QScxmlStateMachinePrivate &dd, QObject *p
 /*!
     \property QScxmlStateMachine::tableData
 
-    This is used when generating C++ from an SCXML file. The class implementing
+    \brief The table data that is used when generating C++ from an SCXML file.
+
+    The class implementing
     the state machine will use this property to assign the generated table
     data. The state machine does not assume ownership of the table data.
  */
@@ -2068,7 +2071,7 @@ void QScxmlStateMachine::stop()
 }
 
 /*!
-  Returns \c true if the state with ID \a stateIndex is active.
+  Returns \c true if the state with the 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
diff --git a/src/scxml/qscxmltabledata.cpp b/src/scxml/qscxmltabledata.cpp
index fc2bbb7..0c2db00 100644
--- a/src/scxml/qscxmltabledata.cpp
+++ b/src/scxml/qscxmltabledata.cpp
@@ -82,7 +82,7 @@ QT_USE_NAMESPACE
 
 /*!
     \fn QScxmlTableData::dataNames(int *count) const
-    Retrieves the string IDs for names of data items in the data model. The
+    Retrieves the string IDs for the 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.
 
@@ -969,7 +969,7 @@ private:
 
 /*!
     \fn QScxmlTableData::~QScxmlTableData()
-    Destroys a QScxmlTableData.
+    Destroys the SXCML table data.
  */
 QScxmlTableData::~QScxmlTableData()
 {}