Update QLowEnergyDescriptor class documentation.

Change-Id: I65d28f43862e95258c3115b79de839b884966119
Reviewed-by: Leena Miettinen <riitta-leena.miettinen@digia.com>

2 files changed, 44 insertions, 17 deletions

diff --git a/src/bluetooth/qbluetoothuuid.cpp b/src/bluetooth/qbluetoothuuid.cpp
index 3f8487b4..cb802474 100644
--- a/src/bluetooth/qbluetoothuuid.cpp
+++ b/src/bluetooth/qbluetoothuuid.cpp
@@ -397,6 +397,7 @@ Q_GLOBAL_STATIC_WITH_ARGS(QUuid, baseUuid, ("{00000000-0000-1000-8000-00805F9B34
     \value ReportReference                   Mapping information in the form of a Report ID and Report Type which maps the
                                              current parent characteristic to the Report ID(s) and Report Type (s) defined
                                              within the Report Map characteristic.
+    \value UnknownDescriptorType             The descriptor type is unknown.
 */
 
 /*!
diff --git a/src/bluetooth/qlowenergydescriptor.cpp b/src/bluetooth/qlowenergydescriptor.cpp
index 6817d20e..4ff86e7f 100644
--- a/src/bluetooth/qlowenergydescriptor.cpp
+++ b/src/bluetooth/qlowenergydescriptor.cpp
@@ -54,9 +54,18 @@ QT_BEGIN_NAMESPACE
     \since 5.4
 
     QLowEnergyDescriptor provides information about a Bluetooth Low Energy
-    descriptor's name, UUID, value and handle. Descriptors are contained in the
-    Bluetooth Low Energy characteristic and they provide additional information
-    about the characteristic (data format, notification activation, etc).
+    descriptor's \l name(), \l uuid(), \l value() and \l handle(). Descriptors are
+    encapsulated by Bluetooth Low Energy characteristics and provide additional
+    centextual information about the characteristic (data format, notification activation
+    and so on).
+
+    The descriptor value may be written via the \l QLowEnergyService instance
+    that manages the service to which this descriptor belongs. the
+    \l {QLowEnergyService::writeDescriptor()} function writes the new value.
+    The \l {QLowEnergyService::descriptorChanged()} signal
+    is emitted upon success. The \l value() of this object is automatically updated accordingly.
+
+    \sa QLowEnergyService, QLowEnergyCharacteristic
 */
 
 struct QLowEnergyDescriptorPrivate
@@ -66,7 +75,8 @@ struct QLowEnergyDescriptorPrivate
 };
 
 /*!
-    Construct a new QLowEnergyDescriptor.
+    Construct a new QLowEnergyDescriptor. A default-constructed instance
+    of this class is always invalid.
 */
 QLowEnergyDescriptor::QLowEnergyDescriptor():
     d_ptr(0), data(0)
@@ -74,7 +84,7 @@ QLowEnergyDescriptor::QLowEnergyDescriptor():
 }
 
 /*!
-    Construct a new QLowEnergyDesxcriptor that is a copy of \a other.
+    Construct a new QLowEnergyDescriptor that is a copy of \a other.
 
     The two copies continue to share the same underlying data which does not detach
     upon write.
@@ -114,7 +124,7 @@ QLowEnergyDescriptor::~QLowEnergyDescriptor()
 
 /*!
     Makes a copy of \a other and assigns it to this QLowEnergyDescriptor object.
-    The two copies continue to share the same service and registration details.
+    The two copies continue to share the same service and controller details.
 */
 QLowEnergyDescriptor &QLowEnergyDescriptor::operator=(const QLowEnergyDescriptor &other)
 {
@@ -140,7 +150,8 @@ QLowEnergyDescriptor &QLowEnergyDescriptor::operator=(const QLowEnergyDescriptor
     Returns \c true if \a other is equal to this QLowEnergyCharacteristic; otherwise \c false.
 
     Two QLowEnergyDescriptor instances are considered to be equal if they refer to
-    the same descriptor on the same remote Bluetooth Low Energy device.
+    the same descriptor on the same remote Bluetooth Low Energy device or both
+    instances have been default-constructed.
  */
 bool QLowEnergyDescriptor::operator==(const QLowEnergyDescriptor &other) const
 {
@@ -165,7 +176,8 @@ bool QLowEnergyDescriptor::operator==(const QLowEnergyDescriptor &other) const
     Returns \c true if \a other is not equal to this QLowEnergyCharacteristic; otherwise \c false.
 
     Two QLowEnergyDescriptor instances are considered to be equal if they refer to
-    the same descriptor on the same remote Bluetooth Low Energy device.
+    the same descriptor on the same remote Bluetooth Low Energy device  or both
+    instances have been default-constructed.
  */
 bool QLowEnergyDescriptor::operator!=(const QLowEnergyDescriptor &other) const
 {
@@ -175,14 +187,15 @@ bool QLowEnergyDescriptor::operator!=(const QLowEnergyDescriptor &other) const
 /*!
     Returns \c true if the QLowEnergyDescriptor object is valid, otherwise returns \c false.
 
-    An invalid descriptor instance is not associated to any service
-    or the associated service is no longer valid due to for example a disconnect from
-    the underlying Bluetooth Low Energy device. Once the object is invalid
+    An invalid descriptor instance is not associated with any service (default-constructed)
+    or the associated service is no longer valid due to a disconnect from
+    the underlying Bluetooth Low Energy device, for example. Once the object is invalid
     it cannot become valid anymore.
 
     \note If a QLowEnergyDescriptor instance turns invalid due to a disconnect
     from the underlying device, the information encapsulated by the current
-    instance remains as it was at the time of the disconnect.
+    instance remains as it was at the time of the disconnect. Therefore it can be
+    retrieved after the disconnect event.
 */
 bool QLowEnergyDescriptor::isValid() const
 {
@@ -196,7 +209,8 @@ bool QLowEnergyDescriptor::isValid() const
 }
 
 /*!
-    Returns the UUID of this descriptor.
+    Returns the UUID of this descriptor if \l isValid() returns \c true; otherwise a
+    \l {QUuid::isNull()}{null} UUID.
 */
 QBluetoothUuid QLowEnergyDescriptor::uuid() const
 {
@@ -211,7 +225,8 @@ QBluetoothUuid QLowEnergyDescriptor::uuid() const
 }
 
 /*!
-    Returns the handle of the descriptor.
+    Returns the handle of the descriptor or \c 0 if the handle
+    cannot be accessed on the platform.
 */
 QLowEnergyHandle QLowEnergyDescriptor::handle() const
 {
@@ -223,6 +238,9 @@ QLowEnergyHandle QLowEnergyDescriptor::handle() const
 
 /*!
     Returns the value of the descriptor.
+
+    A descriptor value may be updated using
+    \l QLowEnergyService::writeDescriptor().
 */
 QByteArray QLowEnergyDescriptor::value() const
 {
@@ -237,9 +255,15 @@ QByteArray QLowEnergyDescriptor::value() const
 }
 
 /*!
-    Returns the name of the descriptor type.
+    Returns the human-readable name of the descriptor.
+
+    The name is based on the descriptor's \l type(). The complete list
+    of descriptor types can be found under
+    \l {https://developer.bluetooth.org/gatt/descriptors/Pages/DescriptorsHomePage.aspx}{Bluetooth.org Descriptors}.
 
-    \sa type()
+    The returned string is empty if the \l type() is unknown.
+
+    \sa type(), QBluetoothUuid::descriptorToString()
 */
 
 QString QLowEnergyDescriptor::name() const
@@ -248,7 +272,9 @@ QString QLowEnergyDescriptor::name() const
 }
 
 /*!
-    Returns the type of descriptor.
+    Returns the type of the descriptor.
+
+    \sa name()
  */
 QBluetoothUuid::DescriptorType QLowEnergyDescriptor::type() const
 {