From a432fc35da03eaa75c074f58ba44f0573c768d39 Mon Sep 17 00:00:00 2001
From: meejah <meejah@meejah.ca>
Date: Fri, 24 Aug 2018 15:41:31 -0600
Subject: [PATCH] docstring improvements

---
 src/allmydata/client.py | 16 ++++++++++++++--
 src/allmydata/node.py   | 18 +++++++++++++++++-
 2 files changed, 31 insertions(+), 3 deletions(-)

diff --git a/src/allmydata/client.py b/src/allmydata/client.py
index 77643d205..a9135470a 100644
--- a/src/allmydata/client.py
+++ b/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")
diff --git a/src/allmydata/node.py b/src/allmydata/node.py
index 695d77c49..132521f48 100644
--- a/src/allmydata/node.py
+++ b/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