Add documentation to python binding

Also some minor documentation for some .proto that goes into the API
guide

binding/core.py

@@ -14,6 +14,11 @@
 # 
 # You should have received a copy of the GNU General Public License
 # along with this program.  If not, see <http://www.gnu.org/licenses/>
+"""
+This is the core module for the Ostinato Python API.
+All drone configuration is done by creating an instance of the
+`DroneProxy` class and calling its various methods subsequently.
+"""
 
 import os
 from rpc import OstinatoRpcChannel, OstinatoRpcController, RpcError
@@ -22,8 +27,16 @@ import protocols.emulproto_pb2 as emul
 from __init__ import __version__
 
 class DroneProxy(object):
+    """
+    DroneProxy acts as a proxy to a Drone instance. A method invoked on this
+    class will be trigerred on the actual Drone instance being proxied
+    """
 
     def __init__(self, host_name, port_number=7878):
+        """
+        Create a DroneProxy object as a proxy to the Drone instance
+        running at the specified host and port
+        """
         self.host = host_name
         self.port = port_number
         self.channel = OstinatoRpcChannel()
@@ -34,14 +47,26 @@ class DroneProxy(object):
             fn = lambda request=self.void, method_name=method.name: \
                 self.callRpcMethod(method_name, request)
             self.__dict__[method.name] = fn
+            self.__dict__[method.name].__doc__ = 'This is a protobuf API'
 
     def hostName(self):
+        """
+        Returns the hostname of the Drone which is being proxied by
+        this DroneProxy object
+        """
         return self.host
 
     def portNumber(self):
+        """
+        Returns the TCP port number of the Drone which is being proxied by
+        this DroneProxy object
+        """
         return self.port
 
     def connect(self):
+        """
+        Connect to the Drone instance
+        """
         self.channel.connect(self.host, self.port)
         ver = ost_pb.VersionInfo()
         ver.client_name = 'python-ostinato'
@@ -52,6 +77,9 @@ class DroneProxy(object):
                     (ver.version, compat.notes))
 
     def disconnect(self):
+        """
+        Disconnect from the Drone instance
+        """
         self.channel.disconnect()
 
     def callRpcMethod(self, method_name, request):
@@ -61,9 +89,12 @@ class DroneProxy(object):
         return controller.response
 
     def saveCaptureBuffer(self, buffer, file_name):
-         f= open(file_name, 'wb')
+        """
-         f.write(buffer)
+        Save the capture buffer in a PCAP file
-         f.flush()
+        """
-         os.fsync(f.fileno())
+        f= open(file_name, 'wb')
-         f.close()
+        f.write(buffer)
+        f.flush()
+        os.fsync(f.fileno())
+        f.close()
 

common/dot2llc.proto

@@ -1,3 +1,4 @@
+/// (802.2 LLC)
 /*
 Copyright (C) 2010 Srivats P.
 
@@ -23,7 +24,6 @@ import "llc.proto";
 
 package OstProto;
 
-// 802.2 LLC
 message Dot2Llc {
     // Empty since this is a 'combo' protocol
 }

common/dot2snap.proto

@@ -1,3 +1,4 @@
+/// (802.2 SNAP)
 /*
 Copyright (C) 2010 Srivats P.
 

common/dot3.proto

@@ -1,3 +1,4 @@
+/// (802.3)
 /*
 Copyright (C) 2010 Srivats P.
 

common/gmp.proto

@@ -21,7 +21,7 @@ import "protocol.proto";
 
 package OstProto;
 
-// Group Management Protocol (i.e. IGMP and MLD)
+/// Group Management Protocol (i.e. IGMP and MLD)
 message Gmp {
     //
     // Common fields for both ASM and SSM messages

common/protocol.proto

@@ -52,8 +52,8 @@ message StreamCore {
     optional bool is_enabled = 2;
     optional uint32 ordinal = 3;
 
-    // Frame Length (includes CRC)
     optional FrameLengthMode len_mode = 14 [default = e_fl_fixed];
+    /// Frame Length (includes CRC)
     optional uint32 frame_len = 15 [default = 64];
     optional uint32 frame_len_min = 16 [default = 64];
     optional uint32 frame_len_max = 17 [default = 1518];