Fix mistakes in the documentation

Change-Id: I30272d6b52bbf4c16c1a312d6827386f8d767549
Reviewed-by: Frank Meerkoetter <frank.meerkoetter@basyskom.com>
Reviewed-by: Alex Blasche <alexander.blasche@qt.io>

8 files changed, 75 insertions, 47 deletions

diff --git a/src/opcua/client/qopcuaclient.cpp b/src/opcua/client/qopcuaclient.cpp
index ca17dec..c6a2f9f 100644
--- a/src/opcua/client/qopcuaclient.cpp
+++ b/src/opcua/client/qopcuaclient.cpp
@@ -78,7 +78,7 @@ Q_DECLARE_LOGGING_CATEGORY(QT_OPCUA)
                 qDebug() << "A node object has been created";
         }
     });
-    client->connectToEndpoint(QUrl("opc.tcp://127.0.0.1:4840"); // Connect the client to the server
+    client->connectToEndpoint(QUrl("opc.tcp://127.0.0.1:4840")); // Connect the client to the server
     \endcode
 */
 
@@ -139,7 +139,7 @@ Q_DECLARE_LOGGING_CATEGORY(QT_OPCUA)
 /*!
     \fn void QOpcUaClient::namespaceArrayUpdated(QStringList namespaces)
 
-    This signal is emitted after a updateNamespaceArray operation has finished.
+    This signal is emitted after an updateNamespaceArray operation has finished.
     \a namespaces contains the content of the server's namespace table. The index
     of an entry in \a namespaces corresponds to the namespace index used in the node id.
 */
@@ -211,8 +211,8 @@ QOpcUaClient::ClientError QOpcUaClient::error() const
     Returns a \l QOpcUaNode object associated with the OPC UA node identified
     by \a nodeId. The caller becomes owner of the node object.
 
-    If the client is not connected, nullptr is returned. The backends may also
-    return nullptr for other error cases (for example for a malformed node id).
+    If the client is not connected, \c nullptr is returned. The backends may also
+    return \c nullptr for other error cases (for example for a malformed node id).
 */
 QOpcUaNode *QOpcUaClient::node(const QString &nodeId)
 {
diff --git a/src/opcua/client/qopcuamonitoringparameters.cpp b/src/opcua/client/qopcuamonitoringparameters.cpp
index 307bdb1..d111160 100644
--- a/src/opcua/client/qopcuamonitoringparameters.cpp
+++ b/src/opcua/client/qopcuamonitoringparameters.cpp
@@ -50,12 +50,12 @@ QT_BEGIN_NAMESPACE
     the revised values from the server.
 
     \section1 Usage
-    For most use cases, only the publishing interval is required
+    For most use cases, only the publishing interval is required.
     \code
-    QOpcUaMonitoringParameters p(100); // Set a publishing interval of 100ms and share the subscription
+    QOpcUaMonitoringParameters p(100); // Set a publishing interval of 100ms and share the subscription.
     node->enableMonitoring(QOpcUa::NodeAttribute::Value, p);
     \endcode
-    If an \l {QOpcUaMonitoringParameters::SubscriptionType} {exclusive} subscription is required, use the second parameter
+    If an \l {QOpcUaMonitoringParameters::SubscriptionType} {exclusive} subscription is required, use the second parameter.
     \code
     QOpcUaMonitoringParameters p(100, QOpcUaMonitoringParameters::SubscriptionType::Exclusive); // Create a new subscription
     \endcode
@@ -184,6 +184,12 @@ QT_BEGIN_NAMESPACE
 */
 
 /*!
+    \fn QOpcUaMonitoringParameters::DataChangeFilter::DataChangeFilter(DataChangeTrigger p_trigger, DeadbandType p_deadbandType, double p_deadbandValue)
+
+    Constructs a DataChangeFilter with trigger \a p_trigger, deadband type \a p_deadbandType and deadband value \a p_deadbandValue.
+*/
+
+/*!
     \variable QOpcUaMonitoringParameters::DataChangeFilter::trigger
 
     The trigger for this filter.
@@ -206,9 +212,9 @@ QT_BEGIN_NAMESPACE
 
     Enumerates the possible triggers for a \l DataChangeFilter.
 
-    \value Status Triggers if the status code for the value changes.
-    \value StatusValue Triggers if the status code or the value changes.
-    \value StatusValueTimestamp Triggers if the status code, the value or the source timestamp changes.
+    \value Status Triggers if the value's status code changes.
+    \value StatusValue Triggers if the value's status code or the value itself changes.
+    \value StatusValueTimestamp Triggers if the value's status code, the value itself or the source timestamp changes.
 */
 
 /*!
@@ -355,7 +361,7 @@ quint32 QOpcUaMonitoringParameters::maxNotificationsPerPublish() const
 }
 
 /*!
-    Request \a maxNotificationsPerPublish as maximum notifications per publish value for the subscription.
+    Set \a maxNotificationsPerPublish as maximum notifications per publish value for the subscription.
 */
 void QOpcUaMonitoringParameters::setMaxNotificationsPerPublish(quint32 maxNotificationsPerPublish)
 {
@@ -437,7 +443,7 @@ QOpcUaMonitoringParameters::MonitoringMode QOpcUaMonitoringParameters::monitorin
 }
 
 /*!
-    Request \a monitoringMode as monitoring mode for the monitored item.
+    Set \a monitoringMode as monitoring mode for the monitored item.
 */
 void QOpcUaMonitoringParameters::setMonitoringMode(MonitoringMode monitoringMode)
 {
@@ -453,7 +459,7 @@ bool QOpcUaMonitoringParameters::discardOldest() const
 }
 
 /*!
-    Request \a discardOldest as discardOldest setting for the monitored item.
+    Set \a discardOldest as discardOldest setting for the monitored item.
 */
 void QOpcUaMonitoringParameters::setDiscardOldest(bool discardOldest)
 {
@@ -494,7 +500,7 @@ void QOpcUaMonitoringParameters::setDataChangeFilter(const QOpcUaMonitoringParam
 }
 
 /*!
-    Request \a filter as filter for for the monitored item.
+    Request \a filter as filter for the monitored item.
 
     For general use, the type-safe versions that are listed below are preferred.
 
diff --git a/src/opcua/client/qopcuanode.cpp b/src/opcua/client/qopcuanode.cpp
index 38dcd3d..73a545f 100644
--- a/src/opcua/client/qopcuanode.cpp
+++ b/src/opcua/client/qopcuanode.cpp
@@ -54,11 +54,11 @@ QT_BEGIN_NAMESPACE
     It has attributes like browse name, value, associated properties and can have
     references to other nodes in the address space.
     Nodes are organized in namespaces and have IDs which can e.g. be numeric,
-    a string, a namespace specific format (opaque) or a globally unique identifier.
-    A node is identified by the namespace id and the node ID.
+    a string, a namespace-specific format (opaque) or a globally unique identifier.
+    A node is identified by the namespace ID and the node ID.
     This identifier is usually given as a string:
     The identifier of a node residing in namespace 0 and having the numeric
-    identifier 42, the string is \c ns=0;i=42, a node with a string
+    identifier 42 results in the string \c ns=0;i=42. A node with a string
     identifier can be addressed via \c ns=0;s=myStringIdentifier.
 
     Objects of this type are owned by the user and must be deleted when they are
@@ -77,7 +77,7 @@ QT_BEGIN_NAMESPACE
     \l attributeError() contains a status code associated with the last read or write operation
     on the attribute. This is the low level status code returned by the OPC UA service.
     This status code can be simplified by converting it to a \l QOpcUa::ErrorCategory using
-    \l QOpcUa::errorCategory).
+    \l QOpcUa::errorCategory().
 
     \section1 Subscribing to data changes
     Subscriptions are a concept in OPC UA which allows receiving of notifications for changes in data
@@ -89,7 +89,7 @@ QT_BEGIN_NAMESPACE
 
     \l QOpcUaNode offers an abstraction to interact with subscriptions and monitored items.
     \l enableMonitoring() enables data change notifications for one or more attributes.
-    The \l attributeUpdated signal contains new values, the local cache is updated.
+    The \l attributeUpdated signal contains new values and the local cache is updated.
     \l disableMonitoring() disables the data change notifications.
     The \l monitoringStatusChanged signal notifies about changes of the monitoring status, e. g. after
     manual enable and disable or a status change on the server.
@@ -250,6 +250,7 @@ bool QOpcUaNode::readAttributeRange(QOpcUa::NodeAttribute attribute, const QStri
 
 /*!
     Starts an asynchronous read operation for the node attributes in \a attributes.
+
     Returns \c true if the asynchronous call has been successfully dispatched.
 
     Attribute values only contain valid information after the \l attributeRead signal has been emitted.
@@ -400,7 +401,7 @@ bool QOpcUaNode::modifyDataChangeFilter(QOpcUa::NodeAttribute attr, const QOpcUa
     Writes \a value to the attribute given in \a attribute using the type information from \a type.
     Returns \c true if the asynchronous call has been successfully dispatched.
 
-    If the \a type parameter is omitted, the backend tries to find the correct type. Following default types are assumed:
+    If the \a type parameter is omitted, the backend tries to find the correct type. The following default types are assumed:
     \table
         \header
             \li Qt MetaType
@@ -479,6 +480,7 @@ bool QOpcUaNode::writeAttributeRange(QOpcUa::NodeAttribute attribute, const QVar
 
 /*!
     Executes a write operation for the attributes and values specified in \a toWrite.
+
     Returns \c true if the asynchronous call has been successfully dispatched.
 
     The \a valueAttributeType parameter can be used to supply type information for the value attribute.
@@ -532,7 +534,7 @@ bool QOpcUaNode::browseChildren(QOpcUa::ReferenceTypeId referenceType, QOpcUa::N
 }
 
 /*!
-    The ID of the OPC UA node.
+    Returns the ID of the OPC UA node.
 */
 QString QOpcUaNode::nodeId() const
 {
diff --git a/src/opcua/client/qopcuareferencedescription.cpp b/src/opcua/client/qopcuareferencedescription.cpp
index 5607b9b..60c293f 100644
--- a/src/opcua/client/qopcuareferencedescription.cpp
+++ b/src/opcua/client/qopcuareferencedescription.cpp
@@ -42,7 +42,7 @@ QT_BEGIN_NAMESPACE
 /*!
     \class QOpcUaReferenceDescription
     \inmodule QtOpcUa
-    \brief Contains information about a node, result of a browse call
+    \brief Contains information about a node
 
     This class is used to return the results of a call to \l QOpcUaNode::browseChildren().
 
diff --git a/src/opcua/client/qopcuatype.cpp b/src/opcua/client/qopcuatype.cpp
index 98de28a..3de10e1 100644
--- a/src/opcua/client/qopcuatype.cpp
+++ b/src/opcua/client/qopcuatype.cpp
@@ -681,6 +681,13 @@ QString QOpcUa::nodeIdFromInteger(quint16 ns, quint32 identifier)
 */
 
 /*!
+    \fn QOpcUa::QEUInformation::QEUInformation(QString p_namespaceUri, qint32 p_unitId, QLocalizedText p_displayName, QLocalizedText p_description)
+
+    Constructs a QEUInformation with namespace URI \a p_namespaceUri, unit id \a p_unitId, display name \a p_displayName
+    and description \a p_description.
+*/
+
+/*!
     \fn bool QOpcUa::QEUInformation::operator==(const QEUInformation &other) const
     Returns \c true if this QEUInformation has the same value as \a other.
 */
@@ -694,7 +701,7 @@ QString QOpcUa::nodeIdFromInteger(quint16 ns, quint32 identifier)
 /*!
     \variable QOpcUa::QEUInformation::unitId
 
-    A machine readable identifier for the unit.
+    A machine-readable identifier for the unit.
 */
 
 /*!
@@ -788,6 +795,13 @@ QString QOpcUa::nodeIdFromInteger(quint16 ns, quint32 identifier)
 */
 
 /*!
+    \fn QOpcUa::QAxisInformation::QAxisInformation(QEUInformation p_engineeringUnits, QRange p_eURange, QLocalizedText p_title, AxisScale p_axisScaleType, QVector<double> p_axisSteps)
+
+    Constructs a QAxisInformation with engineering units \a p_engineeringUnits, range \a p_eURange, title \a p_title,
+    scaling \a p_axisScaleType and axis steps \a p_axisSteps.
+*/
+
+/*!
     \variable QOpcUa::QAxisInformation::engineeringUnits
 
     The engineering units of this axis.
diff --git a/src/opcua/core/qopcuaprovider.cpp b/src/opcua/core/qopcuaprovider.cpp
index 62b5d7e..52c0e50 100644
--- a/src/opcua/core/qopcuaprovider.cpp
+++ b/src/opcua/core/qopcuaprovider.cpp
@@ -170,7 +170,7 @@ static QOpcUaPlugin *loadPlugin(const QString &key)
 /*!
     Returns a pointer to a QOpcUaClient object by loading the selected \a backend
     as a plugin and creating a client object.
-    If the plugin loading fails, nullptr is returned instead.
+    If the plugin loading fails, \c nullptr is returned instead.
 
     The user is responsible for deleting the returned \l QOpcUaClient object
     when it is no longer needed.
diff --git a/src/opcua/doc/src/examples/waterpump.qdoc b/src/opcua/doc/src/examples/waterpump.qdoc
index d67b9a1..d7ebb67 100644
--- a/src/opcua/doc/src/examples/waterpump.qdoc
+++ b/src/opcua/doc/src/examples/waterpump.qdoc
@@ -38,9 +38,8 @@
     The OPC UA server included in this example runs a simulation of a machine
     containing two tanks, a water pump and a valve. Water can be pumped from the
     first tank into the second tank and then be flushed from the second tank
-    by opening the valve. Both operations have a user configurable setpoint
-    which controls how much water is pumped to the second tank or flushed
-    from the first tank.
+    by opening the valve. Both operations have a user-configurable setpoint
+    which controls how much water is pumped to or flushed from the second tank.
 
     The following nodes exist on the server:
 
@@ -96,9 +95,10 @@
     methods wrapping the OPC UA method calls.
 
     \section2 Member variables
-    Pointers to \l QOpcUaClient and to each \l QOpcUaNode needed for interaction with the server
-    are required. For the values of these nodes, member variables containing the last value
-    reported by the server are added.
+    A pointer to \l QOpcUaClient is required for connection management. An
+    additional pointer to a \l QOpcUaNode object is needed for each OPC UA
+    node the HMI interacts with. For the values of these nodes, member variables
+    containing the last value reported by the server are added.
 
     \quotefromfile opcua/waterpump/qml-hmi/opcuamachinebackend.h
     \dots
@@ -129,7 +129,7 @@
     \printuntil }
 
     A read operation emits the \l QOpcUaNode::attributeRead signal on completion.
-    The client has to check the status code and then get the result from the node
+    The client has to check the status code and then get the result from the node.
 
     \skipto void OpcUaMachineBackend::machineDesignationRead
     \printuntil }
@@ -138,17 +138,23 @@
 
     \section2 Interaction with the server
 
-    In the constructor, a \l QOpcUaProvider is created and a \l QOpcUaClient with
-    open62541 backend is requested. Its \l QOpcUaClient::stateChanged signal must be
-    connected to the backend's machineStateUpdated slot.
+    In the constructor, a QOpcUaProvider is created and the available backends are saved to provide a model for the backend selection dropdown menu.
 
     \quotefromfile opcua/waterpump/qml-hmi/opcuamachinebackend.cpp
     \dots
     \skipto QOpcUaProvider provider
-    \printuntil QObject
+    \printuntil setBackends
     \dots
 
-    machineStateUpdated acts on QOpcUaClient being connected or disconnected.
+    Before attempting a connection, a QOpcUaClient with the selected backend is created. Its \l QOpcUaClient::stateChanged signal must be
+    connected to the backend's clientStateHandler slot.
+
+    \quotefromfile opcua/waterpump/qml-hmi/opcuamachinebackend.cpp
+    \skipto OpcUaMachineBackend::connectToEndpoint
+    \printuntil m_client->connectToEndpoint
+    \printuntil }
+
+    clientStateHandler acts on QOpcUaClient being connected or disconnected.
     In case of a successful connection, the node member variables created before
     are filled with node objects.
 
@@ -159,7 +165,7 @@
     \dots
 
     After all node objects have been created, the data change handlers are
-    connected to the node objects and monitoring is enabled
+    connected to the node objects and monitoring is enabled.
 
     \dots
     \skipto Connect signal handlers
@@ -167,7 +173,7 @@
     \dots
 
     The machine designation is not supposed to change and will be read once at
-    startup
+    startup.
 
     \dots
     \skipto Connect the handler for async reading
@@ -175,12 +181,12 @@
     \codeline
     \dots
 
-    A setter for the setpoint is added to the backend
+    A setter for the setpoint is added to the backend.
 
     \skipto machineWriteTank2TargetPercent
     \printuntil }
 
-    For the methods, wrappers which call the OPC UA server method are created
+    For the methods, wrappers which call the OPC UA server method are created.
 
     \skipto startPump
     \printuntil }
@@ -188,7 +194,7 @@
     \section2 The HMI
 
     A backend instance is created and handed to the QML part as a context property
-    named uaBackend
+    named uaBackend.
 
     \dots
     \quotefromfile opcua/waterpump/qml-hmi/main.cpp
@@ -207,7 +213,7 @@
     \printuntil }
     \printuntil }
 
-    Signals from the backend can also be used directly in the QML code
+    Signals from the backend can also be used directly in the QML code.
 
     \quotefromfile opcua/waterpump/qml-hmi/Pump.qml
     \skipto Connections
diff --git a/src/opcua/doc/src/qtopcua.qdoc b/src/opcua/doc/src/qtopcua.qdoc
index f6f0c97..2c23c46 100644
--- a/src/opcua/doc/src/qtopcua.qdoc
+++ b/src/opcua/doc/src/qtopcua.qdoc
@@ -79,22 +79,22 @@
     The use of different reference types and nodes containing metadata enable a client to navigate and interpret
     the data without knowing their structure in advance.
 
-    All nodes have a unique identifier and attributes that can be read and written.
+    Each node has a unique identifier and attributes that can be read and written.
     Among others, there are Variable nodes which store values and callable Method nodes with attached nodes describing
     parameters and return values. Notifications in case of events and monitoring of Variable nodes for value changes are offered too.
 
     Complex objects can be created by combining nodes using references, inheritance is also possible.
     OPC UA offers support for pre-made models which can be extended to fit special needs.
 
-    OPC UA is the platform independent successor of OPC Classic intended for usage on all levels,
+    OPC UA is the platform-independent successor of OPC Classic intended for usage on all levels,
     from embedded sensors up to manufacturing execution and enterprise resource planning systems.
-    It has a service oriented architecture based on standardized messages for service requests and responses.
+    It has a service-oriented architecture based on standardized messages for service requests and responses.
     There are different ways for these messages to be encoded and transported over the network. The most common way
     is binary encoding over TCP.
 
     \section1 Implemented features from the OPC UA protocol
 
-    Following features of OPC UA are supported by Qt OPC UA:
+    The following features of OPC UA are supported by Qt OPC UA:
 
     \table
     \header
@@ -136,7 +136,7 @@
 
     \section1 Data types
     A subset of the OPC UA data types is currently supported in Qt OPC UA.
-    Most of them are available with both backends.
+    Most of them are available with all backends.
 
     \table
     \header