doc: Move Ryu App API doc into each source code

To improve maintainability, this patch moves the descriptions of
"Ryu application API" into each source code.

Signed-off-by: IWASE Yusuke <iwase.yusuke0@gmail.com>
Signed-off-by: FUJITA Tomonori <fujita.tomonori@lab.ntt.co.jp>

8 files changed, 292 insertions, 208 deletions

diff --git a/doc/source/ryu_app_api.rst b/doc/source/ryu_app_api.rst
index 323b4a9d..67566c7c 100644
--- a/doc/source/ryu_app_api.rst
+++ b/doc/source/ryu_app_api.rst
@@ -82,20 +82,10 @@ For example, EventOFPPacketIn for packet-in message.
 The OpenFlow controller part of Ryu automatically decodes OpenFlow messages
 received from switches and send these events to Ryu applications which
 expressed an interest using ryu.controller.handler.set_ev_cls.
-OpenFlow event classes have at least the following attributes.
+OpenFlow event classes are subclass of the following class.
 
-.. tabularcolumns:: |l|L|
+.. autoclass:: ryu.controller.ofp_event.EventOFPMsgBase
 
-============ =============================================================
-Attribute    Description
-============ =============================================================
-msg          An object which describes the corresponding OpenFlow message.
-msg.datapath A ryu.controller.controller.Datapath instance which describes
-             an OpenFlow switch from which we received this OpenFlow message.
-============ =============================================================
-
-The msg object has some more additional members whose values are extracted
-from the original OpenFlow message.
 See :ref:`ofproto_ref` for more info about OpenFlow messages.
 
 ryu.base.app_manager.RyuApp
@@ -103,97 +93,30 @@ ryu.base.app_manager.RyuApp
 
 See :ref:`api_ref`.
 
-ryu.controller.handler.set_ev_cls(ev_cls, dispatchers=None)
-===========================================================
-
-A decorator for Ryu application to declare an event handler.
-Decorated method will become an event handler.
-ev_cls is an event class whose instances this RyuApp wants to receive.
-dispatchers argument specifies one of the following negotiation phases
-(or a list of them) for which events should be generated for this handler.
-Note that, in case an event changes the phase, the phase before the change
-is used to check the interest.
-
-.. tabularcolumns:: |l|L|
-
-=========================================== ==================================
-Negotiation phase                           Description
-=========================================== ==================================
-ryu.controller.handler.HANDSHAKE_DISPATCHER Sending and waiting for hello
-                                            message
-ryu.controller.handler.CONFIG_DISPATCHER    Version negotiated and sent
-                                            features-request message
-ryu.controller.handler.MAIN_DISPATCHER      Switch-features message received
-                                            and sent set-config message
-ryu.controller.handler.DEAD_DISPATCHER      Disconnect from the peer.  Or
-                                            disconnecting due to some
-                                            unrecoverable errors.
-=========================================== ==================================
+ryu.controller.handler.set_ev_cls
+=================================
+
+.. autofunction:: ryu.controller.handler.set_ev_cls
 
 ryu.controller.controller.Datapath
 ==================================
 
-A class to describe an OpenFlow switch connected to this controller.
-An instance has the following attributes.
-
-.. tabularcolumns:: |l|L|
-
-====================================== =======================================
-Attribute                              Description
-====================================== =======================================
-id                                     64-bit OpenFlow Datapath ID.
-                                       Only available for
-                                       ryu.controller.handler.MAIN_DISPATCHER
-                                       phase.
-ofproto                                A module which exports OpenFlow
-                                       definitions, mainly constants appeared
-                                       in the specification, for the
-                                       negotiated OpenFlow version.  For
-                                       example, ryu.ofproto.ofproto_v1_0 for
-                                       OpenFlow 1.0.
-ofproto_parser                         A module which exports OpenFlow wire
-                                       message encoder and decoder for the
-                                       negotiated OpenFlow version.  For
-                                       example, ryu.ofproto.ofproto_v1_0_parser
-                                       for OpenFlow 1.0.
-ofproto_parser.OFPxxxx(datapath, ....) A callable to prepare an OpenFlow
-                                       message for the given switch.  It can
-                                       be sent with Datapath.send_msg later.
-                                       xxxx is a name of the message.  For
-                                       example OFPFlowMod for flow-mod
-                                       message.  Arguemnts depend on the
-                                       message.
-set_xid(self, msg)                     Generate an OpenFlow XID and put it
-                                       in msg.xid.
-send_msg(self, msg)                    Queue an OpenFlow message to send to
-                                       the corresponding switch.  If msg.xid
-                                       is None, set_xid is automatically
-                                       called on the message before queueing.
-send_packet_out                        deprecated
-send_flow_mod                          deprecated
-send_flow_del                          deprecated
-send_delete_all_flows                  deprecated
-send_barrier                           Queue an OpenFlow barrier message to
-                                       send to the switch.
-send_nxt_set_flow_format               deprecated
-is_reserved_port                       deprecated
-====================================== =======================================
+.. autoclass:: ryu.controller.controller.Datapath
 
 ryu.controller.event.EventBase
 ==============================
 
