utils/vlog: Improve style and documentation in yosys.run

Signed-off-by: David Shah <davey1576@gmail.com>
diff --git a/yosys/run.py b/yosys/run.py
index f34ad57..0b475ea 100755
--- a/yosys/run.py
+++ b/yosys/run.py
@@ -4,26 +4,45 @@
 import yosys.utils
 
 def get_yosys():
-    return os.getenv('YOSYS', "yosys")
+    """Return how to execute Yosys: the value of $YOSYS if set, otherwise just
+    `yosys`."""
+    return os.getenv("YOSYS", "yosys")
 
 def get_output(params):
+    """Run Yosys with given command line parameters, and return stdout as a string"""
     cmd = [get_yosys()] + params
     return subprocess.check_output(cmd).decode("utf-8")
 
 defines = []
 
 def add_define(defname):
+    """Add a Verilog define to the list of defines to set in Yosys"""
     defines.append(defname)
 
 def get_defines():
+    """Return a list of set Verilog defines, as a list of arguments to pass to Yosys `read_verilog`"""
     return " ".join(["-D" + _ for _ in defines])
 
 def commands(commands, infiles = []):
+    """Run a given string containing Yosys commands
+
+    Inputs
+    -------
+    commands : string of Yosys commands to run
+    infiles : list of input files
+    """
     commands = "read_verilog %s %s; " % (get_defines(), " ".join(infiles)) + commands
     params = ["-q", "-p", commands]
     return get_output(params)
 
 def script(script, infiles = []):
+    """Run a Yosys script given a path to the script
+
+    Inputs
+    -------
+    script : path to Yosys script to run
+    infiles : list of input files
+    """
     params = ["-q", "-s", script] + infiles
     return get_output(params)
 
@@ -42,7 +61,7 @@
     prep_opts = "-flatten" if flatten else ""
     json_opts = "-aig" if aig else ""
     if mode is not None:
-        mode_str = "chparam -set MODE \"%s\" %s; " % (mode, mode_mod)
+        mode_str = 'chparam -set MODE "%s" %s; ' % (mode, mode_mod)
     else:
         mode_str = ""
     cmds = "%sprep %s; write_json %s" % (mode_str, prep_opts, json_opts)
@@ -54,7 +73,14 @@
 
 def extract_pin(module, pstr, _regex=re.compile(r"([^/]+)/([^/]+)")):
     """
-    Extract the pin from a line of the result of a Yosys select command
+    Extract the pin from a line of the result of a Yosys select command, or
+    None if the command result is irrelevant (e.g. does not correspond to the
+    correct module)
+
+    Inputs
+    -------
+    module: Name of module to extract pins from
+    pstr: Line from Yosys select command (`module/pin` format)
     """
     m = re.match(r"([^/]+)/([^/]+)", pstr)
     if m and m.group(1) == module:
@@ -68,6 +94,12 @@
     """
     Run a Yosys select command (given the expression and input files) on a module
     and return the result as a list of pins
+
+    Inputs
+    -------
+    infiles: List of Verilog source files to pass to Yosys
+    module: Name of module to run command on
+    expr: Yosys selector expression for select command
     """
 
     """TODO: All of these functions involve a fairly large number of calls to Yosys
@@ -91,13 +123,33 @@
 
 def get_combinational_sinks(infiles, module, innet):
     """Return a list of output ports which are combinational sinks of a given
-    input."""
+    input.
+
+    Inputs
+    -------
+    infiles: List of Verilog source files to pass to Yosys
+    module: Name of module to run command on
+    innet: Name of input net to find sinks of
+    """
     return do_select(infiles, module, "%s %%coe* o:* %%i %s %%d" % (innet, innet))
 
 def list_clocks(infiles, module):
-    """Return a list of clocks in the module"""
+    """Return a list of clocks in the module
+
+    Inputs
+    -------
+    infiles: List of Verilog source files to pass to Yosys
+    module: Name of module to run command on
+    """
     return do_select(infiles, module, "c:* %x:+[CLK] a:CLOCK=1 %u c:* %d")
 
 def get_clock_assoc_signals(infiles, module, clk):
-    """Return the list of signals associated with a given clock."""
+    """Return the list of signals associated with a given clock.
+
+    Inputs
+    -------
+    infiles: List of Verilog source files to pass to Yosys
+    module: Name of module to run command on
+    clk: Name of clock to find associated signals
+    """
     return do_select(infiles, module, "select -list %s %%x* i:* o:* %%u %%i a:ASSOC_CLOCK=%s %%u %s %%d" % (clk, clk, clk))