Add docstrings and Add pydoc generated doc files

This Commit,
- adds docstrings to all the python modules, class and functions
- adds pydoc generated doc files to doc/pydoc/ dir

Author: codenio

docs/README.md renamed to DESIGN_DOCS.md

@@ -47,7 +47,7 @@ the example file at `bitscope/examples/scope/scope_plot.py`
 
 ## Library Overview
 
-The Library provides full programmed access to the BitScope Capture Engine. It is implemented using a small set of portable functions. Programming BitScope to capture waveforms and logic is simply a matter of calling the correct sequence of these functions from your program. There are no complicated data structures, parameter lists or callbacks.
+The Library provides full programmed access to the BitScope Capture Engine. It is implemented using a small set of portable functions. Programming BitScope to capture waveforms and logic is simply a matter of calling the correct sequence of these functions from your program.
 
 See BitScope Programming and Library Reference for details.
 

README.md

@@ -1,18 +1,26 @@
+"""Document level docstring."""
 #!/usr/bin/env python
 
 from bitlib import *
 
 class Channel:
-
-    id = ""
-    device = ""
-    src = ""
-    analog_count = ""
-    logic_count = ""
-    analog_range_count = ""
+    """channel class to select, configure and acquire data from channels."""
+    
+    id = None
+    device = None
+    src = None
+    analog_count = None
+    logic_count = None
+    analog_range_count = None
 
     def __init__(self, device, channel):
+        """Initialise channel objects.
         
+        :type device: int
+        :param device: device id
+        :type channel: int
+        :param channel: channel id
+        """
         self.device = device
         self.id = channel
         # device is seleted from previous Device class
@@ -23,6 +31,10 @@ def __init__(self, device, channel):
         self.analog_range_count = BL_Count(BL_COUNT_RANGE)
 
     def select(self):
+        """Request the selection of a current channel.
+        
+        :return: current selection of channel is returned.
+        """
         # check if the corresponding device is already selected
         if self.device != BL_Select(BL_SELECT_DEVICE,BL_ASK):
             # select the corresponding device first
@@ -35,13 +47,24 @@ def select(self):
         # print "Selected Device : {} , Channel : {}".format(self.device,self.id)
 
     def count(self,type):
+        """Return the number of channels or ranges per the type specifier(BL_COUNT_ANALOG=>devices, BL_COUNT_LOGIC=>analog, 2=>logic, BL_COUNT_RANGE=>ranges) using the prevailing device and/or channel for those types that require it.
+        
+        :type type: BL_COUNT_ANALOG,BL_COUNT_LOGIC,BL_COUNT_RANGE
+        :param type: specifies the type for which count must be found
+        :return: count of the selected type
+        """
         if type in [BL_COUNT_ANALOG,BL_COUNT_LOGIC,BL_COUNT_RANGE]:
             return BL_Count(type)
         else:
             print "Invalid Count Type"
             return 0
 
     def source(self,type=BL_SOURCE_BNC):
+        """Request the selection of a range or sources.
+        
+        :type type: BL_SOURCE_POD, BL_SOURCE_BNC, BL_SOURCE_X10, BL_SOURCE_X20, BL_SOURCE_X50, BL_SOURCE_ALT, BL_SOURCE_GND
+        :param type: selects the type of source for a channel
+        """
         self.select()
 
         if type in [BL_SOURCE_POD, BL_SOURCE_BNC, BL_SOURCE_X10, BL_SOURCE_X20, BL_SOURCE_X50, BL_SOURCE_ALT, BL_SOURCE_GND]:
@@ -50,26 +73,64 @@ def source(self,type=BL_SOURCE_BNC):
             self.source = type
 
     # set offset
-    def offset(self, volt):
+    def offset(self, offset):
+        """Request offset and return the offset that is actually assigned to to
+        the selected device, channel and source. If a value beyond the
+        available offset range of the device is specified the closest available
+        offset for that channel is used.
+        
+        :type offset: int
+        :param offset: the value to be offset
+        :return: offset that is actually assigned to the selected device, channel and source.
+        """
         self.select()
         # set offset
         BL_Offset(offset)
 
     # set range
-    def analog_range(self,analog_range):
+    def analog_range(self, range):
+        """Selects range and returns the maximum peak-to-peak voltage the can
+        be captured on the selected device, channel and source. If the range is
+        omitted, the prevailing range scale is returned. The range must
+        otherwise be 0 to N where N is the number of available ranges).
+        
+        :type range: int
+        :param range: maximum peak-to-peak voltage the can be captured on the selected device, channel and source.
+        :return: returns the maximum peak-to-peak voltage
+        """
         self.select()
         # set range
-        if analog_range >= 0 and analog_range <= (self.analog_range_count)-1:
-            BL_Range(analog_range)
+        if range >= 0 and range <= (self.analog_range_count)-1:
+            BL_Range(range)
 
     # set coupling
     def coupling(self,coupling):
