diff --git a/src/mqtt/doc/src/overview.qdoc b/src/mqtt/doc/src/overview.qdoc
index 3180f74..b1e9f15 100644
--- a/src/mqtt/doc/src/overview.qdoc
+++ b/src/mqtt/doc/src/overview.qdoc
@@ -179,4 +179,18 @@
     discarded. The broker \e{should} store the last message, but \e{may}
     also discard it. This depends on the implementation of the broker.
 
+    \section1 Threading and Blocking Operations
+
+    Consider running \l QMqttClient and its related classes in a thread
+    separate from the UI thread.\l QMqttClient uses a \l QIODevice as
+    its transport, and some transport operations may block. For example,
+    QMqttClient::disconnectFromHost() may wait synchronously for pending
+    data to be written, with a timeout of up to 30 seconds. Calling it from
+    the UI thread can therefore block the UI event loop and make the
+    application unresponsive. Keeping the MQTT client and its transport in
+    a dedicated thread helps prevent potentially blocking I/O from affecting
+    UI responsiveness. Use signals and slots or other mechanisms that queue
+    work to the target thread to communicate between the MQTT thread and
+    the UI thread.
+
 */
diff --git a/src/mqtt/qmqttclient.cpp b/src/mqtt/qmqttclient.cpp
index 9ec2b0a..2fc87ee 100644
--- a/src/mqtt/qmqttclient.cpp
+++ b/src/mqtt/qmqttclient.cpp
@@ -637,6 +637,11 @@ void QMqttClient::connectToHost(bool encrypted, const QString &sslPeerName)
 
 /*!
     Disconnects from the MQTT broker.
+
+    \note This function may block while waiting for pending data
+    to be written to the transport.
+    See \l {Threading and Blocking Operations} for recommended approaches
+    on handling it.
  */
 void QMqttClient::disconnectFromHost()
 {