add some docstring on StringifyMixin and relevant code

Signed-off-by: YAMAMOTO Takashi <yamamoto@valinux.co.jp>
Signed-off-by: FUJITA Tomonori <fujita.tomonori@lab.ntt.co.jp>

ryu/lib/stringify.py

@@ -77,6 +77,33 @@ _types = {
 
 
 class StringifyMixin(object):
+
+    _TYPE = {}
+    """_TYPE class attribute is used to annotate types of attributes.
+
+    This type information is used to find an appropriate conversion for
+    a JSON style dictionary.
+
+    Currently the following types are implemented.
+
+    ===== ==========
+    Type  Descrption
+    ===== ==========
+    ascii US-ASCII
+    utf-8 UTF-8
+    ===== ==========
+
+    Example::
+        _TYPE = {
+            'ascii': [
+                'hw_addr',
+            ],
+            'utf-8': [
+                'name',
+            ]
+        }
+    """
+
     _class_prefixes = []
 
     def stringify_attrs(self):
@@ -149,7 +176,31 @@ class StringifyMixin(object):
         return _encode
 
     def to_jsondict(self, encode_string=base64.b64encode):
-        """returns an object to feed json.dumps()
+        """
+        This method returns a JSON style dict to describe this object.
+
+        The returned dict is compatible with json.dumps() and json.loads().
+
+        Suppose ClassName object inherits StringifyMixin.
+        For an object like the following::
+
+            ClassName(Param1=100, Param2=200)
+
+        this method would produce::
+
+            { "ClassName": {"Param1": 100, "Param2": 200} }
+
+        This method takes the following arguments.
+
+        =============  =====================================================
+        Argument       Description
+        =============  =====================================================
+        encode_string  (Optional) specify how to encode attributes which has
+                       python 'str' type.
+                       The default is base64.
+                       This argument is used only for attributes which don't
+                       have explicit type annotations in _TYPE class attribute.
+        =============  =====================================================
         """
         dict_ = {}
         encode = lambda k, x: self._encode_value(k, x, encode_string)
@@ -217,7 +268,24 @@ class StringifyMixin(object):
     @classmethod
     def from_jsondict(cls, dict_, decode_string=base64.b64decode,
                       **additional_args):
-        """create an instance from a result of json.loads()
+        """Create an instance from a JSON style dict.
+
+        Instantiate this class with parameters specified by the dict.
+
+        This method takes the following arguments.
+
+        =============== =====================================================
+        Argument        Descrpition
+        =============== =====================================================
+        dict\_          A dictionary which describes the parameters.
+                        For example, {"Param1": 100, "Param2": 200}
+        decode_string   (Optional) specify how to decode strings.
+                        The default is base64.
+                        This argument is used only for attributes which don't
+                        have explicit type annotations in _TYPE class
+                        attribute.
+        additional_args (Optional) Additional kwargs for constructor.
+        =============== =====================================================
         """
         decode = lambda k, x: cls._decode_value(k, x, decode_string)
         kwargs = cls._restore_args(_mapdict_kv(decode, dict_))

ryu/ofproto/ofproto_parser.py

@@ -68,6 +68,30 @@ def create_list_of_base_attributes(f):
 
 
 def ofp_msg_from_jsondict(dp, jsondict):
+    """
+    This function instanticates an appropriate OpenFlow message class
+    from the given JSON style dictionary.
+    The objects created by following two code fragments are equivalent.
+
+    Code A::
+
+        jsonstr = '{ "OFPSetConfig": { "flags": 0, "miss_send_len": 128 } }'
+        jsondict = json.loads(jsonstr)
+        o = ofp_msg_from_jsondict(dp, jsondict)
+
+    Code B::
+
+        o = dp.ofproto_parser.OFPSetConfig(flags=0, miss_send_len=128)
+
+    This function takes the following arguments.
+
+    ======== =======================================
+    Argument Description
+    ======== =======================================
+    dp       An instance of ryu.controller.Datapath.
+    jsondict A JSON style dict.
+    ======== =======================================
+    """
     parser = dp.ofproto_parser
     assert len(jsondict) == 1
     for k, v in jsondict.iteritems():
@@ -87,6 +111,23 @@ class StringifyMixin(stringify.StringifyMixin):
 
 
 class MsgBase(StringifyMixin):
+    """
+    This is a base class for OpenFlow message classes.
+
+    An instance of this class has at least the following attributes.
+
+    ========= ==============================
+    Attribute Description
+    ========= ==============================
+    datapath  A ryu.controller.controller.Datapath instance for this message
+    version   OpenFlow protocol version
+    msg_type  Type of OpenFlow message
+    msg_len   Length of the message
+    xid       Transaction id
+    buf       Raw data
+    ========= ==============================
+    """
+
     @create_list_of_base_attributes
     def __init__(self, datapath):
         super(MsgBase, self).__init__()