Merge branch 'master' of github.com:ChIoT-Tech/paho.mqtt.python into …

…ChIoT-Tech-master

README.rst

@@ -445,8 +445,10 @@ connect()
 
     connect(host, port=1883, keepalive=60, bind_address="")
 
-The ``connect()`` function connects the client to a broker. This is a blocking
-function. It takes the following arguments:
+The ``connect()`` function connects the client to a broker. ``connect()`` blocks until
+the underlying connection is established and a CONNECT packet transmitted.
+Note that the connection status will not be updated until a CONNACK is received and
+processed (this requires a ``loop*()`` function).
 
 host
     the hostname or IP address of the remote broker
@@ -465,6 +467,9 @@ bind_address
     the IP address of a local network interface to bind this client to,
     assuming multiple interfaces exist
 
+Returns MQTT_ERR_SUCCESS if the underlying connection was successfully established
+and an MQTT CONNECT packet sent.
+
 Callback
 ........
 
@@ -474,6 +479,11 @@ before the connection starts, e.g., calling `will_set()`.
 
 When the client receives a CONNACK message from the broker in response to the
 connect it generates an ``on_connect()`` callback.
+When the client ``loop*()`` function receives a CONNACK packet from the broker in
+response to the CONNECT packet it generates an ``on_connect()`` callback.
+
+In most cases the connection should not be used prior to the ``on_connect()`` call
+because the broker may reject the CONNECT packet.
 
 Connect Example
 ...............

src/paho/mqtt/client.py

@@ -867,7 +867,8 @@ def disable_logger(self):
 
     def connect(self, host, port=1883, keepalive=60, bind_address="", bind_port=0,
                 clean_start=MQTT_CLEAN_START_FIRST_ONLY, properties=None):
-        """Connect to a remote broker.
+        """Connect to a remote broker. This is a blocking call that establishes
+        the underlying connection and transmits a CONNECT packet.
 
         host is the hostname or IP address of the remote broker.
         port is the network port of the server host to connect to. Defaults to