From 6c89a9d606bf38974a7de5d35b545841fca2f9fc Mon Sep 17 00:00:00 2001
From: Thiago Macieira <thiago.macieira@intel.com>
Date: Sat, 3 Feb 2024 19:01:21 -0800
Subject: [PATCH] QDBusAbstractInterface/Doc: fix example to match the
 description

The docs say "This example illustrates function calling with 0, 1 and 2
parameters" because it was copied from the synchronous call()
documentation. But the snippet didn't do that, because back in Qt 4 when
this was created, it was too difficult to exemplify that for
asynchronous use. It now no longer is, with lambdas.

Drive-by update the docs for both functions to refer to each other.

Fixes: QTBUG-121873
Pick-to: 6.6
Change-Id: I664b9f014ffc48cbb49bfffd17b089b7f77c1cde
Reviewed-by: Ievgenii Meshcheriakov <ievgenii.meshcheriakov@qt.io>
(cherry picked from commit 9e73917537368d1904cc227da3332e970ad23752)
Reviewed-by: Qt Cherry-pick Bot <cherrypick_bot@qt-project.org>
---
 .../code/src_qdbus_qdbusabstractinterface.cpp | 20 ++++++++++++++-----
 src/dbus/qdbusabstractinterface.cpp           |  2 ++
 2 files changed, 17 insertions(+), 5 deletions(-)

diff --git a/src/dbus/doc/snippets/code/src_qdbus_qdbusabstractinterface.cpp b/src/dbus/doc/snippets/code/src_qdbus_qdbusabstractinterface.cpp
index 85945ac2c7a..92b9dea909c 100644
--- a/src/dbus/doc/snippets/code/src_qdbus_qdbusabstractinterface.cpp
+++ b/src/dbus/doc/snippets/code/src_qdbus_qdbusabstractinterface.cpp
@@ -47,12 +47,22 @@ else
 void Abstract_DBus_Interface::asyncCall()
 {
 //! [1]
-QString value = retrieveValue();
-QDBusPendingCall pcall = interface->asyncCall("Process"_L1, value);
-
-QDBusPendingCallWatcher *watcher = new QDBusPendingCallWatcher(pcall);
+QDBusPendingCall pcall = interface->asyncCall("GetAPIVersion"_L1);
+auto watcher = new QDBusPendingCallWatcher(pcall, this);
 
 QObject::connect(watcher, &QDBusPendingCallWatcher::finished, this,
-                 &Abstract_DBus_Interface::callFinishedSlot);
+                 [&](QDBusPendingCallWatcher *w) {
+    QString value = retrieveValue();
+    QDBusPendingReply<int> reply(*w);
+    QDBusPendingCall pcall;
+    if (reply.argumentAt<0>() >= 14)
+        pcall = interface->asyncCall("ProcessWorkUnicode"_L1, value);
+    else
+        pcall = interface->asyncCall("ProcessWork"_L1, "UTF-8"_L1, value.toUtf8());
+
+    w = new QDBusPendingCallWatcher(pcall);
+    QObject::connect(w,  &QDBusPendingCallWatcher::finished, this,
+                     &Abstract_DBus_Interface::callFinishedSlot);
+});
 //! [1]
 }
diff --git a/src/dbus/qdbusabstractinterface.cpp b/src/dbus/qdbusabstractinterface.cpp
index 6dd3c23b0d4..8e34fa40e7f 100644
--- a/src/dbus/qdbusabstractinterface.cpp
+++ b/src/dbus/qdbusabstractinterface.cpp
@@ -723,6 +723,7 @@ void QDBusAbstractInterface::internalPropSet(const char *propname, const QVarian
     This example illustrates function calling with 0, 1 and 2 parameters and illustrates different
     parameter types passed in each (the first call to \c "ProcessWorkUnicode" will contain one
     Unicode string, the second call to \c "ProcessWork" will contain one string and one byte array).
+    See asyncCall() for the same example in non-blocking (asynchronous) calls.
 
     \note Before Qt 5.14, this function accepted a maximum of just eight (8) arguments.
 
@@ -780,6 +781,7 @@ void QDBusAbstractInterface::internalPropSet(const char *propname, const QVarian
     This example illustrates function calling with 0, 1 and 2 parameters and illustrates different
     parameter types passed in each (the first call to \c "ProcessWorkUnicode" will contain one
     Unicode string, the second call to \c "ProcessWork" will contain one string and one byte array).
+    See call() for the same example in blocking (synchronous) calls.
 
     \note Before Qt 5.14, this function accepted a maximum of just eight (8) arguments.