From 71c34bdc3acf699be0dabf93ce3fa6b3ba9de11c Mon Sep 17 00:00:00 2001
From: Giacomo Tanganelli <giacomo.tanganelli@for.unipi.it>
Date: Wed, 1 Mar 2017 11:36:56 +0100
Subject: [PATCH] update documentation

---
 coapthon/client/coap.py         |   5 +-
 coapthon/client/helperclient.py | 106 +++++++++++++++++++++++++++++++-
 coapthon/serializer.py          |   4 +-
 3 files changed, 112 insertions(+), 3 deletions(-)

diff --git a/coapthon/client/coap.py b/coapthon/client/coap.py
index 23557e0..f9d934f 100644
--- a/coapthon/client/coap.py
+++ b/coapthon/client/coap.py
@@ -21,12 +21,15 @@
 
 
 class CoAP(object):
+    """
+    Client class to perform requests to remote servers.
+    """
     def __init__(self, server, starting_mid, callback, sock=None):
         """
         Initialize the client.
 
         :param server: Server address for incoming connections
-        :param callback:the calback function to be invoked when a response is received
+        :param callback:the callback function to be invoked when a response is received
         :param starting_mid: used for testing purposes
         :param sock: if a socket has been created externally, it can be used directly
         """
diff --git a/coapthon/client/helperclient.py b/coapthon/client/helperclient.py
index e6adfcb..941f639 100644
--- a/coapthon/client/helperclient.py
+++ b/coapthon/client/helperclient.py
@@ -11,30 +11,63 @@
 
 
 class HelperClient(object):
+    """
+    Helper Client class to perform requests to remote servers in a simplified way.
+    """
     def __init__(self, server, sock=None):
+        """
+        Initialize a client to perform request to a server.
+
+        :param server: the remote CoAP server
+        :param sock: if a socket has been created externally, it can be used directly
+        """
         self.server = server
         self.protocol = CoAP(self.server, random.randint(1, 65535), self._wait_response, sock=sock)
         self.queue = Queue()
 
     def _wait_response(self, message):
+        """
+        Private function to get responses from the server.
+
+        :param message: the received message
+        """
         if message.code != defines.Codes.CONTINUE.number:
             self.queue.put(message)
 
     def stop(self):
+        """
+        Stop the client.
+        """
         self.protocol.stopped.set()
         self.queue.put(None)
         self.protocol.close()
 
     def close(self):
+        """
+        Close the client.
+        """
         self.stop()
 
     def _thread_body(self, request, callback):
+        """
+        Private function. Send a request, wait for response and call the callback function.
+
+        :param request: the request to send
+        :param callback: the callback function
+        """
         self.protocol.send_message(request)
         while not self.protocol.stopped.isSet():
             response = self.queue.get(block=True)
             callback(response)
 
     def cancel_observing(self, response, send_rst):  # pragma: no cover
+        """
+        Delete observing on the remote server.
+
+        :param response: the last received response
+        :param send_rst: if explicitly send RST message
+        :type send_rst: bool
+        """
         if send_rst:
             message = Message()
             message.destination = self.server
@@ -46,22 +79,55 @@ def cancel_observing(self, response, send_rst):  # pragma: no cover
         self.stop()
 
     def get(self, path, callback=None, timeout=None):  # pragma: no cover
+        """
+        Perform a GET on a certain path.
+
+        :param path: the path
+        :param callback: the callback function to invoke upon response
+        :param timeout: the timeout of the request
+        :return: the response
+        """
         request = self.mk_request(defines.Codes.GET, path)
 
         return self.send_request(request, callback, timeout)
 
     def observe(self, path, callback, timeout=None):  # pragma: no cover
+        """
+        Perform a GET with observe on a certain path.
+
+        :param path: the path
+        :param callback: the callback function to invoke upon notifications
+        :param timeout: the timeout of the request
+        :return: the response to the observe request
+        """
         request = self.mk_request(defines.Codes.GET, path)
         request.observe = 0
 
         return self.send_request(request, callback, timeout)
 
     def delete(self, path, callback=None, timeout=None):  # pragma: no cover
+        """
+        Perform a DELETE on a certain path.
+
+        :param path: the path
+        :param callback: the callback function to invoke upon response
+        :param timeout: the timeout of the request
+        :return: the response
+        """
         request = self.mk_request(defines.Codes.DELETE, path)
 
         return self.send_request(request, callback, timeout)
 
     def post(self, path, payload, callback=None, timeout=None):  # pragma: no cover
+        """
+        Perform a POST on a certain path.
+
+        :param path: the path
+        :param payload: the request payload
+        :param callback: the callback function to invoke upon response
+        :param timeout: the timeout of the request
+        :return: the response
+        """
         request = self.mk_request(defines.Codes.POST, path)
         request.token = generate_random_token(2)
         request.payload = payload
@@ -69,17 +135,41 @@ def post(self, path, payload, callback=None, timeout=None):  # pragma: no cover
         return self.send_request(request, callback, timeout)
 
     def put(self, path, payload, callback=None, timeout=None):  # pragma: no cover
+        """
+        Perform a PUT on a certain path.
+
+        :param path: the path
+        :param payload: the request payload
+        :param callback: the callback function to invoke upon response
+        :param timeout: the timeout of the request
+        :return: the response
+        """
         request = self.mk_request(defines.Codes.PUT, path)
         request.payload = payload
 
         return self.send_request(request, callback, timeout)
 
     def discover(self, callback=None, timeout=None):  # pragma: no cover
+        """
+        Perform a Discover request on the server.
+
+        :param callback: the callback function to invoke upon response
+        :param timeout: the timeout of the request
+        :return: the response
+        """
         request = self.mk_request(defines.Codes.GET, defines.DISCOVERY_URL)
 
         return self.send_request(request, callback, timeout)
 
     def send_request(self, request, callback=None, timeout=None):  # pragma: no cover
+        """
+        Send a request to the remote server.
+
+        :param request: the request to send
+        :param callback: the callback function to invoke upon response
+        :param timeout: the timeout of the request
+        :return: the response
+        """
         if callback is not None:
             thread = threading.Thread(target=self._thread_body, args=(request, callback))
             thread.start()
@@ -89,11 +179,25 @@ def send_request(self, request, callback=None, timeout=None):  # pragma: no cove
             return response
 
     def send_empty(self, empty):  # pragma: no cover
+        """
+        Send empty message.
+
+        :param empty: the empty message
+        """
         self.protocol.send_message(empty)
 
     def mk_request(self, method, path):
+        """
+        Create a request.
+
+        :param method: the CoAP method
+        :param path: the path of the request
+        :return:  the request
+        """
         request = Request()
         request.destination = self.server
         request.code = method.number
         request.uri_path = path
-	return request
+        return request
+
+
diff --git a/coapthon/serializer.py b/coapthon/serializer.py
index 3fac23c..1f877b2 100644
--- a/coapthon/serializer.py
+++ b/coapthon/serializer.py
@@ -10,7 +10,9 @@
 
 
 class Serializer(object):
-
+    """
+    Serializer class to serialize and deserialize CoAP message to/from udp streams.
+    """
     @staticmethod
     def deserialize(datagram, source):
         """