Fix BTLE related qdoc errors

Change-Id: Id1a56b0ed050fd9cebee8738351e560b442d748f
Reviewed-by: Lars Knoll <lars.knoll@digia.com>
Reviewed-by: Alex Blasche <alexander.blasche@digia.com>

8 files changed, 89 insertions, 75 deletions

diff --git a/src/bluetooth/doc/src/bluetooth-overview.qdoc b/src/bluetooth/doc/src/bluetooth-overview.qdoc
index 2a5d8de2..e20a1d22 100644
--- a/src/bluetooth/doc/src/bluetooth-overview.qdoc
+++ b/src/bluetooth/doc/src/bluetooth-overview.qdoc
@@ -128,39 +128,45 @@
     heart rate or any other measurements) and advertises them. The client (PC, smartphone
     or any other Bluetooth Smart Ready device) connects to the server and reads the values
     advertised by the server. The BLE API is based on GATT (Generic Attribute Profile) concepts.
-    GATT commands are initiated by the client, as mentioned above, and the server is receiving
-    GATT commands and sends replies.
+    GATT commands are initiated by the client, and the server processes them. Each command is
+    usually answered by a reply.
 
-    These GATT commands initiate the services, which consist of characteristics. A characteristic
-    is data that is being transferred. Each characteristic has descriptors, which give additional
-    information about the characteristic. Services, characteristics and descriptors are recognized
-    by their 128bits UUIDs.
+    Each BLE service may consist of one or more characteristics. A characteristic
+    contains data  and can be further described by descriptors, which provide additional
+    information or means of manipulating the characteristic. All services, characteristics and
+    descriptors are recognized by their 128bits UUIDs. Further details on known uuids can be found
+    in \l QBluetoothUuid.
 
-    To be able to get and read characteristics, it is required to connect to the LE device service.
+    To be able to read and write characteristics, it is necessary to connect to the LE service.
 
     \snippet heartlistener/heartrate.cpp Connect signals
 
     We start a service discovery with a \l QBluetoothServiceDiscoveryAgent class and connect its
-    signal \l serviceDiscovered(QLowEnergyServiceInfo) to the slot in the application.
-    This way, it is possible to store all LE services or connect to the desired one.
-    \l QLowEnergyController is used for connecting to service, emitting values,
-    receiving emitted errors from the service and characteristics, and disconnecting from the service.
+    \l {QBluetoothServiceDiscoveryAgent::}{serviceDiscovered()} signal. Within the receiving slot we connect to the desired service.
+    \l QLowEnergyController is used to connect or disconnect to services, emits service-related value changes
+    and propagates errors in relation to the service management.
 
     Even though it is possible to connect to an LE service before the service scan is done,
-    it is advisable to do it after the service scan is done.
+    it is advisable to delay until after the service search has finished.
 
     \snippet heartlistener/heartrate.cpp Connecting to service
 
-    In the code example above, the wanted characteristics will be enabled for the notifications, but not
-    all of them have that option as explained in \l QLowEnergyController documentation. In this case,
-    it was a characteristic \l QBluetoothUuid::HeartRateMeasurement.
+    In the code example above, the desired characteristics is of type
+    \l {QBluetoothUuid::HeartRateMeasurement}{HeartRateMeasurement}. Since the application measures
+    the heart rate changes, it must enable change notifications for the characteristic.
+    Note that not all characteristics provide change notifications. Since the HeartRate characteristic
+    has been standardized it is possible to assume that notifications can be received. Ultimately
+    \l QLowEnergyCharacteristicInfo::isNotificationCharacteristic() must return \c true to
+    verify the availability of notifications.
 
-    Finally, to receive updates, we defined the slot where we read the emitted value.
+    Finally, we process the value of the HeartRate characteristic, as per Bluetooth Low Energy standard:
 
     \snippet heartlistener/heartrate.cpp Reading value
 
