[Pkg-privacy-commits] [pyptlib] 97/136: - rewrite some docs to use :returns: and :raises:

[Ximin Luo]

This is an automated email from the git hooks/post-receive script.

infinity0 pushed a commit to branch master
in repository pyptlib.

commit 24148bde54b580b5d5af8fc9a4567502473a5dbc
Author: Ximin Luo <infinity0 at gmx.com>
Date:   Mon Sep 2 16:33:40 2013 +0100

    - rewrite some docs to use :returns: and :raises:
---
 pyptlib/config.py        | 27 +++++++++++----------------
 pyptlib/core.py          |  3 +--
 pyptlib/server.py        |  5 ++---
 pyptlib/server_config.py |  5 ++---
 4 files changed, 16 insertions(+), 24 deletions(-)

diff --git a/pyptlib/config.py b/pyptlib/config.py
index 7106d97..4726763 100644
--- a/pyptlib/config.py
+++ b/pyptlib/config.py
@@ -11,17 +11,12 @@ SUPPORTED_TRANSPORT_VERSIONS = ['1']
 
 def env_has_k(k, v):
     """
-    A validator for Config.getEnv that returns the value of the envvar if it
-    was found, or throws ValueError if it was not.
-    """
-    if v is None: raise ValueError('Missing environment variable %s' % k)
-    return v
+    Default validator for :func:`get_env`.
 
-def env_id(_, v):
-    """
-    A validator for Config.getEnv that returns the value of the envvar if it
-    was found, or None if it was not.
+    :returns: str -- The value of the envvar `k` if it is set.
+    :raises: :class:`ValueError` if `k` was not found.
     """
+    if v is None: raise ValueError('Missing environment variable %s' % k)
     return v
 
 class Config(object):
@@ -74,14 +69,13 @@ def get_env(key, validate=env_has_k):
     Get the value of an environment variable.
 
     :param str key: Environment variable key.
-    :param f validate: Function that takes a var and a value and returns
-        a transformed value if it is valid, or throws an exception.
-        If the environment does not define var, value is None. By default,
-        we return the value if the environment has the variable, otherwise
-        we raise a ValueError.
+    :param f validate: Function that takes a `var` and a `value`, and returns
+        a (maybe transformed) value if it is valid, or throws an exception.
+        If the environment does not set `var`, `value` is passed in as `None`.
+        The default validator is :func:`env_has_k` which passes any value
+        which is set (i.e. not `None`).
 
     :returns: str -- The value of the envrionment variable.
-
     :raises: :class:`pyptlib.config.EnvError` if environment variable could not be
             found, or if it did not pass validation.
     """
@@ -106,7 +100,8 @@ def checkClientMode():
     Read the environment and return true if we are supposed to be a
     client. Return false if we are supposed to be a server.
 
-    Raise EnvError if the environment was not properly set up.
+    :raises: :class:`pyptlib.config.EnvError` if the environment was not
+             properly set up
     """
     if 'TOR_PT_CLIENT_TRANSPORTS' in os.environ: return True
     if 'TOR_PT_SERVER_TRANSPORTS' in os.environ: return False
diff --git a/pyptlib/core.py b/pyptlib/core.py
index a1b785a..4a290f3 100644
--- a/pyptlib/core.py
+++ b/pyptlib/core.py
@@ -89,8 +89,7 @@ class TransportPlugin(object):
 
     def getServedTransports(self):
         """
-        Return the names of the transports that this plugin is serving.
-
+        :returns: list of names of the transports that this plugin can serve.
         :raises: :class:`ValueError` if called before :func:`init`.
         """
         if self.served_transports is None:
diff --git a/pyptlib/server.py b/pyptlib/server.py
index d4f3d4f..e6b5199 100644
--- a/pyptlib/server.py
+++ b/pyptlib/server.py
@@ -35,9 +35,8 @@ class ServerTransportPlugin(TransportPlugin):
 
     def getServedBindAddresses(self):
         """
-        Return the names of the transports that this plugin is serving, each
-        mapped to '(ip,port)' of the location where the transport should bind.
-
+        :returns: dict of names of the transports that this plugin can serve,
+            each mapped to the (ip,port) where the transport should bind.
         :raises: :class:`ValueError` if called before :func:`init`.
         """
         return dict((k, v)
diff --git a/pyptlib/server_config.py b/pyptlib/server_config.py
index 953df60..495afa7 100644
--- a/pyptlib/server_config.py
+++ b/pyptlib/server_config.py
@@ -28,9 +28,8 @@ class ServerConfig(config.Config):
         :raises: :class:`pyptlib.config.EnvError` if environment was incomplete or corrupted.
         """
 
-        # TOR_PT_EXTENDED_SERVER_PORT is optional; tor uses the empty
-        # string as its value if it does not support the Extended
-        # ORPort.
+        # TOR_PT_EXTENDED_SERVER_PORT is set and empty if Tor does not support
+        # the Extended ORPort.
         def empty_or_valid_addr(k, v):
             v = env_has_k(k, v)
             if v == '': return None

-- 
Alioth's /usr/local/bin/git-commit-notice on /srv/git.debian.org/git/pkg-privacy/packages/pyptlib.git