Merge pull request #11 from timthelion/docs

Document transport classes.

docs/Makefile

@@ -10,3 +10,4 @@ html:
 
 clean:
 	rm -rf _build/
+

docs/transport.rst

@@ -1,6 +1,16 @@
 Transport class
 --------------
 
-.. automodule:: trezorlib.transport
+.. autoclass:: trezorlib.transport.Transport
+  :members:
+  :undoc-members:
+
+Exceptions:
+
+.. autoclass:: trezorlib.transport.ConnectionError
+  :members:
+  :undoc-members:
+
+.. autoclass:: trezorlib.transport.NotImplementedException
   :members:
   :undoc-members:

docs/transport_hid.rst

@@ -10,6 +10,6 @@ To get a list of TREZORs that are currently plugged into our computer, we use th
 
 We can now interact with our TREZORs by creating a :doc:`TrezorClient <client>` object.
 
-.. automodule:: trezorlib.transport_hid
+.. autoclass:: trezorlib.transport_hid.HidTransport
   :members:
   :undoc-members:

trezorlib/transport.py

@@ -32,28 +32,47 @@ class Transport(object):
         pass
     
     def ready_to_read(self):
+        """
+        Returns True if there is data to be read from the transport.  Otherwise, False.
+        """
         raise NotImplementedException("Not implemented")
     
     def session_begin(self):
+        """
+        Apply a lock to the device in order to preform synchronous multistep "conversations" with the device.  For example, before entering the transaction signing workflow, one begins a session.  After the transaction is complete, the session may be ended.
+        """
         if self.session_depth == 0:
             self._session_begin()
         self.session_depth += 1
     
     def session_end(self):
+        """
+        End a session.  Se session_begin for an in depth description of TREZOR sessions.
+        """
         self.session_depth -= 1
         self.session_depth = max(0, self.session_depth)
         if self.session_depth == 0:
             self._session_end()
         
     def close(self):
+        """
+        Close the connection to the physical device or file descriptor represented by the Transport.
+        """
         self._close()
         
     def write(self, msg):
+        """
+        Write mesage to tansport.  msg should be a member of a valid `protobuf class <https://developers.google.com/protocol-buffers/docs/pythontutorial>`_ with a SerializeToString() method.
+        """
         ser = msg.SerializeToString()
         header = struct.pack(">HL", mapping.get_type(msg), len(ser))
         self._write("##%s%s" % (header, ser), msg)
 
     def read(self):
+        """
+        If there is data available to be read from the transport, reads the data and tries to parse it as a protobuf message.  If the parsing succeeds, return a protobuf object.
+        Otherwise, returns None.
+        """
         if not self.ready_to_read():
             return None
 
@@ -64,6 +83,9 @@ class Transport(object):
         return self._parse_message(data)
         
     def read_blocking(self):
+        """
+        Same as read, except blocks untill data is available to be read.
+        """
         while True:
             data = self._read()
             if data != None:

trezorlib/transport_hid.py

@@ -54,6 +54,9 @@ class HidTransport(Transport):
 
     @classmethod
     def enumerate(cls):
+        """
+        Return a list of available TREZOR devices.
+        """
         devices = {}
         for d in hid.enumerate(0, 0):
             vendor_id = d['vendor_id']
@@ -74,7 +77,9 @@ class HidTransport(Transport):
         return devices.values()
 
     def is_connected(self):
-        # Check if the device is still connected
+        """
+        Check if the device is still connected.
+        """
         for d in hid.enumerate(0, 0):
             if d['path'] == self.device:
                 return True