BtChat example: document service lookup

Extend the documentation for BtChat example with a section describing
remote service discovery. This allows to completely remove the
PingPong example, because it does not show any new APIs compared to
the BtChat example.

Task-number: QTBUG-111972
Pick-to: 6.5 6.5.0
Change-Id: I9328205b21fe750562c3510815aaa6c8d47640b1
Reviewed-by: Juha Vuolle <juha.vuolle@qt.io>

2 files changed, 34 insertions, 1 deletions

diff --git a/examples/bluetooth/btchat/doc/src/btchat.qdoc b/examples/bluetooth/btchat/doc/src/btchat.qdoc
index 7469a5af..aa0b189b 100644
--- a/examples/bluetooth/btchat/doc/src/btchat.qdoc
+++ b/examples/bluetooth/btchat/doc/src/btchat.qdoc
@@ -97,6 +97,34 @@
 
     \snippet btchat/chatserver.cpp stopServer
 
+    \section1 Service Discovery
+
+    Before connecting to the server, the client needs to scan the nearby
+    devices and search for the device that is advertising the chat service.
+    This is done by the \c RemoteSelector class.
+
+    To start service lookup, the \c RemoteSelector creates an instance of
+    \l QBluetoothServiceDiscoveryAgent and connects to its signals.
+
+    \snippet btchat/remoteselector.cpp createDiscoveryAgent
+
+    An UUID filter is set, so that the service discovery only shows the devices
+    that advertise the needed service. After that a
+    \l {QBluetoothServiceDiscoveryAgent::}{FullDiscovery} is started:
+
+    \snippet btchat/remoteselector.cpp startDiscovery
+
+    When a matching service is discovered, a
+    \l {QBluetoothServiceDiscoveryAgent::}{serviceDiscovered()} signal is
+    emitted with an instance of \l QBluetoothServiceInfo as a parameter. This
+    service info is used to extract the device name and the service name,
+    and add a new entry to the list of discovered remote devices:
+
+    \snippet btchat/remoteselector.cpp serviceDiscovered
+
+    Later the user can select one of the devices from the list and try to
+    connect to it.
+
     \section1 Chat Client
 
     The chat client is implemented by the \c ChatClient class.
diff --git a/examples/bluetooth/btchat/remoteselector.cpp b/examples/bluetooth/btchat/remoteselector.cpp
index a7a9a00e..7ab496bd 100644
--- a/examples/bluetooth/btchat/remoteselector.cpp
+++ b/examples/bluetooth/btchat/remoteselector.cpp
@@ -19,6 +19,7 @@ RemoteSelector::RemoteSelector(const QBluetoothAddress &localAdapter, QWidget *p
     setWindowState(Qt::WindowMaximized);
 #endif
 
+//! [createDiscoveryAgent]
     m_discoveryAgent = new QBluetoothServiceDiscoveryAgent(localAdapter);
 
     connect(m_discoveryAgent, &QBluetoothServiceDiscoveryAgent::serviceDiscovered,
@@ -27,6 +28,7 @@ RemoteSelector::RemoteSelector(const QBluetoothAddress &localAdapter, QWidget *p
             this, &RemoteSelector::discoveryFinished);
     connect(m_discoveryAgent, &QBluetoothServiceDiscoveryAgent::canceled,
             this, &RemoteSelector::discoveryFinished);
+//! [createDiscoveryAgent]
 }
 
 RemoteSelector::~RemoteSelector()
@@ -43,9 +45,10 @@ void RemoteSelector::startDiscovery(const QBluetoothUuid &uuid)
 
     ui->remoteDevices->clear();
 
+//! [startDiscovery]
     m_discoveryAgent->setUuidFilter(uuid);
     m_discoveryAgent->start(QBluetoothServiceDiscoveryAgent::FullDiscovery);
-
+//! [startDiscovery]
 }
 
 void RemoteSelector::stopDiscovery()
@@ -80,6 +83,7 @@ void RemoteSelector::serviceDiscovered(const QBluetoothServiceInfo &serviceInfo)
             return;
     }
 
+//! [serviceDiscovered]
     QString remoteName;
     if (serviceInfo.device().name().isEmpty())
         remoteName = address.toString();
@@ -92,6 +96,7 @@ void RemoteSelector::serviceDiscovered(const QBluetoothServiceInfo &serviceInfo)
 
     m_discoveredServices.insert(item, serviceInfo);
     ui->remoteDevices->addItem(item);
+//! [serviceDiscovered]
 }
 
 void RemoteSelector::discoveryFinished()