From 2a18c00c2a8bc8e11159485312e251100ed34c12 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Kai=20K=C3=B6hne?= <kai.koehne@qt.io>
Date: Mon, 15 Jan 2024 16:40:43 +0100
Subject: [PATCH] Doc: Improve documentation around setting
 ALLOW_INTERACTIVE_AUTHORIZATION in D-Bus

Change-Id: I4830b375c5f8c7986985c1d6caddc51348fb45ed
Reviewed-by: Thiago Macieira <thiago.macieira@intel.com>
(cherry picked from commit 4c86f9b8049ad7717988125c725492febc44010b)
Reviewed-by: Qt Cherry-pick Bot <cherrypick_bot@qt-project.org>
---
 src/dbus/qdbusabstractinterface.cpp | 26 ++++++++++++++++++------
 src/dbus/qdbusmessage.cpp           | 31 +++++++++++++++++------------
 2 files changed, 38 insertions(+), 19 deletions(-)

diff --git a/src/dbus/qdbusabstractinterface.cpp b/src/dbus/qdbusabstractinterface.cpp
index f0a5032d5cb..6dd3c23b0d4 100644
--- a/src/dbus/qdbusabstractinterface.cpp
+++ b/src/dbus/qdbusabstractinterface.cpp
@@ -398,12 +398,22 @@ int QDBusAbstractInterface::timeout() const
 }
 
 /*!
-    When passed \a enable = \c true it causes all consecutive DBus calls made via
-    this interface to have the InteractiveAuthorizationAllowed flag set. Passing
-    false disables this behavior.
+    Configures whether, for asynchronous calls, the caller
+    is prepared to wait for interactive authorization.
+
+    If \a enable is set to \c true, the D-Bus messages generated for
+    asynchronous calls via this interface will set the
+    \c ALLOW_INTERACTIVE_AUTHORIZATION flag.
+
+    This flag is only useful when unprivileged code calls a more privileged
+    method call, and an authorization framework is deployed that allows
+    possibly interactive authorization.
+
+    The default is \c false.
 
     \since 6.7
-    \sa QDBusMessage::setInteractiveAuthorizationAllowed()
+    \sa QDBusMessage::setInteractiveAuthorizationAllowed(),
+        interactiveAuthorizationAllowed()
 */
 void QDBusAbstractInterface::setInteractiveAuthorizationAllowed(bool enable)
 {
@@ -411,10 +421,14 @@ void QDBusAbstractInterface::setInteractiveAuthorizationAllowed(bool enable)
 }
 
 /*!
-    Returns the current value of the InteractiveAuthorizationAllowed flag.
+    Returns whether, for asynchronous calls, the caller
+    is prepared to wait for interactive authorization.
+
+    The default is \c false.
 
     \since 6.7
-    \sa QDBusMessage::setInteractiveAuthorizationAllowed()
+    \sa setInteractiveAuthorizationAllowed(),
+        QDBusMessage::setInteractiveAuthorizationAllowed()
 */
 bool QDBusAbstractInterface::isInteractiveAuthorizationAllowed() const
 {
diff --git a/src/dbus/qdbusmessage.cpp b/src/dbus/qdbusmessage.cpp
index a43a86df22b..6ef762f2257 100644
--- a/src/dbus/qdbusmessage.cpp
+++ b/src/dbus/qdbusmessage.cpp
@@ -694,20 +694,26 @@ bool QDBusMessage::autoStartService() const
 }
 
 /*!
-    Sets the interactive authorization flag to \a enable.
-    This flag only makes sense for method call messages, where it
-    tells the D-Bus server that the caller of the method is prepared
-    to wait for interactive authorization to take place (for instance
-    via Polkit) before the actual method is processed.
+    Enables or disables the \c ALLOW_INTERACTIVE_AUTHORIZATION flag
+    in a message.
 
-    By default this flag is false and the other end is expected to
-    make any authorization decisions non-interactively and promptly.
+    This flag only makes sense for method call messages
+    (\l QDBusMessage::MethodCallMessage). If \a enable
+    is set to \c true, the flag indicates to the callee that the
+    caller of the method is prepared to wait for interactive authorization
+    to take place (for instance via Polkit) before the actual method
+    is processed.
+
+    If \a enable is set to \c false, the flag is not
+    set, meaning that the other end is expected to make any authorization
+    decisions non-interactively and promptly. This is the default.
 
     The \c org.freedesktop.DBus.Error.InteractiveAuthorizationRequired
     error indicates that authorization failed, but could have succeeded
     if this flag had been set.
 
-    \sa isInteractiveAuthorizationAllowed()
+    \sa isInteractiveAuthorizationAllowed(),
+        QDBusAbstractInterface::setInteractiveAuthorizationAllowed()
 
     \since 5.12
 */
@@ -717,12 +723,11 @@ void QDBusMessage::setInteractiveAuthorizationAllowed(bool enable)
 }
 
 /*!
-    Returns the interactive authorization allowed flag, as set by
-    setInteractiveAuthorizationAllowed(). By default this flag
-    is false and the other end is expected to make any authorization
-    decisions non-interactively and promptly.
+    Returns whether the message has the
+    \c ALLOW_INTERACTIVE_AUTHORIZATION flag set.
 
-    \sa setInteractiveAuthorizationAllowed()
+    \sa setInteractiveAuthorizationAllowed(),
+        QDBusAbstractInterface::isInteractiveAuthorizationAllowed()
 
     \since 5.12
 */