docstring improvements

src/allmydata/client.py

@@ -163,6 +163,13 @@ class Terminator(service.Service):
 
 
 def read_config(basedir, portnumfile, generated_files=[]):
+    """
+    Read and validate configuration for a client-style Node. See
+    :method:`allmydata.node.read_config` for parameter meanings (the
+    only difference here is we pass different validation data)
+
+    :returns: :class:`allmydata.node._Config` instance
+    """
     return node.read_config(
         basedir, portnumfile,
         generated_files=generated_files,
@@ -175,9 +182,14 @@ def create_client(basedir=u".", _client_factory=None):
     """
     Creates a new client instance (a subclass of Node).
 
-    :param basedir: the node directory
+    :param unicode basedir: the node directory (which may not exist yet)
 
-    :param _client_factory: for testing; the class to instantiate
+    :param _client_factory: (for testing) a callable that returns an
+        instance of :class:`allmydata.node.Node` (or a subclass). By default
+        this is :class:`allmydata.client._Client`
+
+    :returns: :class:`allmydata.client._Client` instance (or whatever
+        `_client_factory` returns)
     """
     node.create_node_dir(basedir, CLIENT_README)
     config = read_config(basedir, u"client.port")

src/allmydata/node.py

@@ -94,7 +94,7 @@ such as private keys.  On Unix-like systems, the permissions on this directory
 are set to disallow users other than its owner from reading the contents of
 the files.   See the 'configuration.rst' documentation file for details."""
 
-class _None(object):  # used as a marker in get_config()
+class _None(object):
     """
     This class is to be used as a marker in get_config()
     """
@@ -145,6 +145,22 @@ def create_node_dir(basedir, readme_text):
 
 
 def read_config(basedir, portnumfile, generated_files=[], _valid_config_sections=None):
+    """
+    Read and validate configuration.
+
+    :param unicode basedir: directory where configuration data begins
+
+    :param unicode portnumfile: filename fragment for "port number" files
+
+    :param list generated_files: a list of automatically-generated
+        configuration files.
+
+    :param dict _valid_config_sections: (internal use, optional) a
+        dict-of-dicts structure defining valid configuration sections and
+        keys
+
+    :returns: :class:`allmydata.node._Config` instance
+    """
     basedir = abspath_expanduser_unicode(unicode(basedir))
     if _valid_config_sections is None:
         _valid_config_sections = _common_config_sections