-The base of all event classes.
-A Ryu application can define its own event type by creating a subclass.
+.. autoclass:: ryu.controller.event.EventBase
 
 ryu.controller.event.EventRequestBase
 =====================================
 
-The base class for synchronous request for RyuApp.send_request.
+.. autoclass:: ryu.controller.event.EventRequestBase
 
 ryu.controller.event.EventReplyBase
 ===================================
 
-The base class for synchronous request reply for RyuApp.send_reply.
+.. autoclass:: ryu.controller.event.EventReplyBase
 
 ryu.controller.ofp_event.EventOFPStateChange
 ============================================
@@ -208,158 +131,49 @@ ryu.controller.ofp_event.EventOFPPortStateChange
 ryu.controller.dpset.EventDP
 ============================
 
-An event class to notify connect/disconnect of a switch.
-For OpenFlow switches, one can get the same notification by observing
-ryu.controller.ofp_event.EventOFPStateChange.
-An instance has at least the following attributes.
-
-========= ====================================================================
-Attribute Description
-========= ====================================================================
-dp        A ryu.controller.controller.Datapath instance of the switch
-enter     True when the switch connected to our controller.  False for
-          disconnect.
-========= ====================================================================
+.. autoclass:: ryu.controller.dpset.EventDP
 
 ryu.controller.dpset.EventPortAdd
 =================================
 
-An event class for switch port status notification.
-This event is generated when a new port is added to a switch.
-For OpenFlow switches, one can get the same notification by observing
-ryu.controller.ofp_event.EventOFPPortStatus.
-An instance has at least the following attributes.
-
-========= ====================================================================
-Attribute Description
-========= ====================================================================
-dp        A ryu.controller.controller.Datapath instance of the switch
-port      port number
-========= ====================================================================
+.. autoclass:: ryu.controller.dpset.EventPortAdd
 
 ryu.controller.dpset.EventPortDelete
 ====================================
 
-An event class for switch port status notification.
-This event is generated when a port is removed from a switch.
-For OpenFlow switches, one can get the same notification by observing
-ryu.controller.ofp_event.EventOFPPortStatus.
-An instance has at least the following attributes.
-
-========= ====================================================================
-Attribute Description
-========= ====================================================================
-dp        A ryu.controller.controller.Datapath instance of the switch
-port      port number
-========= ====================================================================
+.. autoclass:: ryu.controller.dpset.EventPortDelete
 
 ryu.controller.dpset.EventPortModify
 ====================================
 
-An event class for switch port status notification.
-This event is generated when some attribute of a port is changed.
-For OpenFlow switches, one can get the same notification by observing
-ryu.controller.ofp_event.EventOFPPortStatus.
-An instance has at least the following attributes.
-
-========= ====================================================================
-Attribute Description
-========= ====================================================================
-dp        A ryu.controller.controller.Datapath instance of the switch
-port      port number
-========= ====================================================================
+.. autoclass:: ryu.controller.dpset.EventPortModify
 
 ryu.controller.network.EventNetworkPort
 =======================================
 
-An event class for notification of port arrival and deperture.
-This event is generated when a port is introduced to or removed from a network
-by the REST API.
-An instance has at least the following attributes.
-
-========== ===================================================================
-Attribute  Description
-========== ===================================================================
-network_id Network ID
-dpid       OpenFlow Datapath ID of the switch to which the port belongs.
-port_no    OpenFlow port number of the port
-add_del    True for adding a port.  False for removing a port.
-========== ===================================================================
+.. autoclass:: ryu.controller.network.EventNetworkPort
 
 ryu.controller.network.EventNetworkDel
 ======================================
 