-    The returned value is the hexadecimal value. The procedure of reading and converting hexadecimal
-    value properly depends on the BLE devices that is sending updates since every device has a different
-    value structure.
-
+    In general a characterisitic value is a series of hexadecimal numbers. The precise interpretation of
+    those hexadecimal numbers depends on the characteristic type and its value structure.
+    A significant number has been standardized by the
+    \l {https://developer.bluetooth.org/gatt/services/Pages/ServicesHome.aspx}{Bluetooth SIG} whereas others
+    may follow a custom protocol. The above code snippet demonstrates how to the read the standardized
+    HeartRate value.
 */
diff --git a/src/bluetooth/qbluetoothdeviceinfo.cpp b/src/bluetooth/qbluetoothdeviceinfo.cpp
index 1dd100e0..9e6ebaec 100644
--- a/src/bluetooth/qbluetoothdeviceinfo.cpp
+++ b/src/bluetooth/qbluetoothdeviceinfo.cpp
@@ -252,9 +252,9 @@ QT_BEGIN_NAMESPACE
     This enum describes the configuration of the device.
 
     \value BaseRateCoreConfiguration            The device is a standard Bluetooth device.
-    \value BaseRateAndLowEnergyConfiguration    The device is a Bluetooth Smart device with support
+    \value BaseRateAndLowEnergyCoreConfiguration    The device is a Bluetooth Smart device with support
                                                 for standard and Low Energy device.
-    \value LowEnergyCoreCOnfiguration           The device is a Bluetooth Low Energy device.
+    \value LowEnergyCoreConfiguration           The device is a Bluetooth Low Energy device.
 */
 QBluetoothDeviceInfoPrivate::QBluetoothDeviceInfoPrivate() :
     valid(false),
@@ -517,6 +517,8 @@ QBluetoothDeviceInfo::DataCompleteness QBluetoothDeviceInfo::serviceUuidsComplet
 /*!
     Sets the CoreConfiguration of the device to a \a coreConfig. This will help to make a difference
     between regular and Low Energy devices.
+
+    \sa coreConfiguration()
 */
 void QBluetoothDeviceInfo::setCoreConfiguration(const CoreConfiguration &coreConfig)
 {
@@ -528,7 +530,8 @@ void QBluetoothDeviceInfo::setCoreConfiguration(const CoreConfiguration &coreCon
 /*!
     Returns the configuration of the device. If device configuration is not set,
     basic rate device configuration will be returned.
-    \sa setCoreConfiguration
+
+    \sa setCoreConfiguration()
 */
 QBluetoothDeviceInfo::CoreConfiguration QBluetoothDeviceInfo::coreConfiguration() const
 {
diff --git a/src/bluetooth/qbluetoothservicediscoveryagent.cpp b/src/bluetooth/qbluetoothservicediscoveryagent.cpp
index 1d8809a8..864b6d05 100644
--- a/src/bluetooth/qbluetoothservicediscoveryagent.cpp
+++ b/src/bluetooth/qbluetoothservicediscoveryagent.cpp
@@ -105,6 +105,12 @@ QT_BEGIN_NAMESPACE
 */
 
 /*!
+    \fn QBluetoothServiceDiscoveryAgent::serviceDiscovered(const QLowEnergyServiceInfo &info)
+
+    This signal is emitted when the Bluetooth Low Energy service described by \a info is discovered.
+*/
+
+/*!
     \fn QBluetoothServiceDiscoveryAgent::finished()
 
     This signal is emitted when the Bluetooth service discovery completes.
diff --git a/src/bluetooth/qlowenergycontroller.cpp b/src/bluetooth/qlowenergycontroller.cpp
index afb9831a..fb60e4df 100644
--- a/src/bluetooth/qlowenergycontroller.cpp
+++ b/src/bluetooth/qlowenergycontroller.cpp
@@ -54,12 +54,12 @@ QT_BEGIN_NAMESPACE
 
     To read data contained in LE service characteristics, the LE device must be paired and turned on.
     First, connect necessary signals from the class and then connect to service by passing the wanted service
-    to \l connectoToService() function. \l connected() signal will be emitted on success or \l error()
+    to \l connectToService() function. \l connected() signal will be emitted on success or \l error()
     signal in case of failure. It is possible to get error message by calling errorString function
     in QLowEnergyServiceInfo class.
 
     In case of disconnecting from service, pass the wanted service to \l disconnectFromService()
-    function and \l disconnected signal will be emitted.
+    function and \l disconnected() signal will be emitted.
 
     It is enough to use one instance of this class to connect to more service on more devices,
     but it is not possible to create more QLowEnergyController classes and connect to same
@@ -83,44 +83,46 @@ QT_BEGIN_NAMESPACE
 */
 
 /*!
-    \fn void QLowEnergyController::connected(const QLowEnergyServiceInfo &)
+    \fn void QLowEnergyController::connected(const QLowEnergyServiceInfo &info)
 
-    This signal is emitted when a LE service is connected, passing connected QLowEnergyServiceInfo
-    instance.
+    This signal is emitted when the connection to the Bluetooth Low Energy service
+    \a info was established.
 
-    \sa connectToService(const QLowEnergyServiceInfo &leService)
+    \sa disconnected(), connectToService()
 */
 
 /*!
-    \fn void QLowEnergyController::error(const QLowEnergyServiceInfo &, QLowEnergyController::Error)
+    \fn void QLowEnergyController::error(const QLowEnergyServiceInfo &info, QLowEnergyController::Error error)
 
-    This signal is emitted when the service error occurs.
+    This signal is emitted when the service \a info triggered an \a error.
 
     \sa errorString()
 */
 
 /*!
-    \fn void QLowEnergyController::error(const QLowEnergyCharacteristicInfo &, QLowEnergyController::Error)
+    \fn void QLowEnergyController::error(const QLowEnergyCharacteristicInfo &info, QLowEnergyController::Error error)
 
-    This signal is emitted when the characteristic error occurs.
+    This signal is emitted when the characteristic \a info triggered an \a error.
 
     \sa errorString()
 */
 
 /*!
-    \fn void QLowEnergyController::disconnected(const QLowEnergyServiceInfo &)
+    \fn void QLowEnergyController::disconnected(const QLowEnergyServiceInfo &info)
 
-    Emits disconnected signal with disconnected LE service.
+    This signal is emitted when the connection to the Bluertooth Low Energy service \a info
+    was severed.
+
+    \sa connected(), disconnectFromService()
 */
 
 /*!
-    \fn QLowEnergyController::valueChanged(const QLowEnergyCharacteristicInfo &)
+    \fn QLowEnergyController::valueChanged(const QLowEnergyCharacteristicInfo &info)
 
-    Emits a signal when the characteristic value is changed. This signal is emitted
-    after calling \l enableNotifications(const QLowEnergyCharacteristicInfo &characteristic)
-    function.
+    Emits a signal when the value of \a info has changed. This signal is only emitted
+    once the \l enableNotifications() function was called.
 
-    \sa enableNotifications(const QLowEnergyCharacteristicInfo &characteristic)
+    \sa enableNotifications()
 */
 
 
@@ -155,7 +157,7 @@ QLowEnergyController::~QLowEnergyController()
 }
 
 /*!
-    Returns the list of all Bluetooth LE Services that were added.
+    Returns the list of all Bluetooth Low Energy services managed by this controller instance.
 */
 QList<QLowEnergyServiceInfo> QLowEnergyController::services() const
 {
@@ -176,7 +178,7 @@ void QLowEnergyController::connectToService(const QLowEnergyServiceInfo &leServi
 /*!
     Disconnects the given \a leService. If the given service was not connected, nothing will be done.
 
-    If the \a leService is not passed or it is invalid, all connected services will be disconnected.
+    If \a leService is invalid, all connected services will be disconnected.
 
 */
 void QLowEnergyController::disconnectFromService(const QLowEnergyServiceInfo &leService)
@@ -197,9 +199,7 @@ bool QLowEnergyController::enableNotifications(const QLowEnergyCharacteristicInf
 
 /*!
     Disables receiving notifications from the given \a characteristic. If the service characteristic
-    does not belong to one of the services, nothing wil lbe done.
-
-    \sa addLeService
+    does not belong to one of the services, nothing will be done.
 */
 void QLowEnergyController::disableNotifications(const QLowEnergyCharacteristicInfo &characteristic)
 {
@@ -208,8 +208,6 @@ void QLowEnergyController::disableNotifications(const QLowEnergyCharacteristicIn
 
 /*!
     Returns a human-readable description of the last error that occurred.
-
-    \sa error(const QLowEnergyServiceInfo &), error(const QLowEnergyCharacteristicInfo &)
 */
 QString QLowEnergyController::errorString() const
 {
@@ -226,9 +224,10 @@ void QLowEnergyController::setRandomAddress()
 }
 
 /*!
-    This method writes the wanted \a characteristic taking its value. This value is written directly
-    to the Bluetooth Low Energy device. In case wanted characteristic is not connected or does not
-    have write permission, it will return false with the corresponding error string.
+    This method writes \a characteristic using its current value. The value is directly written
+    to the Bluetooth Low Energy device. If the service associated to \a characteristic is not
+    connected or does not have write permission, the function returns \c false with
+    a corresponding \l errorString() being set.
 
     \sa QLowEnergyCharacteristicInfo::setValue(), errorString(), error()
  */
@@ -238,11 +237,11 @@ bool QLowEnergyController::writeCharacteristic(const QLowEnergyCharacteristicInf
 }
 
 /*!
-    This method writes the wanted \a descriptor taking its value. This value is written directly
-    to the Bluetooth Low Energy device. In case wanted descriptor is not connected it will return
-    false with the corresponding error string.
+    This method writes \a descriptor using its current value. The value is directly written
+    to the Bluetooth Low Energy device. If the service associated to \a descriptor is not
+    connected it returns \c false with a corresponding \l errorString() being set.
 
-    \sa QLowEnergyDescriptorInfo::setValue(), errorString(), error()
+    \sa QLowEnergyDescriptorInfo::setValue(), errorString()
  */
 bool QLowEnergyController::writeDescriptor(const QLowEnergyDescriptorInfo &descriptor)
 {
@@ -250,9 +249,9 @@ bool QLowEnergyController::writeDescriptor(const QLowEnergyDescriptorInfo &descr
 }
 
 /*!
-    This method returns the last error that was emitted.
+    This method returns the last occurred error.
 
-    \sa errorString(), error()
+    \sa errorString()
  */
 QLowEnergyController::Error QLowEnergyController::error() const
 {
diff --git a/src/bluetooth/qlowenergyprocess_bluez.cpp b/src/bluetooth/qlowenergyprocess_bluez.cpp
index dc556ed3..9f94da4f 100644
--- a/src/bluetooth/qlowenergyprocess_bluez.cpp
+++ b/src/bluetooth/qlowenergyprocess_bluez.cpp
@@ -48,10 +48,10 @@ QT_BEGIN_NAMESPACE
 Q_GLOBAL_STATIC(QLowEnergyProcess, processInstance)
 Q_DECLARE_LOGGING_CATEGORY(QT_BT_BLUEZ)
 
-/*!
- * Private constructor. Constructs the new QLowEnergyProcess, sets variables and connects
- * signal to a slot.
- */
+/*
+    Private constructor. Constructs the new QLowEnergyProcess, sets variables and connects
+    signal to a slot.
+*/
 QLowEnergyProcess::QLowEnergyProcess()
 {
     m_process = new QProcess();
@@ -60,7 +60,7 @@ QLowEnergyProcess::QLowEnergyProcess()
     connect(m_process, SIGNAL(readyReadStandardOutput()), this, SLOT(replyRead()));
 }
 
-/*!
+/*
     Destroys the QLowEnergyProcess object.
 */
 QLowEnergyProcess::~QLowEnergyProcess()
@@ -69,8 +69,8 @@ QLowEnergyProcess::~QLowEnergyProcess()
     delete m_process;
 }
 
-/*!
-    Returns the instance of this class. This class is a singleton class.
+/*
+    Returns the singleton instance of this class.
 */
 
 QLowEnergyProcess *QLowEnergyProcess::instance()
@@ -78,7 +78,7 @@ QLowEnergyProcess *QLowEnergyProcess::instance()
     return processInstance();
 }
 
-/*!
+/*
     Slot that emits a signal replySend. This slot is connected with QProcess signal
     and it is called whenever something comes to output.
 */
@@ -90,7 +90,7 @@ void QLowEnergyProcess::replyRead()
         emit replySend(back);
 }
 
-/*!
+/*
     Starts the process with \a command. This method is used only when starting the
     process.
 
@@ -103,7 +103,7 @@ void QLowEnergyProcess::startCommand(const QString &command)
         qDebug() << "Could not start the process under the command: "<<command;
 }
 
-/*!
+/*
     Executes the \a command. This method is called after process started.
 
     \sa startCommand()
@@ -115,7 +115,7 @@ void QLowEnergyProcess::executeCommand(const QString &command)
     m_process->write(cmd.constData());
 }
 
-/*!
+/*
     Terminate running process.
 */
 void QLowEnergyProcess::endProcess()
diff --git a/src/bluetooth/qlowenergyprocess_p.cpp b/src/bluetooth/qlowenergyprocess_p.cpp
index 3303bef0..3bbacdbf 100644
--- a/src/bluetooth/qlowenergyprocess_p.cpp
+++ b/src/bluetooth/qlowenergyprocess_p.cpp
@@ -46,7 +46,7 @@ QLowEnergyProcess::QLowEnergyProcess()
 
 }
 
-/*!
+/*
     Destroys the QLowEnergyProcess object.
 */
 QLowEnergyProcess::~QLowEnergyProcess()
@@ -54,8 +54,8 @@ QLowEnergyProcess::~QLowEnergyProcess()
 
 }
 
-/*!
-    Returns the instance of this class. This class is a singleton class.
+/*
+    Returns the singleton instance of this class.
 */
 QLowEnergyProcess *QLowEnergyProcess::instance()
 {
diff --git a/src/bluetooth/qlowenergyprocess_qnx.cpp b/src/bluetooth/qlowenergyprocess_qnx.cpp
index 05ef2e4e..f7e298de 100644
--- a/src/bluetooth/qlowenergyprocess_qnx.cpp
+++ b/src/bluetooth/qlowenergyprocess_qnx.cpp
@@ -62,7 +62,7 @@ QLowEnergyProcess::QLowEnergyProcess()
 
 }
 
-/*!
+/*
     Destroys the QLowEnergyProcess object.
 */
 QLowEnergyProcess::~QLowEnergyProcess()
@@ -73,8 +73,8 @@ QLowEnergyProcess::~QLowEnergyProcess()
     m_classPointers.clear();
 }
 
-/*!
-    Returns the instance of this clas. This class is a singleton class.
+/*
+    Returns the singleton instance of this class.
 */
 
 QLowEnergyProcess *QLowEnergyProcess::instance()
diff --git a/src/bluetooth/qlowenergyserviceinfo.cpp b/src/bluetooth/qlowenergyserviceinfo.cpp
index c820e51c..8c263c3d 100644
--- a/src/bluetooth/qlowenergyserviceinfo.cpp
+++ b/src/bluetooth/qlowenergyserviceinfo.cpp
@@ -163,7 +163,7 @@ QLowEnergyServiceInfo::ServiceType QLowEnergyServiceInfo::serviceType() const
 }
 
 /*!
-    Makes a copy of the \a other and assigns it to this QLowEnergyServiceInfo object.
+    Returns a copy of \a other and assigns it to this QLowEnergyServiceInfo object.
     The two copies continue to share the same service and registration details.
 */
 QLowEnergyServiceInfo &QLowEnergyServiceInfo::operator=(const QLowEnergyServiceInfo &other)
@@ -173,7 +173,7 @@ QLowEnergyServiceInfo &QLowEnergyServiceInfo::operator=(const QLowEnergyServiceI
 }
 
 /*!
-    Checks whether service is connected.
+    Returns \c true if this service is connected; otherwise returns \c false.
  */
 bool QLowEnergyServiceInfo::isConnected() const
 {