From 3af35f3c1fdfedfbc4b79034e89147b493d9d5d3 Mon Sep 17 00:00:00 2001
From: Scott Petersen <scott@nutech.com>
Date: Tue, 21 May 2013 11:54:33 -0700
Subject: [PATCH] Docs

---
 pyad2usb/ad2usb.py  |  9 ++++++---
 pyad2usb/devices.py | 13 +++++++++++--
 pyad2usb/util.py    | 17 ++++++++++++++++-
 3 files changed, 33 insertions(+), 6 deletions(-)

diff --git a/pyad2usb/ad2usb.py b/pyad2usb/ad2usb.py
index 0c018fc..5346b7e 100644
--- a/pyad2usb/ad2usb.py
+++ b/pyad2usb/ad2usb.py
@@ -13,6 +13,7 @@ class Overseer(object):
     Factory for creation of AD2USB devices as well as provide4s attach/detach events."
     """
 
+    # Factory events
     on_attached = event.Event('Called when an AD2USB device has been detected.')
     on_detached = event.Event('Called when an AD2USB device has been removed.')
 
@@ -152,13 +153,15 @@ class AD2USB(object):
     High-level wrapper around AD2USB/AD2SERIAL devices.
     """
 
+    # High-level Events
     on_open = event.Event('Called when the device has been opened')
     on_close = event.Event('Called when the device has been closed')
+    on_message = event.Event('Called when a message has been received from the device.')
+
+    # Low-level Events
     on_read = event.Event('Called when a line has been read from the device')
     on_write = event.Event('Called when data has been written to the device')
 
-    on_message = event.Event('Called when a message has been received from the device.')
-
     def __init__(self, device):
         """
         Constructor
@@ -198,7 +201,7 @@ class AD2USB(object):
         """
         Parses messages from the panel.
         """
-        if data[0] == '!':
+        if data[0] == '!':      # TEMP: Remove this.
             return None
 
         msg = Message()
diff --git a/pyad2usb/devices.py b/pyad2usb/devices.py
index 3c2f06c..c1020b9 100644
--- a/pyad2usb/devices.py
+++ b/pyad2usb/devices.py
@@ -19,6 +19,7 @@ class Device(object):
     Generic parent device to all AD2USB products.
     """
 
+    # Generic device events
     on_open = event.Event('Called when the device has been opened')
     on_close = event.Event('Called when the device has been closed')
     on_read = event.Event('Called when a line has been read from the device')
@@ -59,7 +60,7 @@ class Device(object):
                 try:
                     self._device.read_line(timeout=10)
                 except util.CommError, err:
-                    traceback.print_exc(err)
+                    traceback.print_exc(err)    # TEMP
                 except util.TimeoutError, err:
                     pass
 
@@ -70,6 +71,7 @@ class USBDevice(Device):
     AD2USB device exposed with PyFTDI's interface.
     """
 
+    # Constants
     FTDI_VENDOR_ID = 0x0403
     FTDI_PRODUCT_ID = 0x6001
     BAUDRATE = 115200
@@ -113,6 +115,7 @@ class USBDevice(Device):
         """
         self._running = True
 
+        # Set up defaults
         if baudrate is None:
             baudrate = USBDevice.BAUDRATE
 
@@ -125,6 +128,7 @@ class USBDevice(Device):
         if index is None:
             index = 0
 
+        # Open the device and start up the thread.
         try:
             self._device.open(self._vendor_id,
                              self._product_id,
@@ -226,6 +230,8 @@ class SerialDevice(Device):
     """
     AD2USB or AD2SERIAL device exposed with the pyserial interface.
     """
+
+    # Constants
     BAUDRATE = 19200
 
     @staticmethod
@@ -264,6 +270,8 @@ class SerialDevice(Device):
         """
         Opens the device.
         """
+
+        # Set up the defaults
         if baudrate is None:
             baudrate = SerialDevice.BAUDRATE
 
@@ -276,6 +284,7 @@ class SerialDevice(Device):
         self._device.baudrate = baudrate
         self._device.port = self._interface
 
+        # Open the device and start up the reader thread.
         try:
             self._device.open()
 
@@ -338,7 +347,7 @@ class SerialDevi