-An event class for network deletion.
-This event is generated when a network is deleted by the REST API.
-An instance has at least the following attributes.
-
-========== ===================================================================
-Attribute  Description
-========== ===================================================================
-network_id Network ID
-========== ===================================================================
+.. autoclass:: ryu.controller.network.EventNetworkDel
 
 ryu.controller.network.EventMacAddress
 ======================================
 
-An event class for end-point MAC address registration.
-This event is generated when a end-point MAC address is updated
-by the REST API.
-An instance has at least the following attributes.
-
-=========== ==================================================================
-Attribute   Description
-=========== ==================================================================
-network_id  Network ID
-dpid        OpenFlow Datapath ID of the switch to which the port belongs.
-port_no     OpenFlow port number of the port
-mac_address The old MAC address of the port if add_del is False.  Otherwise
-            the new MAC address.
-add_del     False if this event is a result of a port removal.  Otherwise
-            True.
-=========== ==================================================================
+.. autoclass:: ryu.controller.network.EventMacAddress
 
 ryu.controller.tunnels.EventTunnelKeyAdd
 ========================================
 
-An event class for tunnel key registration.
-This event is generated when a tunnel key is registered or updated
-by the REST API.
-An instance has at least the following attributes.
-
-=========== ==================================================================
-Attribute   Description
-=========== ==================================================================
-network_id  Network ID
-tunnel_key  Tunnel Key
-=========== ==================================================================
+.. autoclass:: ryu.controller.tunnels.EventTunnelKeyAdd
 
 ryu.controller.tunnels.EventTunnelKeyDel
 ========================================
 
-An event class for tunnel key registration.
-This event is generated when a tunnel key is removed by the REST API.
-An instance has at least the following attributes.
-
-=========== ==================================================================
-Attribute   Description
-=========== ==================================================================
-network_id  Network ID
-tunnel_key  Tunnel Key
-=========== ==================================================================
+.. autoclass:: ryu.controller.tunnels.EventTunnelKeyDel
 
 ryu.controller.tunnels.EventTunnelPort
 ======================================
 
-An event class for tunnel port registration.
-This event is generated when a tunnel port is added or removed by the REST API.
-An instance has at least the following attributes.
-
-=========== ==================================================================
-Attribute   Description
-=========== ==================================================================
-dpid        OpenFlow Datapath ID
-port_no     OpenFlow port number
-remote_dpid OpenFlow port number of the tunnel peer
-add_del     True for adding a tunnel.  False for removal.
-=========== ==================================================================
+.. autoclass:: ryu.controller.tunnels.EventTunnelPort
diff --git a/ryu/controller/controller.py b/ryu/controller/controller.py
index 177b2892..f1ba45cb 100644
--- a/ryu/controller/controller.py
+++ b/ryu/controller/controller.py
@@ -125,6 +125,56 @@ def _deactivate(method):
 
 
 class Datapath(ofproto_protocol.ProtocolDesc):
+    """
+    A class to describe an OpenFlow switch connected to this controller.
+
+    An instance has the following attributes.
+
+    .. tabularcolumns:: |l|L|
+
+    ==================================== ======================================
+    Attribute                            Description
+    ==================================== ======================================
+    id                                   64-bit OpenFlow Datapath ID.
+                                         Only available for
+                                         ryu.controller.handler.MAIN_DISPATCHER
+                                         phase.
+    ofproto                              A module which exports OpenFlow
+                                         definitions, mainly constants appeared
+                                         in the specification, for the
+                                         negotiated OpenFlow version.  For
+                                         example, ryu.ofproto.ofproto_v1_0 for
+                                         OpenFlow 1.0.
+    ofproto_parser                       A module which exports OpenFlow wire
+                                         message encoder and decoder for the
+                                         negotiated OpenFlow version.
+                                         For example,
+                                         ryu.ofproto.ofproto_v1_0_parser
+                                         for OpenFlow 1.0.
+    ofproto_parser.OFPxxxx(datapath,...) A callable to prepare an OpenFlow
+                                         message for the given switch.  It can
+                                         be sent with Datapath.send_msg later.
+                                         xxxx is a name of the message.  For
+                                         example OFPFlowMod for flow-mod
+                                         message.  Arguemnts depend on the
+                                         message.
+    set_xid(self, msg)                   Generate an OpenFlow XID and put it
+                                         in msg.xid.
+    send_msg(self, msg)                  Queue an OpenFlow message to send to
+                                         the corresponding switch.  If msg.xid
+                                         is None, set_xid is automatically
+                                         called on the message before queueing.
+    send_packet_out                      deprecated
+    send_flow_mod                        deprecated
+    send_flow_del                        deprecated
+    send_delete_all_flows                deprecated
+    send_barrier                         Queue an OpenFlow barrier message to
+                                         send to the switch.
+    send_nxt_set_flow_format             deprecated
+    is_reserved_port                     deprecated
+    ==================================== ======================================
+    """
+
     def __init__(self, socket, address):
         super(Datapath, self).__init__()
 
