From 324679043657f885692db511a0714aa43a9385f0 Mon Sep 17 00:00:00 2001
From: Ned Batchelder <ned@nedbatchelder.com>
Date: Wed, 13 May 2009 09:13:45 -0400
Subject: Add the last few docstrings, and no pylint messages!

---
 .pylintrc           |  3 ++-
 Makefile            |  3 +--
 TODO.txt            |  3 ++-
 coverage/control.py | 33 +++++++++++++++++++++++++--------
 coverage/data.py    |  2 +-
 5 files changed, 31 insertions(+), 13 deletions(-)

diff --git a/.pylintrc b/.pylintrc
index 834dcc3..94f944c 100644
--- a/.pylintrc
+++ b/.pylintrc
@@ -61,6 +61,7 @@ load-plugins=
 #   C0323:311:coverage.report: Operator not followed by a space
 #   C0324: 15: Comma not followed by a space
 #   W0603: 28:call_singleton_method: Using the global statement
+#   W0703:133:CoverageData._read_file: Catch "Exception"
 # Messages that may be silly:
 #   R0201: 42:Tracer.stop: Method could be a function
 #   R0401:  1: Cyclic import (coverage -> coverage.control -> coverage.html)
@@ -69,7 +70,7 @@ load-plugins=
 # Messages that are noisy for now, eventually maybe we'll turn them on:
 #   C0111:169:coverage.analyze_morf: Missing docstring
 #   C0103:256:coverage.morf_filename: Invalid name "f" (should match [a-z_][a-z0-9_]{2,30}$)
-disable-msg=I0011,W0122,W0142,W0232,C0323,C0324,W0603, R0201,R0401,W0403,E1103, C0103
+disable-msg=I0011,W0122,W0142,W0232,C0323,C0324,W0603,W0703, R0201,R0401,W0403,E1103, C0103
 
 [REPORTS]
 
diff --git a/Makefile b/Makefile
index 8d37f87..f932df8 100644
--- a/Makefile
+++ b/Makefile
@@ -32,8 +32,7 @@ LINTABLE_TESTS = \
 	test/test_templite.py
 
 lint: 
-	-python -x /Python25/Scripts/pylint.bat --rcfile=.pylintrc coverage
-	-python -x /Python25/Scripts/pylint.bat --rcfile=.pylintrc $(LINTABLE_TESTS)
+	-python -x /Python25/Scripts/pylint.bat --rcfile=.pylintrc coverage $(LINTABLE_TESTS)
 	python /Python25/Lib/tabnanny.py coverage
 	python checkeol.py
 
diff --git a/TODO.txt b/TODO.txt
index 0275d9c..4e68243 100644
--- a/TODO.txt
+++ b/TODO.txt
@@ -63,6 +63,7 @@ x Tricky swapping of collector like figleaf, pycov, et al. (Don't need to do
     from the command line, to reconsider exclusions.
 - Reporting on files never touched by coverage (package completeness)
 - Why can't a morf also be a string, the name of a module?
+- ignore by module as well as file?
 
 
 * Beauty
@@ -116,7 +117,7 @@ x Tricky swapping of collector like figleaf, pycov, et al. (Don't need to do
     + Use sets instead of dicts
 - Switch from getopt to optparse.
 + Get rid of the recursive nonsense.
-- Docstrings.
++ Docstrings.
 + Remove huge document-style comments.
 - Better names:
     + self.cache -> self.cache_filename -> CoverageData.filename
diff --git a/coverage/control.py b/coverage/control.py
index dab9eca..ad4d3aa 100644
--- a/coverage/control.py
+++ b/coverage/control.py
@@ -94,7 +94,6 @@ class coverage:
             if canonical.startswith(self.sysprefix):
                 return False
         
-        # TODO: ignore by module as well as file?
         return canonical
 
     def use_cache(self, usecache):
@@ -161,7 +160,13 @@ class coverage:
         self.data.write()
 
     def combine(self):
-        """Entry point for combining together parallel-mode coverage data."""
+        """Combine together a number of similarly-named coverage data files.
+        
+        All coverage data files whose name starts with `data_file` (from the
+        coverage() constructor) will be read, and combined together into the
+        current measurements.
+        
+        """
         self.data.combine_parallel_data()
 
     def _harvest_data(self):
@@ -171,10 +176,26 @@ class coverage:
 
     # Backward compatibility with version 1.
     def analysis(self, morf):
+        """Like `analysis2` but doesn't return excluded line numbers."""
         f, s, _, m, mf = self.analysis2(morf)
         return f, s, m, mf
 
     def analysis2(self, morf):
+        """Analyze a module.
+        
+        `morf` is a module or a filename.  It will be analyzed to determine
+        its coverage statistics.  The return value is a 5-tuple:
+        
+          * The filename for the module.
+          * A list of line numbers of executable statements.
+          * A list of line numbers of excluded statements.
+          * A list of line numbers of statements not run (missing from execution).
+          * A readable formatted string of the missing line numbers.
+
+        The analysis uses the source file itself and the current measured
+        coverage data.
+
+        """
         code_unit = code_unit_factory(morf, self.file_locator)[0]
         st, ex, m, mf = self.analyze(code_unit)
         return code_unit.filename, st, ex, m, mf
@@ -182,11 +203,7 @@ class coverage:
     def analyze(self, code_unit):
         """Analyze a single code unit.
         
-        Returns a tuple of:
-        - a list of lines of statements in the source code,
-        - a list of lines of excluded statements,
-        - a list of lines missing from execution, and
-        - a readable string of missing lines.
+        Returns a 4-tuple: (statements, excluded, missing, missing formatted).
 
         """
         from coverage.parser import CodeParser
@@ -227,7 +244,7 @@ class coverage:
             )
 
     def report(self, morfs=None, show_missing=True, ignore_errors=False,
-                file=None, omit_prefixes=None):
+                file=None, omit_prefixes=None):     # pylint: disable-msg=W0622
         """Write a summary report to `file`.
         
         Each module in `morfs` is listed, with counts of statements, executed
diff --git a/coverage/data.py b/coverage/data.py
index 00d5b30..9e1e058 100644
--- a/coverage/data.py
+++ b/coverage/data.py
@@ -130,7 +130,7 @@ class CoverageData:
                 return lines
             else:
                 return {}
-        except:
+        except Exception:
             return {}
 
     def combine_parallel_data(self):
-- 
cgit v1.2.1