Merge pull request #28 from rohieb/patch/documentation

improve documentation

Author: jquast

README.rst

@@ -18,12 +18,14 @@ Usage
 Create a function to get and put character data (to a serial line for
 example)::
 
+    >>> import serial
     >>> from xmodem import XMODEM
+    >>> ser = serial.Serial('/dev/ttyUSB0', timeout=0) # or whatever port you need
     >>> def getc(size, timeout=1):
-    ...     return data or None
+    ...     return ser.read(size) or None
     ...
     >>> def putc(data, timeout=1):
-    ...     return size or None
+    ...     return ser.write(data)  # note that this ignores the timeout
     ...
     >>> modem = XMODEM(getc, putc)
 

xmodem/__init__.py

@@ -133,21 +133,32 @@
 
 class XMODEM(object):
     '''
-    XMODEM Protocol handler, expects an object to read from and an object to
-    write to.
+    XMODEM Protocol handler, expects two callables which encapsulate the read
+        and write operations on the underlying stream.
 
+    Example functions for reading and writing to a serial line:
+
+    >>> import serial
+    >>> from xmodem import XMODEM
+    >>> ser = serial.Serial('/dev/ttyUSB0', timeout=0) # or whatever you need
     >>> def getc(size, timeout=1):
-    ...     return data or None
+    ...     return ser.read(size) or None
     ...
     >>> def putc(data, timeout=1):
-    ...     return size or None
+    ...     return ser.write(data) or None
     ...
     >>> modem = XMODEM(getc, putc)
 
 
-    :param getc: Function to retrieve bytes from a stream
+    :param getc: Function to retrieve bytes from a stream. The function takes
+        the number of bytes to read from the stream and a timeout in seconds as
+        parameters. It must return the bytes which were read, or ``None`` if a
+        timeout occured.
     :type getc: callable
-    :param putc: Function to transmit bytes to a stream
+    :param putc: Function to transmit bytes to a stream. The function takes the
+        bytes to be written and a timeout in seconds as parameters. It must
+        return the number of bytes written to the stream, or ``None`` in case of
+        a timeout.
     :type putc: callable
     :param mode: XMODEM protocol mode
     :type mode: string
@@ -202,6 +213,11 @@ def __init__(self, getc, putc, mode='xmodem', pad=b'\x1a'):
     def abort(self, count=2, timeout=60):
         '''
         Send an abort sequence using CAN bytes.
+
+        :param count: how many abort characters to send
+        :type count: int
+        :param timeout: timeout in seconds
+        :type timeout: int
         '''
         for _ in range(count):
             self.putc(CAN, timeout)
@@ -377,6 +393,22 @@ def recv(self, stream, crc_mode=1, retry=16, timeout=60, delay=1, quiet=0):
 
         Returns the number of bytes received on success or ``None`` in case of
         failure.
+
+        :param stream: The stream object to write data to.
+        :type stream: stream (file, etc.)
+        :param crc_mode: XMODEM CRC mode
+        :type crc_mode: int
+        :param retry: The maximum number of times to try to resend a failed
+                      packet before failing.
+        :type retry: int
+        :param timeout: The number of seconds to wait for a response before
+                        timing out.
+        :type timeout: int
+        :param delay: The number of seconds to wait between resend attempts
+        :type delay: int
+        :param quiet: If ``True``, write transfer information to stderr.
+        :type quiet: bool
+
         '''
 
         # initiate protocol