diff --git a/ryu/controller/dpset.py b/ryu/controller/dpset.py
index 1ec6a338..5af6835a 100644
--- a/ryu/controller/dpset.py
+++ b/ryu/controller/dpset.py
@@ -44,6 +44,23 @@ class EventDPBase(event.EventBase):
 
 
 class EventDP(EventDPBase):
+    """
+    An event class to notify connect/disconnect of a switch.
+
+    For OpenFlow switches, one can get the same notification by observing
+    ryu.controller.ofp_event.EventOFPStateChange.
+    An instance has at least the following attributes.
+
+    ========= =================================================================
+    Attribute Description
+    ========= =================================================================
+    dp        A ryu.controller.controller.Datapath instance of the switch
+    enter     True when the switch connected to our controller.  False for
+              disconnect.
+    ports     A list of port instances.
+    ========= =================================================================
+    """
+
     def __init__(self, dp, enter_leave):
         # enter_leave
         # True: dp entered
@@ -67,16 +84,64 @@ class EventPortBase(EventDPBase):
 
 
 class EventPortAdd(EventPortBase):
+    """
+    An event class for switch port status "ADD" notification.
+
+    This event is generated when a new port is added to a switch.
+    For OpenFlow switches, one can get the same notification by observing
+    ryu.controller.ofp_event.EventOFPPortStatus.
+    An instance has at least the following attributes.
+
+    ========= =================================================================
+    Attribute Description
+    ========= =================================================================
+    dp        A ryu.controller.controller.Datapath instance of the switch
+    port      port number
+    ========= =================================================================
+    """
+
     def __init__(self, dp, port):
         super(EventPortAdd, self).__init__(dp, port)
 
 
 class EventPortDelete(EventPortBase):
+    """
+    An event class for switch port status "DELETE" notification.
+
+    This event is generated when a port is removed from a switch.
+    For OpenFlow switches, one can get the same notification by observing
+    ryu.controller.ofp_event.EventOFPPortStatus.
+    An instance has at least the following attributes.
+
+    ========= =================================================================
+    Attribute Description
+    ========= =================================================================
+    dp        A ryu.controller.controller.Datapath instance of the switch
+    port      port number
+    ========= =================================================================
+    """
+
     def __init__(self, dp, port):
         super(EventPortDelete, self).__init__(dp, port)
 
 
 class EventPortModify(EventPortBase):
+    """
+    An event class for switch port status "MODIFY" notification.
+
+    This event is generated when some attribute of a port is changed.
+    For OpenFlow switches, one can get the same notification by observing
+    ryu.controller.ofp_event.EventOFPPortStatus.
+    An instance has at least the following attributes.
+
+    ========= ====================================================================
+    Attribute Description
+    ========= ====================================================================
+    dp        A ryu.controller.controller.Datapath instance of the switch
+    port      port number
+    ========= ====================================================================
+    """
+
     def __init__(self, dp, new_port):
         super(EventPortModify, self).__init__(dp, new_port)
 
diff --git a/ryu/controller/event.py b/ryu/controller/event.py
index a90bf660..e9d49211 100644
--- a/ryu/controller/event.py
+++ b/ryu/controller/event.py
@@ -16,11 +16,20 @@
 
 
 class EventBase(object):
