style: use good docstring style

Author: nedbat

cogapp/cogapp.py

@@ -91,7 +91,9 @@ class CogGeneratedError(CogError):
 
 class CogUserException(CogError):
     """An exception caught when running a user's cog generator.
+
     The argument is the traceback message to print.
+
     """
 
     pass
@@ -202,9 +204,11 @@ def outl(self, sOut="", **kw):
 
     def error(self, msg="Error raised by cog generator."):
         """The cog.error function.
+
         Instead of raising standard python errors, cog generators can use
         this function.  It will display the error without a scary Python
         traceback.
+
         """
         raise CogGeneratedError(msg)
 
@@ -363,8 +367,10 @@ def isEndOutputLine(self, s):
         return self.options.sEndOutput in s
 
     def createCogModule(self):
-        """Make a cog "module" object so that imported Python modules
-        can say "import cog" and get our state.
+        """Make a cog "module" object.
+
+        Imported Python modules can use "import cog" to get our state.
+
         """
         self.cogmodule = types.SimpleNamespace()
         self.cogmodule.path = []
@@ -390,9 +396,10 @@ def openInputFile(self, fname):
 
     def processFile(self, fIn, fOut, fname=None, globals=None):
         """Process an input file object to an output file object.
-        fIn and fOut can be file objects, or file names.
-        """
 
+        `fIn` and `fOut` can be file objects, or file names.
+
+        """
         sFileIn = fname or ""
         sFileOut = fname or ""
         fInToClose = fOutToClose = None
@@ -589,7 +596,9 @@ def processFile(self, fIn, fOut, fname=None, globals=None):
 
     def suffixLines(self, text):
         """Add suffixes to the lines in text, if our options desire it.
-        text is many lines, as a single string.
+
+        `text` is many lines, as a single string.
+
         """
         if self.options.sSuffix:
             # Find all non-blank lines, and add the suffix to the end.
@@ -598,8 +607,10 @@ def suffixLines(self, text):
         return text
 
     def processString(self, sInput, fname=None):
-        """Process sInput as the text to cog.
+        """Process `sInput` as the text to cog.
+
         Return the cogged output as a string.
+
         """
         fOld = io.StringIO(sInput)
         fNew = io.StringIO()
@@ -737,8 +748,9 @@ def processArguments(self, args):
 
     def callableMain(self, argv):
         """All of command-line cog, but in a callable form.
-        This is used by main.
-        argv is the equivalent of sys.argv.
+
+        This is used by main.  `argv` is the equivalent of sys.argv.
+
         """
         argv = argv[1:]
 

cogapp/makefiles.py

@@ -6,7 +6,7 @@
 
 
 def makeFiles(d, basedir="."):
-    """Create files from the dictionary `d`, in the directory named by `basedir`."""
+    """Create files from the dictionary `d` in the directory named by `basedir`."""
     for name, contents in d.items():
         child = os.path.join(basedir, name)
         if isinstance(contents, (bytes, str)):
@@ -22,8 +22,10 @@ def makeFiles(d, basedir="."):
 
 
 def removeFiles(d, basedir="."):
-    """Remove the files created by makeFiles.
+    """Remove the files created by `makeFiles`.
+
     Directories are removed if they are empty.
+
     """
     for name, contents in d.items():
         child = os.path.join(basedir, name)

cogapp/test_cogapp.py

@@ -526,9 +526,7 @@ def testMarkersSwitch(self):
 
 
 class FileStructureTests(TestCase):
-    """Test cases to check that we're properly strict about the structure
-    of files.
-    """
+    """Test that we're properly strict about the structure of files."""
 
     def isBad(self, infile, msg=None):
         infile = reindentBlock(infile)
@@ -704,14 +702,11 @@ def testNoErrorIfErrorNotCalled(self):
 
 
 class CogGeneratorGetCodeTests(TestCase):
-    """Unit tests against CogGenerator to see if its getCode() method works
-    properly.
-    """
+    """Tests for CogGenerator.getCode()."""
 
     def setUp(self):
-        """All tests get a generator to use, and short same-length names for
-        the functions we're going to use.
-        """
+        # All tests get a generator to use, and short same-length names for
+        # the functions we're going to use.
         self.gen = CogGenerator()
         self.m = self.gen.parseMarker
         self.l = self.gen.parseLine
@@ -1514,9 +1509,12 @@ def testFileEncodingOption(self):
 
 
 class TestCaseWithImports(TestCaseWithTempDir):
-    """When running tests which import modules, the sys.modules list
+    """Automatic resetting of sys.modules for tests that import modules.
+
+    When running tests which import modules, the sys.modules list
     leaks from one test to the next.  This test case class scrubs
     the list after each run to keep the tests isolated from each other.
+
     """
 
     def setUp(self):

cogapp/whiteutils.py

@@ -4,9 +4,7 @@
 
 
 def whitePrefix(strings):
-    """Determine the whitespace prefix common to all non-blank lines
-    in the argument list.
-    """
+    """Find the whitespace prefix common to non-blank lines in `strings`."""
     # Remove all blank lines from the list
     strings = [s for s in strings if s.strip() != ""]
 
@@ -31,9 +29,12 @@ def whitePrefix(strings):
 
 
 def reindentBlock(lines, newIndent=""):
-    """Take a block of text as a string or list of lines.
+    """Re-indent a block of text.
+
+    Take a block of text as a string or list of lines.
     Remove any common whitespace indentation.
-    Re-indent using newIndent, and return it as a single string.
+    Re-indent using `newIndent`, and return it as a single string.
+
     """
     sep, nothing = "\n", ""
     if isinstance(lines, bytes):