Improving documentation

Author: macartur

pyof/v0x01/controller2switch/common.py

@@ -230,7 +230,7 @@ def unpack(self, buff, offset=0):
         Keep buff and offset just for compability with other unpack methods.
 
         Args:
-            buff: Buffer where data is located.
+            buff (bytes): Buffer where data is located.
             offset (int): Where data stream begins.
         """
         self.length = UBInt16()
@@ -397,7 +397,7 @@ def __init__(self, port_no=None, queue_id=None):
         Args:
             port_no (:class:`int`, :class:`~pyof.v0x01.common.phy_port.Port`):
                  All ports if :attr:`.Port.OFPP_ALL`.
-            queue_id (int): All queues if OFPQ_ALL.
+            queue_id (int): All queues if OFPQ_ALL (``0xfffffff``).
         """
         super().__init__()
         self.port_no = port_no

pyof/v0x01/controller2switch/stats_reply.py

@@ -38,7 +38,7 @@ def pack(self, value=None):
         StatsReply object, then will return this struct as a binary data.
 
         Returns:
-            stats_reply_packed (bytes): Binary data with StatsReply packed.
+            bytes: Binary data with StatsReply packed.
         """
         buff = self.body
         if not value:

pyof/v0x04/common/action.py

@@ -85,7 +85,7 @@ class ActionExperimenterHeader(GenericStruct):
     experimenter = UBInt32()
 
     def __init__(self, length=None, experimenter=None):
-        """Action structure for OFPAT_EXPERIMENTER.
+        """The constructor just assigns parameters to object attributes.
 
         Args:
             experimenter (int): The experimenter field is the Experimenter ID,
@@ -107,7 +107,7 @@ class ActionGroup(GenericStruct):
     group_id = UBInt32()
 
     def __init__(self, group_id=None):
-        """Action structure for OFPAT_GROUP.
+        """The constructor just assigns parameters to object attributes.
 
         Args:
             group_id (int): The group_id indicates the group used to process
@@ -135,7 +135,7 @@ class ActionHeader(GenericStruct):
     pad = Pad(4)
 
     def __init__(self, action_type=None, length=None):
-        """The following constructor parameters are optional.
+        """The constructor just assigns parameters to object attributes.
 
         Args:
             action_type (~pyof.v0x04.common.action.ActionType):
@@ -160,7 +160,7 @@ class ActionMPLSTTL(GenericStruct):
     pad = Pad(3)
 
     def __init__(self, mpls_ttl=None):
-        """Action structure for OFPAT_SET_MPLS_TTL.
+        """The constructor just assigns parameters to object attributes.
 
         Args:
             mpls_ttl (int): The mpls_ttl field is the MPLS TTL to set.
@@ -182,7 +182,7 @@ class ActionNWTTL(GenericStruct):
     pad = Pad(3)
 
     def __init__(self, nw_ttl=None):
-        """Action structure for OFPAT_SET_NW_TTL.
+        """The constructor just assigns parameters to object attributes.
 
         Args:
             nw_ttl (int): the TTL address to set in the IP header.
@@ -214,7 +214,7 @@ class ActionOutput(GenericStruct):
 
     def __init__(self, action_type=None, length=None, port=None,
                  max_length=None):
-        """The following constructor parameters are optional.
+        """The constructor just assigns parameters to object attributes.
 
         Args:
             port (:class:`Port` or :class:`int`): Output port.
@@ -240,7 +240,7 @@ class ActionPopMPLS(GenericStruct):
     pad = Pad(2)
 
     def __init__(self, ethertype=None):
-        """Action structure for OFPAT_POP_MPLS.
+        """The constructor just assigns parameters to object attributes.
 
         Args:
             ethertype (int): indicates the Ethertype of the payload.
@@ -262,7 +262,7 @@ class ActionPush(GenericStruct):
     pad = Pad(2)
 
     def __init__(self, ethertype=None):
-        """Action structure for OFPAT_PUSH_VLAN/MPLS/PBB.
+        """The constructor just assigns parameters to object attributes.
 
         Args:
             ethertype (int): indicates the Ethertype of the new tag.
@@ -286,7 +286,7 @@ class ActionSetField(GenericStruct):
 
     def __init__(self, length=None, field1=None, field2=None, field3=None,
                  field4=None):
-        """Action structure for OFPAT_SET_FIELD.
+        """The constructor just assigns parameters to object attributes.
 
         Args:
             length (int): length padded to 64 bits, followed by exactly
@@ -317,7 +317,7 @@ class ActionSetQueue(GenericStruct):
     queue_id = UBInt32()
 
     def __init__(self, queue_id=None):
-        """Action structure for OFPAT_SET_QUEUE.
+        """The constructor just assigns parameters to object attributes.
 
         Args:
             queue_id (int): The queue_id send packets to given queue on port.

pyof/v0x04/common/flow_instructions.py

@@ -112,11 +112,11 @@ class InstructionApplyAction(Instruction):
     actions = ListOfActions()
 
     def __init__(self, actions=None):
-        """Instruction structure for OFPIT_APPLY_ACTIONS.
+        """The constructor just assigns parameters to object attributes.
 
         Args:
-            - actions (:class:`~.actions.ListOfActions`): Actions associated
-                with OFPIT_APPLY_ACTIONS.
+            actions (:class:`~.actions.ListOfActions`):
+                Actions associated with OFPIT_APPLY_ACTIONS.
         """
         super().__init__(InstructionType.OFPIT_APPLY_ACTIONS)
         self.actions = actions if actions else []