-    # Nothing yet
-    pass
+    """
+    The base of all event classes.
+
+    A Ryu application can define its own event type by creating a subclass.
+    """
+
+    def __init__(self):
+        super(EventBase, self).__init__()
 
 
 class EventRequestBase(EventBase):
+    """
+    The base class for synchronous request for RyuApp.send_request.
+    """
     def __init__(self):
         super(EventRequestBase, self).__init__()
         self.dst = None  # app.name of provide the event.
@@ -30,6 +39,9 @@ class EventRequestBase(EventBase):
 
 
 class EventReplyBase(EventBase):
+    """
+    The base class for synchronous request reply for RyuApp.send_reply.
+    """
     def __init__(self, dst):
         super(EventReplyBase, self).__init__()
         self.dst = dst
diff --git a/ryu/controller/handler.py b/ryu/controller/handler.py
index a0782a12..f1fb7076 100644
--- a/ryu/controller/handler.py
+++ b/ryu/controller/handler.py
@@ -47,6 +47,33 @@ class _Caller(object):
 
 # should be named something like 'observe_event'
 def set_ev_cls(ev_cls, dispatchers=None):
+    """
+    A decorator for Ryu application to declare an event handler.
+
+    Decorated method will become an event handler.
+    ev_cls is an event class whose instances this RyuApp wants to receive.
+    dispatchers argument specifies one of the following negotiation phases
+    (or a list of them) for which events should be generated for this handler.
+    Note that, in case an event changes the phase, the phase before the change
+    is used to check the interest.
+
+    .. tabularcolumns:: |l|L|
+
+    =========================================== ===============================
+    Negotiation phase                           Description
+    =========================================== ===============================
+    ryu.controller.handler.HANDSHAKE_DISPATCHER Sending and waiting for hello
+                                                message
+    ryu.controller.handler.CONFIG_DISPATCHER    Version negotiated and sent
+                                                features-request message
+    ryu.controller.handler.MAIN_DISPATCHER      Switch-features message
+                                                received and sent set-config
+                                                message
+    ryu.controller.handler.DEAD_DISPATCHER      Disconnect from the peer.  Or
+                                                disconnecting due to some
+                                                unrecoverable errors.
+    =========================================== ===============================
+    """
     def _set_ev_cls_dec(handler):
         if 'callers' not in dir(handler):
             handler.callers = {}
diff --git a/ryu/controller/network.py b/ryu/controller/network.py
index 9b9baa4e..83c91b4d 100644
--- a/ryu/controller/network.py
+++ b/ryu/controller/network.py
@@ -31,12 +31,42 @@ class MacAddressAlreadyExist(ryu_exc.RyuException):
 
 
 class EventNetworkDel(event.EventBase):
+    """
+    An event class for network deletion.
+
+    This event is generated when a network is deleted by the REST API.
+    An instance has at least the following attributes.
+
+    ========== ===================================================================
+    Attribute  Description
+    ========== ===================================================================
+    network_id Network ID
+    ========== ===================================================================
+    """
+
     def __init__(self, network_id):
         super(EventNetworkDel, self).__init__()
         self.network_id = network_id
 
 
 class EventNetworkPort(event.EventBase):
+    """
+    An event class for notification of port arrival and deperture.
+
+    This event is generated when a port is introduced to or removed from a
+    network by the REST API.
+    An instance has at least the following attributes.
+
+    ========== ================================================================
+    Attribute  Description
+    ========== ================================================================
+    network_id Network ID
+    dpid       OpenFlow Datapath ID of the switch to which the port belongs.
+    port_no    OpenFlow port number of the port
+    add_del    True for adding a port.  False for removing a port.
+    ========== ================================================================
+    """
+
     def __init__(self, network_id, dpid, port_no, add_del):
         super(EventNetworkPort, self).__init__()
         self.network_id = network_id
@@ -46,6 +76,26 @@ class EventNetworkPort(event.EventBase):
 
 
 class EventMacAddress(event.EventBase):
+    """
+    An event class for end-point MAC address registration.
+
+    This event is generated when a end-point MAC address is updated
+    by the REST API.
+    An instance has at least the following attributes.
+
+    =========== ===============================================================
+    Attribute   Description
+    =========== ===============================================================
+    network_id  Network ID
+    dpid        OpenFlow Datapath ID of the switch to which the port belongs.
+    port_no     OpenFlow port number of the port
+    mac_address The old MAC address of the port if add_del is False.  Otherwise
+                the new MAC address.
+    add_del     False if this event is a result of a port removal.  Otherwise
+                True.
+    =========== ===============================================================
+    """
+
     def __init__(self, dpid, port_no, network_id, mac_address, add_del):
         super(EventMacAddress, self).__init__()
         assert network_id is not None