+        """Selects coupling and returns the same value as A if the requested
+        value is selectable on the current channel and source. If coupling is
+        omitted (or BL_ASK is specified), the prevailing coupling is returned.
+        
+        :type coupling: BL_COUPLING_AC,BL_COUPLING_DC,BL_COUPLING_RF,BL_ASK
+        :param coupling: Selects coupling
+        :return: the prevailing coupling is returned
+        """
         self.select()
-        if coupling in [BL_COUPLING_AC,BL_COUPLING_DC,BL_COUPLING_RF]:
-            BL_Coupling(coupling)
+        if coupling in [BL_COUPLING_AC,BL_COUPLING_DC,BL_COUPLING_RF,BL_ASK]:
+            return BL_Coupling(coupling)
 
-    def configure(self, source=BL_SOURCE_BNC, offset=BL_ZERO,analog_range=0,coupling=BL_COUPLING_DC):
+    def configure(self, source=BL_SOURCE_BNC, offset=BL_ZERO, range=0, coupling=BL_COUPLING_DC):
+        """Configure the channel parameters like source, offset, analog_range,
+        coupling for the selected device and channel.
         
+        :type source: BL_SOURCE_POD, BL_SOURCE_BNC, BL_SOURCE_X10, BL_SOURCE_X20, BL_SOURCE_X50, BL_SOURCE_ALT, BL_SOURCE_GND
+        :param source: selects the type of source for a channel
+        :type offset: int
+        :param offset: the value to be offset
+        :type range: int
+        :param range: maximum peak-to-peak voltage the can be captured on the selected device, channel and source.
+        :type coupling: BL_COUPLING_AC,BL_COUPLING_DC,BL_COUPLING_RF,BL_ASK
+        :param coupling: Selects coupling
+        """
+
         self.select()
         if source in [BL_SOURCE_POD, BL_SOURCE_BNC, BL_SOURCE_X10, BL_SOURCE_X20, BL_SOURCE_X50, BL_SOURCE_ALT, BL_SOURCE_GND]:
             # select the corresponding source for the channel