@@ -135,11 +135,11 @@ class InstructionClearAction(Instruction):
     actions = ListOfActions()
 
     def __init__(self, actions=None):
-        """Instruction structure for OFPIT_CLEAR_ACTIONS.
+        """The constructor just assigns parameters to object attributes.
 
         Args:
-            - actions (:class:`~.actions.ListOfActions`): Actions associated
-                with OFPIT_CLEAR_ACTIONS.
+            actions (:class:`~.actions.ListOfActions`):
+                Actions associated with OFPIT_CLEAR_ACTIONS.
         """
         super().__init__(InstructionType.OFPIT_CLEAR_ACTIONS)
         self.actions = actions if actions else []
@@ -155,11 +155,11 @@ class InstructionGotoTable(Instruction):
     pad = Pad(3)
 
     def __init__(self, table_id=Meter.OFPM_ALL):
-        """Instruction structure for OFPIT_GOTO_TABLE.
+        """The constructor just assigns parameters to object attributes.
 
         Args:
-            - length (int): Length of this struct in bytes.
-            - table_id (int): set next table in the lookup pipeline.
+            length (int): Length of this struct in bytes.
+            table_id (int): set next table in the lookup pipeline.
         """
         super().__init__(InstructionType.OFPIT_GOTO_TABLE)
         self.table_id = table_id
@@ -176,10 +176,10 @@ class InstructionMeter(Instruction):
     meter_id = UBInt32()
 
     def __init__(self, meter_id=Meter.OFPM_ALL):
-        """Instruction structure for OFPIT_METER.
+        """The constructor just assigns parameters to object attributes.
 
         Args:
-            - meter_id (int): Meter instance.
+            meter_id (int): Meter instance.
         """
         super().__init__(InstructionType.OFPIT_METER)
         self.meter_id = meter_id
@@ -198,11 +198,11 @@ class InstructionWriteAction(Instruction):
     actions = ListOfActions()
 
     def __init__(self, actions=None):
-        """Instruction structure for OFPIT_WRITE_ACTIONS.
+        """The constructor just assigns parameters to object attributes.
 
         Args:
-            - actions (:class:`~.actions.ListOfActions`): Actions associated
-                with OFPIT_WRITE_ACTIONS.
+            actions (:class:`~.actions.ListOfActions`):
+                Actions associated with OFPIT_WRITE_ACTIONS.
         """
         super().__init__(InstructionType.OFPIT_WRITE_ACTIONS)
         self.actions = actions if actions else []