diff --git a/ryu/controller/ofp_event.py b/ryu/controller/ofp_event.py
index 8c990aae..6b1c8b3e 100644
--- a/ryu/controller/ofp_event.py
+++ b/ryu/controller/ofp_event.py
@@ -27,6 +27,25 @@ from . import event
 
 
 class EventOFPMsgBase(event.EventBase):
+    """
+    The base class of OpenFlow event class.
+
+    OpenFlow event classes have at least the following attributes.
+
+    .. tabularcolumns:: |l|L|
+
+    ============ ==============================================================
+    Attribute    Description
+    ============ ==============================================================
+    msg          An object which describes the corresponding OpenFlow message.
+    msg.datapath A ryu.controller.controller.Datapath instance
+                 which describes an OpenFlow switch from which we received
+                 this OpenFlow message.
+    ============ ==============================================================
+
+    The msg object has some more additional members whose values are extracted
+    from the original OpenFlow message.
+    """
     def __init__(self, msg):
         super(EventOFPMsgBase, self).__init__()
         self.msg = msg
@@ -83,6 +102,7 @@ for ofp_mods in ofproto.get_ofp_modules().values():
 class EventOFPStateChange(event.EventBase):
     """
     An event class for negotiation phase change notification.
+
     An instance of this class is sent to observer after changing
     the negotiation phase.
     An instance has at least the following attributes.
@@ -101,6 +121,7 @@ class EventOFPStateChange(event.EventBase):
 class EventOFPPortStateChange(event.EventBase):
     """
     An event class to notify the port state changes of Dtatapath instance.
+
     This event performs like EventOFPPortStatus, but Ryu will
     send this event after updating ``ports`` dict of Datapath instances.
     An instance has at least the following attributes.
diff --git a/ryu/controller/tunnels.py b/ryu/controller/tunnels.py
index 0a946738..61f0c160 100644
--- a/ryu/controller/tunnels.py
+++ b/ryu/controller/tunnels.py
@@ -43,16 +43,61 @@ class EventTunnelKeyBase(event.EventBase):
 
 
 class EventTunnelKeyAdd(EventTunnelKeyBase):
+    """
+    An event class for tunnel key registration.
+
+    This event is generated when a tunnel key is registered or updated
+    by the REST API.
+    An instance has at least the following attributes.
+
+    =========== ===============================================================
+    Attribute   Description
+    =========== ===============================================================
+    network_id  Network ID
+    tunnel_key  Tunnel Key
+    =========== ===============================================================
+    """
+
     def __init__(self, network_id, tunnel_key):
         super(EventTunnelKeyAdd, self).__init__(network_id, tunnel_key)
 
 
 class EventTunnelKeyDel(EventTunnelKeyBase):
+    """
+    An event class for tunnel key registration.
+
+    This event is generated when a tunnel key is removed by the REST API.
+    An instance has at least the following attributes.
+
+    =========== ===============================================================
+    Attribute   Description
+    =========== ===============================================================
+    network_id  Network ID
+    tunnel_key  Tunnel Key
+    =========== ===============================================================
+    """
+
     def __init__(self, network_id, tunnel_key):
         super(EventTunnelKeyDel, self).__init__(network_id, tunnel_key)
 
 
 class EventTunnelPort(event.EventBase):
+    """
+    An event class for tunnel port registration.
+
+    This event is generated when a tunnel port is added or removed
+    by the REST API.
+    An instance has at least the following attributes.
+
+    =========== ===============================================================
+    Attribute   Description
+    =========== ===============================================================
+    dpid        OpenFlow Datapath ID
+    port_no     OpenFlow port number
+    remote_dpid OpenFlow port number of the tunnel peer
+    add_del     True for adding a tunnel.  False for removal.
+    =========== ===============================================================
+    """
     def __init__(self, dpid, port_no, remote_dpid, add_del):
         super(EventTunnelPort, self).__init__()
         self.dpid = dpid