@@ -79,34 +140,56 @@ def configure(self, source=BL_SOURCE_BNC, offset=BL_ZERO,analog_range=0,coupling
         # set offset
         BL_Offset(offset)
         # set range
-        if analog_range >= 0 and analog_range <= (self.analog_range_count)-1:
-            BL_Range(analog_range)
+        if range >= 0 and range <= (self.analog_range_count)-1:
+            BL_Range(range)
         # set coupling
         if coupling in [BL_COUPLING_AC,BL_COUPLING_DC,BL_COUPLING_RF]:
             BL_Coupling(coupling)
-
+    
     # enable channel
     def enable(self):
+        """Assign enable status E (boolean) on the selected channel.
+        
+        :return: true if successful or false otherwise.
+        """
         self.select()
         BL_Enable(1)
         print "Enabled Device : {} , Channel : {}".format(self.device,self.id)
-
+    
     # disable channel
     def disable(self):
+        """Assign diasble status E (boolean) on the selected channel.
+        
+        :return: true if successful or false otherwise.
+        """
         self.select()   
         BL_Enable(0)
         print "Disabled Device : {} , Channel : {}".format(self.device,self.id)
-
+    
     # set index before reading the data 
     # assign the buffer offset (for dumps)
     def index(self, offset=0):
+        """Request the capture address offset and return the address actually
+        used A which may be different if the request is unavailable or invalid.
+        If offset is omitted the address is (re)set to zero.
+        
+        :type offset: int
+        :param offset: Request the capture address offset
+        :return: the address actually used
+        """
         self.select()
-        BL_Index(offset)
-
+        return BL_Index(offset)
+    
     # acquire data from channel
     def acquire(self):
+        """Reads N samples from the selected device (BL_Select) and channel and
+        writes them to list D.
+        Returns N samples (possibly updated value). Samples are
+        (nominally) floating point voltages. Logic channels are
+        (nominally) low (0V) or high (5V). Alternatively D and/or N may
+        be omitted. In either case the returned value is a new list of
+        size N (or BL_Size() if N is omitted).
+        """
         self.select()
         print "Acquiring Data from Device : {} , Channel : {}".format(self.device,self.id)
-        return BL_Acquire()
-
-
+        return BL_Acquire()

bitscope/channel.py

@@ -4,35 +4,52 @@
 from bitscope.channel import Channel
 
 class Device:
-
-    name = ""
-    id = ""
-    mode = ""
-    version = ""
-    channels = []
+    """Device class to select and configure devices that are open."""
+    name = None
+    id = None
+    mode = None
+    version = None
+    channels = None
 
     def __init__(self,device):
+        """Initialise the Device Object.
+
+        :type device: int
+        :param device: device id to be initialised
+        """
         self.id = device
         BL_Select(BL_SELECT_DEVICE,device)
         self.name = BL_Name()
         self.version = BL_Version(BL_VERSION_DEVICE)
         # Find number of channels in each device and create Channel object for each and append in devices.channels
+        self.channels = []
         for channel in range(0,BL_Count(BL_COUNT_ANALOG)):
             self.channels.append(Channel(self.id, channel))
         for channel in range(0,BL_Count(BL_COUNT_LOGIC)):
             self.channels.append(Channel(self.id, channel))
 
     def select(self):
+        """Request the selection of a current device.
+
+        :return: current selection is returned.
+        """
         # check if the required device is selected
         if self.id != BL_Select(BL_SELECT_DEVICE,BL_ASK):
             # select the corresponding device first
-            BL_Select(BL_SELECT_DEVICE,self.id)
+            return BL_Select(BL_SELECT_DEVICE,self.id)
         # print "Selected Device : {}".format(self.id)
 
     def mode(self, mode):
+        """Assign mode to the selected device and return the mode if
+        successful.
+
+        :type mode: int
+        :param mode: Assign mode (BL_MODE_FAST=>SCOPE, BL_MODE_DUAL=>CHOP, BL_MODE_MIXED=>MIXED, BL_MODE_LOGIC=>LOGIC, BL_MODE_STREAM=>STREAM) to the selected device
+        :return: return the mode if successful
+        """
         self.select()
         if mode in [BL_MODE_FAST, BL_MODE_DUAL, BL_MODE_MIXED, BL_MODE_LOGIC, BL_MODE_STREAM]:
             # select the mode
             BL_Mode(mode)
             self.mode = mode
-            print "Device : {} set to Mode : {}".format(self.id,self.mode)    
+            print "Device : {} set to Mode : {}".format(self.id,self.mode)

bitscope/device.py

@@ -3,44 +3,110 @@
 from bitlib import *
 
 class Trace:
-    """
-    """
+    """Trace Class to handle trace related functionalities."""
 
     def trace(self, time_out, sync):
+        """Commence capture subject to timeout T (seconds) and block until the
+        trace completes unless A is true in which case return now and capture
+        asynchronously. In the latter use BL_State() to determine the state of
+        capture. Returns OK true if the trace commenced successfully, false
+        otherwise. If T is zero or omitted, perform a forced trigger trace
+        immediately. If T is negative, do the trace with infinite timeout but
+        do it execute aysnchronously.
+
+        :type time_out: double
+        :param time_out: specify the time out for trace
+        :type sync: BL_SYNC, BL_ASYNC
+        :param sync: specify trace modes
+        :return: boolean
+        """
         return BL_Trace(time_out,sync)
 
     def rate(self,rate=None):
+        """sets rate for trace.
+
+        :type rate: int
+        :param rate: rate to perform the trace
+        :return: current rate
+        """
         if rate is None:
             return BL_Rate()
         else:
             return BL_Rate(rate); # optional, default BL_MAX_RATE
 
     def size(self, size=None):
+        """sets size for trace.
+
+        :type size: int
+        :param size: size to perform the trace
+        :return: current size
+        """
         if size is None:
             return BL_Size()
         else:
             return BL_Size(size); # optional default BL_MAX_SIZE
 
     def pre_capture(self, pre_capture=BL_ZERO):
+        """sets pre_capture time for trace.
+
+        :type pre_capture: int
+        :param pre_capture: time to start capture before performing the trace
+        :return: current pre_capture time
+        """
         return BL_Intro(pre_capture); #How many seconds to capture before the trigger event- 0 by default
 
     def post_capture(self, post_capture=BL_ZERO):
+        """sets post_capture time for trace.
+
+        :type post_capture: int
+        :param post_capture: time to stop capture after performing the trace
+        :return: current post_capture time
+        """
         return BL_Delay(post_capture); #How many seconds to capture after the trigger event- 0 by default
 
     def time(self, t=None):
+        """sets time for trace.
+
+        :type t: double
+        :param t: time to trace
+        :return: current time
+        """
         if t is None:
             return BL_Time()
         else:
             return BL_Time(t)
 
     def trigger(self, volt, kind):
+        """sets tigger for trace.
+
+        :type volt: double
+        :param volt: voltage level for trigger
+        :type kind: BL_TRIG_RISE, BL_TRIG_FALL, BL_TRIG_HIGH, BL_TRIG_LOW, BL_TRIG_NONE
+        :param kind: specify trigger type
+        :return: cuurent trigger setting
+        """
         if kind in [BL_TRIG_RISE, BL_TRIG_FALL, BL_TRIG_HIGH, BL_TRIG_LOW, BL_TRIG_NONE]:
             return BL_Trigger(volt,kind)
 
     def state(self):
+        """returns current state of the machine.
+
+        :return: current state of machine
+        """
         return BL_State()
 
     def configure(self,rate=BL_MAX_RATE, size=BL_MAX_SIZE, pre_capture=BL_ZERO, post_capture=BL_ZERO):
+        """configure the trace settings.
+
+        :type rate: int
+        :param rate: rate to perform the trace
+        :type size: int
+        :param size: size to perform the trace
+        :type pre_capture: int
+        :param pre_capture: time to start capture before performing the trace
+        :type post_capture: int
+        :param post_capture: time to stop capture after performing the trace
+        """
         #Setup channel-nonspecific parameters for capture.
         BL_Rate(rate); # optional, default BL_MAX_RATE
         BL_Size(size); # optional default BL_MAX_SIZE