From bb0e82090b020a2d2a25283a4a2346cc3bf90fbc Mon Sep 17 00:00:00 2001
From: Antoine Millet <antoine.millet@smartjog.com>
Date: Mon, 3 Oct 2011 14:08:01 +0200
Subject: [PATCH] Added protocols documentation.

---
 doc/api/core.rst                 | 11 +++++++++++
 sjrpc/core/__init__.py           |  2 +-
 sjrpc/core/protocols/__init__.py | 22 ++++++++++++++++++++++
 sjrpc/core/protocols/rpc.py      | 13 +++++++------
 sjrpc/core/protocols/tunnel.py   |  2 ++
 5 files changed, 43 insertions(+), 7 deletions(-)

diff --git a/doc/api/core.rst b/doc/api/core.rst
index 595bc0e..bab89ed 100644
--- a/doc/api/core.rst
+++ b/doc/api/core.rst
@@ -2,6 +2,17 @@
 Core library
 ------------
 
+Sub-packages
+~~~~~~~~~~~~
+
+.. toctree::
+   :maxdepth: 2
+
+   core.protocols
+
+Module members
+~~~~~~~~~~~~~~
+
 .. automodule:: sjrpc.core
    :members:
    :inherited-members:
diff --git a/sjrpc/core/__init__.py b/sjrpc/core/__init__.py
index fadf0d4..2ac7cbb 100644
--- a/sjrpc/core/__init__.py
+++ b/sjrpc/core/__init__.py
@@ -18,7 +18,7 @@ It also contains a sub-package containing protocols: :mod:`core.protocols`.
 .. toctree::
    :hidden:
 
-   api/core.protocols
+   core.protocols
 
 '''
 
diff --git a/sjrpc/core/protocols/__init__.py b/sjrpc/core/protocols/__init__.py
index 04252eb..72bc168 100644
--- a/sjrpc/core/protocols/__init__.py
+++ b/sjrpc/core/protocols/__init__.py
@@ -1,8 +1,28 @@
 
+'''
+Protocols can be binded on a specific label of a :class:`RpcConnection` (see
+`Multiplexing & protocols`_ for more informations).
+
+Following protocols are provided with standard distribution of sjRpc, but you
+can create yours if you needs:
+
+- :class:`RpcProtocol`: the standard rpc protocol
+- :class:`TunnelProtocol`: a protocol which allow to tunnel a socket traffic
+  through the sjRpc connection
+- :class:`VpnProtocol` (experimental): like :class:`TunnelProtocol` but work
+  with a network interface instead of a socket.
+
+'''
+
+
 import logging
 
 class Protocol(object):
 
+    '''
+    Base class for all protocols.
+    '''
+
     def __init__(self, connection, label, logger=None):
         self._connection = connection
         self._label = label
@@ -62,3 +82,5 @@ class Protocol(object):
 
 from sjrpc.core.protocols.rpc import RpcProtocol
 from sjrpc.core.protocols.tunnel import TunnelProtocol
+
+__all__ = ['Protocol', 'RpcProtocol', 'TunnelProtocol']
diff --git a/sjrpc/core/protocols/rpc.py b/sjrpc/core/protocols/rpc.py
index 8909e1a..0751571 100644
--- a/sjrpc/core/protocols/rpc.py
+++ b/sjrpc/core/protocols/rpc.py
@@ -9,23 +9,24 @@ from sjrpc.core.callers import RpcCaller, ThreadedRpcCaller
 from sjrpc.core.exceptions import RpcError
 from sjrpc.core.protocols import Protocol
 
+__all__ = ['RpcProtocol']
 
 class RpcProtocol(Protocol):
 
-    REQUEST_MESSAGE = {'id': None, 'method': None, 'args': [], 'kwargs': {}}
-    RESPONSE_MESSAGE = {'id': None, 'return': None, 'error': None}
-    SPECIAL_MESSAGE = {'special': None}
-
     '''
+    The standard protocol used to do RPC request/responses.
+
     :param connection: the connection serving this :class:`RpcProtocol`
     :param label: the label of this :class:`RpcProtocol` instance
     :param handler: command handler to bind by default
     :param on_disconnect: callback called when client disconnect
-    :param request_decorator: decorator applied on each handler function
     :param timeout: global command timeout
-    :param logger: logging module :class:`Logger` instance
     '''
 
+    REQUEST_MESSAGE = {'id': None, 'method': None, 'args': [], 'kwargs': {}}
+    RESPONSE_MESSAGE = {'id': None, 'return': None, 'error': None}
+    SPECIAL_MESSAGE = {'special': None}
+
     def __init__(self, connection, label, handler=None, on_disconnect=None,
                  request_decorator=None, timeout=30, *args, **kwargs):
         super(RpcProtocol, self).__init__(connection, label, *args, **kwargs)
diff --git a/sjrpc/core/protocols/tunnel.py b/sjrpc/core/protocols/tunnel.py
index a759a4a..5ec98b1 100644
--- a/sjrpc/core/protocols/tunnel.py
+++ b/sjrpc/core/protocols/tunnel.py
@@ -6,6 +6,8 @@ from sjrpc.core.protocols import Protocol
 
 import pyev
 
+__all__ = ['TunnelProtocol']
+
 class TunnelProtocol(Protocol):
 
     '''
-- 
GitLab