packet lib: docstring

also, prefix a private method with _.

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

2 files changed, 68 insertions, 2 deletions

diff --git a/ryu/lib/packet/packet.py b/ryu/lib/packet/packet.py
index da9c412d..95332667 100644
--- a/ryu/lib/packet/packet.py
+++ b/ryu/lib/packet/packet.py
@@ -18,7 +18,16 @@ from . import ethernet
 
 
 class Packet(object):
+    """A packet decoder/encoder class.
+
+    An instance is used to either decode or encode a single packet.
+    """
+
     def __init__(self, data=None):
+        """*data* is a bytearray to describe a raw datagram to decode.
+        *data* should be omitted when encoding a packet.
+        """
+
         super(Packet, self).__init__()
         self.data = data
         self.protocols = []
@@ -26,9 +35,9 @@ class Packet(object):
         self.parsed_bytes = 0
         if self.data:
             # Do we need to handle non ethernet?
-            self.parser(ethernet.ethernet)
+            self._parser(ethernet.ethernet)
 
-    def parser(self, cls):
+    def _parser(self, cls):
         while cls:
             proto, cls = cls.parser(self.data[self.parsed_bytes:])
             if proto:
@@ -39,6 +48,11 @@ class Packet(object):
             self.protocols.append(self.data[self.parsed_bytes:])
 
     def serialize(self):
+        """Encode a packet and store the resulted bytearray in self.data.
+
+        This method is legal only when encoding a packet.
+        """
+
         self.data = bytearray()
         r = self.protocols[::-1]
         for i, p in enumerate(r):
@@ -53,9 +67,21 @@ class Packet(object):
             self.data = data + self.data
 
     def add_protocol(self, proto):
+        """Register a protocol *proto* for this packet.
+
+        This method is legal only when encoding a packet.
+
+        When encoding a packet, register a protocol (ethernet, ipv4, ...)
+        header to add to this packet.
+        Protocol headers should be registered in on-wire order before calling
+        self.serialize.
+        """
+
         self.protocols.append(proto)
 
     def next(self):
+        """See __iter__."""
+
         try:
             p = self.protocols[self.protocol_idx]
         except:
@@ -66,4 +92,13 @@ class Packet(object):
         return p
 
     def __iter__(self):
+        """Iterate protocol (ethernet, ipv4, ...) headers and the payload.
+
+        This method is legal only when decoding a packet.
+
+        Protocol headers are instances of subclass of packet_base.PacketBase.
+        The payload is a bytearray.
+        They are iterated in on-wire order.
+        """
+
         return self
diff --git a/ryu/lib/packet/packet_base.py b/ryu/lib/packet/packet_base.py
index aa38eb03..46feb11e 100644
--- a/ryu/lib/packet/packet_base.py
+++ b/ryu/lib/packet/packet_base.py
@@ -15,14 +15,23 @@
 
 
 class PacketBase(object):
+    """A base class for a protocol (ethernet, ipv4, ...) header."""
     _TYPES = {}
 
     @classmethod
     def get_packet_type(cls, type_):
+        """Per-protocol dict-like get method.
+
+        Provided for convenience of protocol implementers.
+        Internal use only."""
         return cls._TYPES.get(type_)
 
     @classmethod
     def register_packet_type(cls, cls_, type_):
+        """Per-protocol dict-like set method.
+
+        Provided for convenience of protocol implementers.
+        Internal use only."""
         cls._TYPES[type_] = cls_
 
     def __init__(self):
@@ -32,7 +41,29 @@ class PacketBase(object):
 
     @classmethod
     def parser(cls, buf):
+        """Decode a protocol header.
+
+        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.
+        """
         pass
 
     def serialize(self, payload, prev):
+        """Encode a protocol header.
+
+        This method is used only when encoding a packet.
+
+        Encode a protocol header.
+        Returns a bytearray which contains the header.
+
+        *payload* is the rest of the packet which will immediately follow
+        this header.
+
+        *prev* is a packet_base.PacketBase subclass for the outer protocol
+        header.  *prev* is None if the current header is the outer-most.
+        For example, *prev* is ipv4 or ipv6 for tcp.serialize.
+        """
         pass