ryu.lib.packet: docstring

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

5 files changed, 111 insertions, 2 deletions

diff --git a/ryu/lib/packet/ethernet.py b/ryu/lib/packet/ethernet.py
index f266ade3..7bc18ef4 100644
--- a/ryu/lib/packet/ethernet.py
+++ b/ryu/lib/packet/ethernet.py
@@ -21,6 +21,20 @@ from ryu.ofproto import ether
 
 
 class ethernet(packet_base.PacketBase):
+    """Ethernet header encoder/decoder class.
+
+    An instance has the following attributes at least.
+    __init__ takes the correspondig args in this order.
+
+    =========== ====================
+    Attribute   Description
+    =========== ====================
+    dst         destination address
+    src         source address
+    ethertype   ether type
+    =========== ====================
+    """
+
     _PACK_STR = '!6s6sH'
     _MIN_LEN = struct.calcsize(_PACK_STR)
 
diff --git a/ryu/lib/packet/icmp.py b/ryu/lib/packet/icmp.py
index 9fcd8b3f..0e199a6a 100644
--- a/ryu/lib/packet/icmp.py
+++ b/ryu/lib/packet/icmp.py
@@ -27,6 +27,27 @@ ICMP_ECHO_REQUEST = 8
 
 
 class icmp(packet_base.PacketBase):
+    """ICMP (RFC 792) header encoder/decoder class.
+
+    An instance has the following attributes at least.
+    Most of them are same to the on-wire counterparts but in host byte order.
+    __init__ takes the correspondig args in this order.
+
+    ============== ====================
+    Attribute      Description
+    ============== ====================
+    type           Type
+    code           Code
+    csum           CheckSum \
+                   (0 means automatically-calculate when encoding)
+    data           Payload. \
+                   Either a bytearray or ryu.lib.packet.icmp.echo object. \
+                   NOTE: This includes "unused" 16 bits and the following \
+                   "Internet Header + 64 bits of Original Data Datagram" of \
+                   the ICMP header.
+    ============== ====================
+    """
+
     _PACK_STR = '!BBH'
     _MIN_LEN = struct.calcsize(_PACK_STR)
     _ICMP_TYPES = {}
@@ -80,6 +101,24 @@ class icmp(packet_base.PacketBase):
 
 @icmp.register_icmp_type(ICMP_ECHO_REPLY, ICMP_ECHO_REQUEST)
 class echo(object):
+    """ICMP sub encoder/decoder class.
+
+    This is used with ryu.lib.packet.icmp.icmp for
+    ICMP Echo and Echo Reply messages.
+
+    An instance has the following attributes at least.
+    Most of them are same to the on-wire counterparts but in host byte order.
+    __init__ takes the correspondig args in this order.
+
+    ============== ====================
+    Attribute      Description
+    ============== ====================
+    id             Identifier
+    seq            Sequence Number
+    data           Internet Header + 64 bits of Original Data Datagram
+    ============== ====================
+    """
+
     _PACK_STR = '!HH'
     _MIN_LEN = struct.calcsize(_PACK_STR)
 
diff --git a/ryu/lib/packet/ipv4.py b/ryu/lib/packet/ipv4.py
index 4f48e931..ef2d58cc 100644
--- a/ryu/lib/packet/ipv4.py
+++ b/ryu/lib/packet/ipv4.py
@@ -29,6 +29,34 @@ IPV4_PSEUDO_HEADER_PACK_STR = '!II2xHH'
 
 
 class ipv4(packet_base.PacketBase):
+    """IPv4 header encoder/decoder class.
+
+    An instance has the following attributes at least.
+    Most of them are same to the on-wire counterparts but in host byte order.
+    __init__ takes the correspondig args in this order.
+
+    ============== ====================
+    Attribute      Description
+    ============== ====================
+    version        Version
+    header_length  IHL
+    tos            Type of Service
+    total_length   Total Length \
+                   (0 means automatically-calculate when encoding)
+    identification Identification
+    flags          Flags
+    offset         Fragment Offset
+    ttl            Time to Live
+    proto          Protocol
+    csum           Header Checksum \
+                   (Ignored and automatically-calculated when encoding)
+    src            Source Address
+    dst            Destination Address
+    option         A bytearray which contains the entire Options, or None for \
+                   no Options
+    ============== ====================
+    """
+
     _PACK_STR = '!BBHHHBBHII'
     _MIN_LEN = struct.calcsize(_PACK_STR)
 
diff --git a/ryu/lib/packet/packet_base.py b/ryu/lib/packet/packet_base.py
index 46feb11e..8b932154 100644
--- a/ryu/lib/packet/packet_base.py
+++ b/ryu/lib/packet/packet_base.py
@@ -46,8 +46,20 @@ class PacketBase(object):
         This method is used only when decoding a packet.
 
         Decode a protocol header at offset 0 in bytearray *buf*.
-        Returns the rest of the packet and the decoded header, which is
-        instance of packet_base.PacketBase subclass.
+        Returns the following two objects.
+
+        * An object to describe the decoded header.
+        It should have the following attributes at least.
+
+        =========== ============
+        Attribute   Description
+        =========== ============
+        length      The number of the corresponding on-wire octets
+        =========== ============
+
+        * A packet_base.PacketBase subclass appropriate for the rest of
+          the packet.  None when the rest of the packet should be considered
+          as raw payload.
         """
         pass
 
diff --git a/ryu/lib/packet/vlan.py b/ryu/lib/packet/vlan.py
index 164241e1..9a42403f 100644
--- a/ryu/lib/packet/vlan.py
+++ b/ryu/lib/packet/vlan.py
@@ -24,6 +24,22 @@ from ryu.ofproto.ofproto_parser import msg_pack_into
 
 
 class vlan(packet_base.PacketBase):
+    """VLAN (IEEE 802.1Q) header encoder/decoder class.
+
+    An instance has the following attributes at least.
+    Most of them are same to the on-wire counterparts but in host byte order.
+    __init__ takes the correspondig args in this order.
+
+    ============== ====================
+    Attribute      Description
+    ============== ====================
+    pcp            Priority Code Point
+    cfi            Canonical Format Indicator
+    vid            VLAN Identifier
+    ethertype      EtherType
+    ============== ====================
+    """
+
     _PACK_STR = "!HH"
     _MIN_LEN = struct.calcsize(_PACK_STR)