@@ -220,11 +220,11 @@ class InstructionWriteMetadata(Instruction):
     metadata_mask = UBInt64()
 
     def __init__(self, metadata=0, metadata_mask=0):
-        """Instruction structure for OFPIT_WRITE_METADATA.
+        """The constructor just assigns parameters to object attributes.
 
         Args:
-            - metadata (int): Metadata value to write.
-            - metadata_mask (int): Metadata write bitmask.
+            metadata (int): Metadata value to write.
+            metadata_mask (int): Metadata write bitmask.
         """
         super().__init__(InstructionType.OFPIT_WRITE_METADATA)
         self.metadata = metadata
@@ -242,6 +242,7 @@ def __init__(self, items=None):
         """The constructor just assigns parameters to object attributes.
 
         Args:
-            items (Instruction): Instance or a list of instances.
+            items (:class:`~pyof.v0x04.common.flow_instructions.Instruction`):
+                Instance or a list of instances.
         """
         super().__init__(pyof_class=Instruction, items=items)

pyof/v0x04/common/flow_match.py

@@ -246,11 +246,11 @@ class OxmExperimenterHeader(OxmHeader):
     experimenter = UBInt32()
 
     def __init__(self, experimenter=None):
-        """Header for OXM experimenter match fields.
+        """The constructor just assigns parameters to object attributes.
 
         Args:
-            - experimenter (int): Experimenter ID which takes the same form as
-                in struct ofp_experimenter_header
+            experimenter (int): Experimenter ID which takes the same form as
+              in struct ofp_experimenter_header
         """
         super().__init__()
         self.experimenter = experimenter

pyof/v0x04/common/table_feature.py

@@ -142,12 +142,13 @@ class InstructionsProperty(Property):
 
     def __init__(self, property_type=TableFeaturePropType.OFPTFPT_INSTRUCTIONS,
                  instruction_ids=None):
-        """Constructor of InstructionProperty receives the parameters bellow.
+        """Constructor of NextTablesProperty receives the parameters bellow.
 
         Args:
             type(~pyof.v0x04.controller2switch.common.TableFeaturePropType):
                 Property Type value of this instance.
-            instruction_ids(ListOfInstruction): List of Instruction instances.
+            next_table_ids(:class:`ListOfInstruction`):
+                List of InstructionGotoTable instances.
         """
         super().__init__(property_type=property_type)
         self.instruction_ids = instruction_ids if instruction_ids else []
@@ -171,8 +172,9 @@ def __init__(self, property_type=TableFeaturePropType.OFPTFPT_NEXT_TABLES,
         Args:
             type(~pyof.v0x04.controller2switch.common.TableFeaturePropType):
                 Property Type value of this instance.
-            next_table_ids(ListOfInstruction): List of InstructionGotoTable
-                                               instances.
+            next_table_ids \
+            (:class:`~pyof.v0x04.common.flow_instructions.ListOfInstruction`):
+                List of InstructionGotoTable instances.
         """
         super().__init__(property_type)
         self.next_table_ids = next_table_ids

pyof/v0x04/controller2switch/common.py

@@ -234,8 +234,8 @@ def __init__(self, packet_count=None, byte_count=None):
         """The constructor just assigns parameters to object attributes.
 
         Args:
-            packet_count: Number of packets processed by bucket.
-            byte_count: Number of bytes processed by bucket.
+            packet_count (int): Number of packets processed by bucket.
+            byte_count (int): Number of bytes processed by bucket.
         """
         super().__init__()
         self.packet_count = packet_count
@@ -445,14 +445,13 @@ class InstructionsProperty(Property):
 
     def __init__(self, property_type=TableFeaturePropType.OFPTFPT_INSTRUCTIONS,
                  instruction_ids=None):
