@@ -1,6 +1,5 @@
-import random
+import shutil
 import os
-from functools import partial
 import textwrap
 
 from paths_cli.wizard.tools import yes_no, a_an
@@ -14,24 +13,62 @@
 
 from paths_cli.wizard import pause
 
-import shutil
 
 class Console:  # no-cov
+    """Manage actual I/O for the Wizard.
+
+    All direct interaction with the user is performed in this class.
+    """
     # TODO: add logging so we can output the session
     def print(self, *content):
+        """Write content to screen"""
         print(*content)
 
     def input(self, content):
+        """Read user input.
+
+        Parameters
+        ----------
+        content : str
+            input prompt
+        """
         return input(content)
 
     @property
     def width(self):
+        """Terminal width in columns"""
         return shutil.get_terminal_size((80, 24)).columns
 
-    def draw_hline(self):
-        self.print('═' * self.width)
+    def draw_hline(self, char='═'):
+        """Draw a separator line.
+
+        Parameters
+        ----------
+        char : str
+            string to use for line separator
+        """
+        n_chars = self.width // len(char)
+        self.print(char * n_chars)
+
 
 class Wizard:
+    """Friendly interactive Wizard
+
+    This class handles most of the user-facing interaction with the wizard,
+    including various conveniences for asking for certain user selections
+    (such as selecting between a number of possible choices.)
+
+    An instance of this class includes information about how the Wizard will
+    guide the user through various stages of simulation set-up.
+
+    The main method, ``Wizard.run_wizard()``, performs an entire simulation
+    set-up for that instance.
+
+    Parameters
+    ----------
+    steps : List[:class:`.WizardStep`]
+        ordered list of steps in this particular simulation set-up process
+    """
     def __init__(self, steps):
         self.steps = steps
         self.requirements = {
@@ -60,7 +97,8 @@ def _patch(self):  # no-cov
             self._patched = True
             StorageLoader.has_simstore_patch = True
 
-    def debug(content):  # no-cov
+    def debug(self, content):  # no-cov
+        """Print to console without pretty-printing"""
         # debug does no pretty-printing
         self.console.print(content)
 
@@ -84,6 +122,7 @@ def _speak(self, content, preface):
     @get_object
     def ask(self, question, options=None, default=None, helper=None,
             autohelp=False):
+        """Ask the user a question."""
         if helper is None:
             helper = Helper(None)
         if isinstance(helper, str):
@@ -92,30 +131,60 @@ def ask(self, question, options=None, default=None, helper=None,
         self.console.print()
         if result == "":
             if not autohelp:
-                return
+                return None
             result = "?"  # autohelp in this case
 
         if helper and result[0] in ["?", "!"]:
             self.say(helper(result))
-            return
+            return None
         return result
 
     def say(self, content, preface="🧙 "):
+        """Let the wizard make a statement.
+
+        Parameters
+        ----------
+        content : str or List[str]
+            Content to be presented to user. Input will be wrapped to fit
+            the user's terminal. If a list of strings, each element is
+            printed with a blank line separating them.
+        preface : str
+            preface, used only on the first line of the first element of the
+            ``content``.
+        """
         self._speak(content, preface)
         self.console.print()  # adds a blank line
 
     def start(self, content):
+        """Specialized version of :method:`.say` for starting an object"""
         # eventually, this will tweak so that we preface with a line and use
-        # green text here
+        # green text here  TODO: possibly remove?
         self.say(content)
 
     def bad_input(self, content, preface="👺 "):
+        """Specialized version of :method:`.say` for printing errors"""
         # just changes the default preface; maybe print 1st line red?
         self.say(content, preface)
 
     @get_object
     def ask_enumerate_dict(self, question, options, helper=None,
                            autohelp=False):
+        """Ask the user to select from a set of options.
+
+        Parameters
+        ----------
+        question : str
+            the question to ask the user (asked before the options are
+            listed)
+        options: Dict[str, Any]
+            mapping of the string name (shown to the user in the list of
+            options) to the object to return
+
+        Returns
+        -------
+        Any :
+            the object the user selected by either name or number
+        """
         self.say(question)
         opt_string = "\n".join([f" {(i+1):>3}. {opt}"
                                 for i, opt in enumerate(options)])
@@ -138,6 +207,8 @@ def ask_enumerate_dict(self, question, options, helper=None,
 
     def ask_enumerate(self, question, options):
         """Ask the user to select from a list of options"""
+        # NOTE: new code should use ask_enumerate_dict. If we were past the
+        # beta stage, this would probably issue a PendingDeprecationWarning
         self.say(question)
         opt_string = "\n".join([f" {(i+1):>3}. {opt}"
                                 for i, opt in enumerate(options)])
@@ -161,31 +232,51 @@ def ask_enumerate(self, question, options):
 
     @get_object
     def ask_load(self, question, loader, helper=None, autohelp=False):
+        """Load from user input according to ``loader`` method
+
+        Parameters
+        ----------
+        question : str
+            string to ask the user
+        loader : Callable[str] -> Any
+            method that converts user input into the desired format for the
+            object
+        helper : :class:`.Helper`
+            object to handle user requests for help
+        """
         as_str = self.ask(question, helper=helper)
         try:
             result = loader(as_str)
         except Exception as e:
             self.exception(f"Sorry, I couldn't understand the input "
                            f"'{as_str}'.", e)
-            return
+            return None
         return result
 
-    # this should match the args for wizard.ask
     @get_object
     def ask_custom_eval(self, question, options=None, default=None,
                         helper=None, type_=float):
+        """Get user input and convert using custom_eval.
+
+        .. note::
+            New code should use ask_load. If we were past beta, this would
+            have a PendingDeprecationWarning.
+        """
         as_str = self.ask(question, options=options, default=default,
                           helper=helper)
         try:
             result = type_(custom_eval(as_str))
         except Exception as e:
             self.exception(f"Sorry, I couldn't understand the input "
                            f"'{as_str}'", e)
-            return
+            return None
         return result
 
-
     def obj_selector(self, store_name, text_name, create_func):
+        """Select an object from the wizard's pseudo-storage
+        """
+        # TODO: this seems like something that might be possible to refactor
+        # out
         opts = {name: lambda wiz, o=obj: o
                 for name, obj in getattr(self, store_name).items()}
         create_new = f"Create a new {text_name}"
@@ -198,10 +289,27 @@ def obj_selector(self, store_name, text_name, create_func):
         return obj
 
     def exception(self, msg, exception):
+        """Specialized version of :method:`.bad_input` for exceptions"""
         self.bad_input(f"{msg}\nHere's the error I got:\n"
                        f"{exception.__class__.__name__}: {exception}")
 
-    def name(self, obj, obj_type, store_name, default=None):
+    def name(self, obj, obj_type, store_name):
+        """Name a newly created object.
+
+        Parameters
+        ----------
+        obj : Any
+            the new object
+        obj_type : str
+            user-facing name of the object type
+        store_name : str
+            name of the OPS store in which to save this object type
+
+        Returns
+        -------
+        Any :
+            named object
+        """
         self.say(f"Now let's name your {obj_type}.")
         name = None
         while name is None:
@@ -220,8 +328,23 @@ def name(self, obj, obj_type, store_name, default=None):
                  + name_joke(name, obj_type))
         return obj
 
-
     def register(self, obj, obj_type, store_name):
+        """Register a newly-created object in the storage
+
+        Parameters
+        ----------
+        obj : Any
+            the new object
+        obj_type : str
+            user-facing name of the object type
+        store_name : str
+            name of the OPS store in which to save this object type
+
+        Returns
+        -------
+        Any :
+            input object, possibly after being named
+        """
         if not obj.is_named:
             obj = self.name(obj, obj_type, store_name)
         store_dict = getattr(self, store_name)
@@ -230,31 +353,38 @@ def register(self, obj, obj_type, store_name):
 
     @get_object
     def get_storage(self):
+        """Create a file to store the object database to.
+
+        Returns
+        -------
+        :class:`openpathsampling.experimental.storage.Storage` :
+            the storage file object
+        """
         from openpathsampling.experimental.storage import Storage
         filename = self.ask("Where would you like to save your setup "
                             "database?")
         if not filename.endswith(".db"):
             self.bad_input("Files produced by this wizard must end in "
                            "'.db'.")
-            return
+            return None
 
         if os.path.exists(filename):
             overwrite = self.ask(f"{filename} exists. Overwrite it?",
                                  options=["[Y]es", "[N]o"])
             overwrite = yes_no(overwrite)
             if not overwrite:
-                return
+                return None
 
         try:
             storage = Storage(filename, mode='w')
         except Exception as e:
             self.exception(FILE_LOADING_ERROR_MSG, e)
-            return
+            return None
 
         return storage
 
-
     def _storage_description_line(self, store_name):
+        """List number of each type of object to be stored"""
         store = getattr(self, store_name)
         if len(store) == 0:
             return ""
@@ -266,6 +396,13 @@ def _storage_description_line(self, store_name):
         return line
 
     def save_to_file(self, storage):
+        """Save Wizard's pseudostorage to a real file.
+
+        Parameters
+        ----------
+        storage : :class:`openpathsampling.experimental.storage.Storage`
+            storage file to save to
+        """
         store_names = ['engines', 'cvs', 'states', 'networks', 'schemes']
         lines = [self._storage_description_line(store_name)
                  for store_name in store_names]
@@ -280,6 +417,7 @@ def save_to_file(self, storage):
         self.say("Success! Everything has been stored in your file.")
 
     def _req_do_another(self, req):
+        """Check whether requirement requires us to do another"""
         store, min_, max_ = req
         if store is None:
             return (True, False)
@@ -290,6 +428,7 @@ def _req_do_another(self, req):
         return requires, allows
 
     def _ask_do_another(self, obj_type):
+        """Ask the user whether to do another"""
         do_another = None
         while do_another is None:
             do_another_char = self.ask(
@@ -303,6 +442,7 @@ def _ask_do_another(self, obj_type):
         return do_another
 
     def _do_one(self, step, req):
+        """Create a single object of the sort generated by ``step``"""
         try:
             obj = step.func(self)
         except RestartObjectException:
@@ -320,6 +460,7 @@ def _do_one(self, step, req):
         return do_another
 
     def run_wizard(self):
+        """Run this Wizard."""
         self.start("Hi! I'm the OpenPathSampling Wizard.")
         # TODO: next line is only temporary
         self.say("Today I'll help you set up a 2-state TPS simulation.")
@@ -343,6 +484,7 @@ def run_wizard(self):
 
     @get_object
     def _ask_save(self):
+        """Ask user whether to save before quitting"""
         do_save_char = self.ask("Before quitting, would you like to save "
                                 "the objects you've created so far?")
         try: