Fix/update comments for calbacks

Signed-off-by: NAlexis BRENON <brenon.alexis@gmail.com>

src/paho/mqtt/client.py

@@ -1323,27 +1323,41 @@ class Client(object):
 
     @property
     def on_log(self):
-        """Called when the client has log information if implemented.
-
-        Define to allow debugging.
-
-        level:  gives the severity of the message and will be one of
-                MQTT_LOG_INFO, MQTT_LOG_NOTICE, MQTT_LOG_WARNING, MQTT_LOG_ERR, and
-                MQTT_LOG_DEBUG.
-        buf:    the message itself
-        """
+        """If implemented, called when the client has log information.
+        Defined to allow debugging."""
         return self._on_log
 
     @on_log.setter
     def on_log(self, func):
+        """ Define the logging callback implementation.
+
+        Expected signature is:
+            log_callback(client, userdata, level, buf)
+
+        client:     the client instance for this callback
+        userdata:   the private user data as set in Client() or userdata_set()
+        level:      gives the severity of the message and will be one of
+                    MQTT_LOG_INFO, MQTT_LOG_NOTICE, MQTT_LOG_WARNING,
+                    MQTT_LOG_ERR, and MQTT_LOG_DEBUG.
+        buf:        the message itself
+        """
         self._on_log = func
 
     @property
     def on_connect(self):
-        """Called when the broker responds to our connection request if implemented.
+        """If implemented, called when the broker responds to our connection
+        request."""
+        return self._on_connect
+
+    @on_connect.setter
+    def on_connect(self, func):
+        """ Define the connect callback implementation.
 
-        self:       the client instance for this callback
-        userdata:   the private user data as set in ``Client()`` or ``userdata_set()``
+        Expected signature is:
+            connect_callback(client, userdata, flags, rc)
+
+        client:     the client instance for this callback
+        userdata:   the private user data as set in Client() or userdata_set()
         flags:      response flags sent by the broker
         rc:         the connection result
 
@@ -1363,100 +1377,121 @@ class Client(object):
             5: Connection refused - not authorised
             6-255: Currently unused.
         """
-        return self._on_connect
-
-    @on_connect.setter
-    def on_connect(self, func):
         self._on_connect = func
 
     @property
     def on_subscribe(self):
-        """Called when the broker responds to a subscribe request if implemented.
+        """If implemented, called when the broker responds to a subscribe
+        request."""
+        return self._on_subscribe
+
+    @on_subscribe.setter
+    def on_subscribe(self, func):
+        """ Define the suscribe callback implementation.
 
+        Expected signature is:
+            subscribe_callback(client, userdata, mid, granted_qos)
+
+        client:         the client instance for this callback
+        userdata:       the private user data as set in Client() or userdata_set()
         mid:            matches the mid variable returned from the corresponding
                         subscribe() call.
         granted_qos:    list of integers that give the QoS level the broker has
                         granted for each of the different subscription requests.
         """
-        return self._on_subscribe
-
-    @on_subscribe.setter
-    def on_subscribe(self, func):
         self._on_subscribe = func
 
     @property
     def on_message(self):
-        """Called when a message has been received on a topic that the client
-        subscribes to if implemented.
+        """If implemented, called when a message has been received on a topic
+        that the client subscribes to.
 
         This callback will be called for every message received. Use
-        ``message_callback_add()`` to define multiple callbacks that will be called for
-        specific topic filters.
+        message_callback_add() to define multiple callbacks that will be called
+        for specific topic filters."""
+        return self._on_message
+
+    @on_message.setter
+    def on_message(self, func):
+        """ Define the message received callback implementation.
 
-        self:       the client instance for this callback
+        Expected signature is:
+            on_message_callback(client, userdata, message)
+
+        client:     the client instance for this callback
         userdata:   the private user data as set in Client() or userdata_set()
         message:    an instance of MQTTMessage.
                     This is a class with members topic, payload, qos, retain.
         """
-        return self._on_message
-
-    @on_message.setter
-    def on_message(self, func):
         self._on_message = func
 
     @property
     def on_publish(self):
-        """Called when a message that was to be sent using the publish() call
-        has completed transmission to the broker.
-        This function may be overridden by sub-classes.
+        """If implemented, called when a message that was to be sent using the
+        publish() call has completed transmission to the broker.
 
         For messages with QoS levels 1 and 2, this means that the appropriate
         handshakes have completed. For QoS 0, this simply means that the message
         has left the client.
         This callback is important because even if the publish() call returns
-        success, it does not always mean that the message has been sent.
-
-        mid:    matches the mid variable returned from the corresponding
-                publish() call, to allow outgoing messages to be tracked.
-        """
+        success, it does not always mean that the message has been sent."""
         return self._on_publish
 
     @on_publish.setter
     def on_publish(self, func):
+        """ Define the published message callback implementation.
+
+        Expected signature is:
+            on_publish_callback(client, userdata, mid)
+
+        client:     the client instance for this callback
+        userdata:   the private user data as set in Client() or userdata_set()
+        mid:        matches the mid variable returned from the corresponding
+                    publish() call, to allow outgoing messages to be tracked.
+        """
         self._on_publish = func
 
     @property
     def on_unsubscribe(self):
-        """Called when the broker responds to an unsubscribe request.
-        This function may be overridden by sub-classes.
-
-        mid:    matches the mid variable returned from the corresponding
-                unsubscribe() call.
-        """
+        """If implemented, called when the broker responds to an unsubscribe
+        request."""
         return self._on_unsubscribe
 
     @on_unsubscribe.setter
     def on_unsubscribe(self, func):
-        self._on_unsubscribe = func
+        """ Define the unsubscribe callback implementation.
 
-    @property
-    def on_disconnect(self):
-        """Called when the client disconnects from the broker.
-        This function may be overridden by sub-classes.
+        Expected signature is:
+            unsubscribe_callback(client, userdata, mid)
 
-        self:       the client instance for this callback
+        client:     the client instance for this callback
         userdata:   the private user data as set in Client() or userdata_set()
-        rc:         the disconnection result
+        mid:        matches the mid variable returned from the corresponding
+                    unsubscribe() call.
+        """
+        self._on_unsubscribe = func
 
-        The rc parameter indicates the disconnection state. If MQTT_ERR_SUCCESS
-        (0), the callback was called in response to a disconnect() call. If any
-        other value the disconnection was unexpected, such as might be caused by
-        a network error.
+    @property
+    def on_disconnect(self):
+        """If implemented, called when the client disconnects from the broker.
         """
         return self._on_disconnect
 
     @on_disconnect.setter
     def on_disconnect(self, func):
+        """ Define the disconnect callback implementation.
+
+        Expected signature is:
+            disconnect_callback(client, userdata, self)
+
+        client:     the client instance for this callback
+        userdata:   the private user data as set in Client() or userdata_set()
+        rc:         the disconnection result
+                    The rc parameter indicates the disconnection state. If
+                    MQTT_ERR_SUCCESS (0), the callback was called in response to
+                    a disconnect() call. If any other value the disconnection
+                    was unexpected, such as might be caused by a network error.
+        """
         self._on_disconnect = func
 
     def message_callback_add(self, sub, callback):