Create Qt5.15 to 6.2 migration documentation for QtBluetooth

Task-number: QTBUG-90920
Change-Id: I1d99a7f6c6cd0f5f890c65c052ea8ceb87760275
Reviewed-by: Alex Blasche <alexander.blasche@qt.io>
(cherry picked from commit 2e8e58b0eca8b060e02e6b65b57bf14a6a6313ed)
Reviewed-by: Qt Cherry-pick Bot <cherrypick_bot@qt-project.org>

3 files changed, 154 insertions, 119 deletions

diff --git a/src/bluetooth/ApiChangesQt6.txt b/src/bluetooth/ApiChangesQt6.txt
deleted file mode 100644
index 079d1c94..00000000
--- a/src/bluetooth/ApiChangesQt6.txt
+++ /dev/null
@@ -1,119 +0,0 @@
-This document lists the API changes done between Qt Bluetooth 5.15 and the first
-QtBluetooth release in the Qt 6 series. This file is temporary in nature to keep track of API
-changes for further documentation later on.
-
-General
--------
-
- - qbluetoothglobal.h was removed. qtbluetoothglobal. is the official header with the same purpose.
-
- - Every usage of QVector has been replaced by QList.
-
- - Win32 backend has been removed. There will not be a working Bluetooth backend when Qt is built with mingw.
-
- - Since there is now only one Windows backend, the logging category qt.bluetooth.winrt was removed.
-   The corresponding log messages are now in qt.bluetooth.windows.
-
-QBluetooth namespace
---------------------
-
- - The enums QBluetooth::Security and QBluetooth::AttAccessConstraint have been changed
-   to a scoped enums for improved type safety.
-
-QBluetoothDeviceDiscoveryAgent
-------------------------------
-
- - QBluetoothDeviceDiscoveryAgent::inquiryType property and related setter/getter & enum were removed.
-   The API element was never implemented and/or supported.
-
-QBluetoothDeviceInfo
---------------------
-
-- manufacturerData() returns a QMultiHash rather than QHash. Since Qt 6
-  QMultiHash no longer derives from QHash.
-
-- DataCompleteness was removed without replacement.
-
-- setServiceUuids(const QList<QBluetoothUuid>, DataCompleteness) was replaced by
-  setServiceUuids(const QList<QBluetoothUuid> &uuids)
-
-- DataCompleteness serviceUuidsCompleteness() const was removed without replacement.
-
-- QList<QBluetoothUuid> serviceUuids(DataCompleteness *completeness = nullptr) const was replaced by
-  QList<QBluetoothUuid> serviceUuids() const.
-
-QBluetoothLocalDevice
----------------------
-
-- Pairing agent related API was removed without replacement. This includes pairingConfirmation(bool),
-  pairingDisplayPinCode(..) & pairingDisplayConfirmation(..). Except for Android and BlueZ 4 there was
-  never an implementation for it. Bluez 4 support was removed in Qt 6 and Android's implementation
-  required unobtainable BLUETOOTH_PRIVILEGED for at least parts of the code.
-
-QLowEnergyService
------------------
-
- - Renamed ServiceState enum values:
-   - "DiscoveryRequired" becomes "RemoteService"
-   - "DiscoveringServices" becomes "RemoteServiceDiscovering"
-   - "ServiceDiscovered" becomes "RemoteServiceDiscovered"
-   This change happens in anticipation that service discovery might become an optional
-   step in the future.
-
-QBluetoothUuid
---------------
-
- - enums ProtocolUuid, ServiceClassUuid, CharacteristicType, and DescriptorType are now scoped enums.
-   Usage of enum items has to be adapted in user code.
-
-QLowEnergyController
---------------------
-
- - Existing ctors and create*() functions with remote QBluetoothAddress parameters have been removed. QBluetoothAddress
-   is not sufficient to indicate remote devices on Apple systems. It requires UUIDs to "name" devices. This can only
-   be satisfied by QBluetoothDeviceInfo.
-
- - Remaining QLowEnergyController ctors have been made private. The createPeripheral() and createCentral() functions
-   should be used to obtain QLowEnergyController instances.
-
-QLowEnergyCharacteristic
-------------------------
-
- - New method clientCharacteristicConfiguration() have been introduced to conveniently obtain the
-   Client Characteristic Configuration Descriptor.
- - Constants CCCDDisable, CCCDEnableNotification, and CCCDEnableIndication have been introduced
-   which hold the possible values for the Client Characteristic Configuration Descriptor.
- - The handle() method is no longer part of the public interface.
-
-QLowEnergyDescriptor
---------------------
-
- - The handle() method is no longer part of the public interface.
-
-QBluetoothTransferManager
--------------------------
-
- - QBluetoothTransferManager, QBluetoothTransferRequest, and QBluetoothTransferReply have been removed
-   without replacement.
-
-QBluetoothSocket
--------------------------
-
- - QBluetoothSocket::SocketState and QBluetoothSocket::SocketError are now scoped enums. Usage of enum
-   items has to be adapted in user code.
-
-QML Interface
--------------
-
- - The QML interface has been removed because socket programming via QML is not advisable.
-   QDeclarativeBluetoothService, QDeclarativeBluetoothSocket, and QDeclarativeBluetoothDiscoveryModel
-   (in QML: BluetoothService, BluetoothSocket, and BluetoothDiscoveryModel)
-   have been removed without replacement.
-
-"error" signals
----------------
-
- - The "error" signals in QBluetoothDeviceDiscoveryAgent, QBluetoothLocalDevice, QBluetoothServer,
-   QBluetoothServiceDiscoveryAgent, QBluetoothSocket, QLowEnergyController, and QLowEnergyService
-   have been renamed to "errorOccurred" to remove ambiguities between the "error" signal and the
-   "error" getter.
diff --git a/src/bluetooth/doc/qt6-changes.qdoc b/src/bluetooth/doc/qt6-changes.qdoc
new file mode 100644
index 00000000..468263c5
--- /dev/null
+++ b/src/bluetooth/doc/qt6-changes.qdoc
@@ -0,0 +1,149 @@
+/****************************************************************************
+**
+** Copyright (C) 2021 The Qt Company Ltd.
+** Contact: https://www.qt.io/licensing/
+**
+** This file is part of the documentation of the Qt Toolkit.
+**
+** $QT_BEGIN_LICENSE:FDL$
+** Commercial License Usage
+** Licensees holding valid commercial Qt licenses may use this file in
+** accordance with the commercial license agreement provided with the
+** Software or, alternatively, in accordance with the terms contained in
+** a written agreement between you and The Qt Company. For licensing terms
+** and conditions see https://www.qt.io/terms-conditions. For further
+** information use the contact form at https://www.qt.io/contact-us.
+**
+** GNU Free Documentation License Usage
+** Alternatively, this file may be used under the terms of the GNU Free
+** Documentation License version 1.3 as published by the Free Software
+** Foundation and appearing in the file included in the packaging of
+** this file. Please review the following information to ensure
+** the GNU Free Documentation License version 1.3 requirements
+** will be met: https://www.gnu.org/licenses/fdl-1.3.html.
+** $QT_END_LICENSE$
+**
+****************************************************************************/
+
+/*!
+    \page qtbluetooth-changes-qt6.html
+    \title Changes to Qt Bluetooth
+    \ingroup changes-qt-5-to-6
+    \brief Migrate QtBluetooth to Qt 6.
+
+    Qt 6 is a result of the conscious effort to make the framework more
+    efficient and easy to use.
+
+    We try to maintain binary and source compatibility for all the public
+    APIs in each release. But some changes were inevitable in an effort to
+    make Qt a better framework.
+
+    In this topic we summarize those changes in QtBluetooth, and provide guidance
+    to handle them.
+
+    \section1 General
+
+     - qbluetoothglobal.h was removed. qtbluetoothglobal.h is the official header with the same purpose.
+
+     - Every usage of QVector has been replaced by QList.
+
+     - Win32 backend has been removed. There will not be a working Bluetooth backend when Qt is built with mingw.
+
+     - Since there is now only one Windows backend, the logging category qt.bluetooth.winrt was removed.
+       The corresponding log messages are now in qt.bluetooth.windows.
+
+    \section1 QBluetooth namespace
+
+     - The enums QBluetooth::Security and QBluetooth::AttAccessConstraint have been changed
+       to a scoped enums for improved type safety.
+
+    \section1 QBluetoothDeviceDiscoveryAgent
+
+     - QBluetoothDeviceDiscoveryAgent::inquiryType property and related setter/getter & enum were removed.
+       The API element was never implemented and/or supported.
+
+    \section1 QBluetoothDeviceInfo
+
+    - manufacturerData() returns a QMultiHash rather than QHash. Since Qt 6
+      QMultiHash is no longer derived from QHash.
+
+    - DataCompleteness was removed without replacement as the related API elements
+      no longer served a purpose
+
+    - setServiceUuids(const QList<QBluetoothUuid>, DataCompleteness) was replaced by
+      setServiceUuids(const QList<QBluetoothUuid> &uuids)
+
+    - DataCompleteness serviceUuidsCompleteness() const was removed without replacement.
+
+    - QList<QBluetoothUuid> serviceUuids(DataCompleteness *completeness = nullptr) const was replaced by
+      QList<QBluetoothUuid> serviceUuids() const.
+
+    \section1 QBluetoothLocalDevice
+
+    - The pairing agent related API was removed without replacement. This includes pairingConfirmation(bool),
+      pairingDisplayPinCode(..) & pairingDisplayConfirmation(..). Except for Android and BlueZ 4 there was
+      never an implementation for it. Bluez 4 support was removed in Qt 6 and Android's implementation
+      required unobtainable BLUETOOTH_PRIVILEGED for at least parts of the code.
+
+    \section1 QLowEnergyService
+
+     - Renamed ServiceState enum values:
+       - "DiscoveryRequired" becomes "RemoteService"
+       - "DiscoveringServices" becomes "RemoteServiceDiscovering"
+       - "ServiceDiscovered" becomes "RemoteServiceDiscovered"
+       This change happens in anticipation that service discovery might become an optional
+       step in the future.
+
+    \section1 QBluetoothUuid
+
+     - enums ProtocolUuid, ServiceClassUuid, CharacteristicType, and DescriptorType are now scoped enums.
+       The usage of enum items has to be adapted in user code.
+
+    \section1 QLowEnergyController
+
+     - Existing ctors and create*() functions with remote QBluetoothAddress parameters have been removed. QBluetoothAddress
+       is not sufficient to indicate remote devices on Apple systems. It requires UUIDs to "name" devices. This can only
+       be satisfied by QBluetoothDeviceInfo.
+
+     - Remaining QLowEnergyController ctors have been made private. The createPeripheral() and createCentral() functions
+       should be used to obtain QLowEnergyController instances.
+
+    \section1 QLowEnergyCharacteristic
+
+     - The new method clientCharacteristicConfiguration() has been introduced to conveniently obtain the
+       Client Characteristic Configuration Descriptor.
+     - The constants CCCDDisable, CCCDEnableNotification, and CCCDEnableIndication have been introduced
+       which hold the possible values for the Client Characteristic Configuration Descriptor.
+     - The handle() method is no longer part of the public Bluetooth LE interfaces. It's purpose as identifier
+       for characteristics was replaced. The QLowEnergyCharacteristic instances itself serve as identifier.
+
+    \section1 QLowEnergyDescriptor
+
+     - The handle() method is no longer part of the public Bluetooth LE interfaces. It's purpose as identifier
+       for descriptors was replaced. The QLowEnergyDescriptor instances itself serve as identifier.
+
+    \section1 QBluetoothTransferManager
+
+     - QBluetoothTransferManager, QBluetoothTransferRequest, and QBluetoothTransferReply have been removed
+       without replacement.
+
+    \section1 QBluetoothSocket
+
+     - QBluetoothSocket::SocketState and QBluetoothSocket::SocketError are now scoped enums. The usage of enum
+       items has to be adapted in user code.
+
+    \section1 QML Interface
+
+     - The QML interface has been removed because socket programming via QML is not advisable.
+       QDeclarativeBluetoothService, QDeclarativeBluetoothSocket, and QDeclarativeBluetoothDiscoveryModel
+       (in QML: BluetoothService, BluetoothSocket, and BluetoothDiscoveryModel)
+       have been removed without replacement.
+
+    \section1 "error" signals
+
+     - The "error" signals in QBluetoothDeviceDiscoveryAgent, QBluetoothLocalDevice, QBluetoothServer,
+       QBluetoothServiceDiscoveryAgent, QBluetoothSocket, QLowEnergyController, and QLowEnergyService
+       have been renamed to "errorOccurred" to remove ambiguities between the "error" signal and the
+       "error" getter.
+
+*/
diff --git a/src/bluetooth/doc/src/bluetooth-index.qdoc b/src/bluetooth/doc/src/bluetooth-index.qdoc
index 4de94895..f71f015e 100644
--- a/src/bluetooth/doc/src/bluetooth-index.qdoc
+++ b/src/bluetooth/doc/src/bluetooth-index.qdoc
@@ -190,6 +190,11 @@ A quick way to enable all QtBluetooth logging is to add the following line to th
     \endlist
 \endlist
 
+\section1 Module Evolution
+
+\l{Changes to Qt Bluetooth} lists important changes in the module
+API and functionality that were done for the Qt 6 series of Qt.
+
 \section1 Licenses and Attributions
 
 Qt Bluetooth is available under commercial licenses from \l{The Qt Company}.