-        """Constructor of InstructionProperty receives the parameters bellow.
+        r"""Constructor of InstructionProperty receives the parameters bellow.
 
         Args:
             type(~pyof.v0x04.controller2switch.common.TableFeaturePropType):
                 Property Type value of this instance.
-            instruction_ids
-            (~pyof.v0x04.common.flow_instructions.ListOfInstruction):
-                    List of Instruction instances.
+            instruction_ids (:class:`ListOfInstruction`):
+                List of Instruction instances.
         """
         super().__init__(property_type=property_type)
         self.instruction_ids = instruction_ids if instruction_ids else []
@@ -476,9 +475,8 @@ def __init__(self, property_type=TableFeaturePropType.OFPTFPT_NEXT_TABLES,
         Args:
             type(~pyof.v0x04.controller2switch.common.TableFeaturePropType):
                 Property Type value of this instance.
-            next_table_ids
-                (~pyof.v0x04.common.flow_instructions.ListOfInstruction):
-                    List of InstructionGotoTable instances.
+            next_table_ids (:class:`ListOfInstruction`):
+                List of InstructionGotoTable instances.
         """
         super().__init__(property_type)
         self.next_table_ids = next_table_ids
@@ -591,16 +589,16 @@ def __init__(self, table_id=Table.OFPTT_ALL, name="",
 
         Args:
             table_id(int): Indetifier of table.The default value
-                OFPTT_ALL(0xff) will apply the configuration to all tables in
-                the switch.
+                OFPTT_ALL(``0xff``) will apply the configuration to all tables
+                in the switch.
             name(Char): Characters representing the table name.
             metadata_match(int): Indicate the bits of the metadata field that
-               the table can match on.The default value 0xFFFFFFFFFFFFFFFF
+               the table can match on.The default value ``0xFFFFFFFFFFFFFFFF``
                indicates that the table can match the full metadata field.
             metadata_write(int): Indicates the bits of the metadata field that
                the table can write using the OFPIT_WRITE_METADATA instruction.
-               The default value 0xFFFFFFFFFFFFFFFF indicates that the table
-               can write the full metadata field.
+               The default value ``0xFFFFFFFFFFFFFFFF`` indicates that the
+               table can write the full metadata field.
             config(int): Field reseved for future use.
             max_entries(int): Describe the maximum number of flow entries that
                 can be inserted into that table.

pyof/v0x04/controller2switch/get_async_reply.py

@@ -27,22 +27,22 @@ def __init__(self, xid=None, packet_in_mask1=None, packet_in_mask2=None,
 
         Args:
             xid (int): xid to be used on the message header.
-            packet_in_mask1
+            packet_in_mask1 \
                 (~pyof.v0x04.asynchronous.packet_in.PacketInReason):
                     A instance of PacketInReason
-            packet_in_mask2
+            packet_in_mask2 \
                 (~pyof.v0x04.asynchronous.packet_in.PacketInReason):
                     A instance of PacketInReason
-            port_status_mask1
+            port_status_mask1 \
                 (~pyof.v0x04.asynchronous.port_status.PortReason):
                     A instance of PortReason
-            port_status_mask2
+            port_status_mask2 \
                 (~pyof.v0x04.asynchronous.port_status.PortReason):
                     A instance of PortReason
-            flow_removed_mask1
+            flow_removed_mask1 \
                 (~pyof.v0x04.asynchronous.flow_removed.FlowRemoved):
                     A instance of FlowRemoved.
-            flow_removed_mask2
+            flow_removed_mask2 \
                 (~pyof.v0x04.asynchronous.flow_removed.FlowRemoved):
                     A instance of FlowRemoved.
         """

pyof/v0x04/controller2switch/group_mod.py

@@ -11,7 +11,7 @@
 
 
 class Group(IntEnum):
-    """Group numbering. Groups can use any number up to OFPG_MAX."""
+    """Group numbering. Groups can use any number up to attr:`OFPG_MAX`."""
 
     #: Last usable group number.
     OFPG_MAX = 0xffffff00