#205: provide more helpful docstrings for the legacy singleton methods.

2 files changed, 22 insertions, 0 deletions

diff --git a/CHANGES.txt b/CHANGES.txt
index 8031206..57a7df2 100644
--- a/CHANGES.txt
+++ b/CHANGES.txt
@@ -12,8 +12,12 @@ Version 3.5.4b1
 - Running coverage under a debugger is unlikely to work, but it shouldn't fail
   with "TypeError: 'NoneType' object is not iterable".  Fixes `issue 201`_.
 
+- Docstrings for the legacy singleton methods are more helpful.  Thanks Marius
+  Gedminas.  Closes `issue 205`_.
+
 .. _issue 193: https://bitbucket.org/ned/coveragepy/issue/193/unicodedecodeerror-on-htmlpy
 .. _issue 201: https://bitbucket.org/ned/coveragepy/issue/201/coverage-using-django-14-with-pydb-on
+.. _issue 205: https://bitbucket.org/ned/coveragepy/issue/205/make-pydoc-coverage-more-friendly
 
 
 Version 3.5.3 --- 29 September 2012
diff --git a/coverage/__init__.py b/coverage/__init__.py
index 637bc7a..e2db3a5 100644
--- a/coverage/__init__.py
+++ b/coverage/__init__.py
@@ -42,6 +42,24 @@ def _singleton_method(name):
         if not _the_coverage:
             _the_coverage = coverage(auto_data=True)
         return getattr(_the_coverage, name)(*args, **kwargs)
+
+    import inspect
+    meth = getattr(coverage, name)
+    args, varargs, kw, defaults = inspect.getargspec(meth)
+    argspec = inspect.formatargspec(args[1:], varargs, kw, defaults)
+    docstring = meth.__doc__
+    wrapper.__doc__ = ("""\
+        A first-use-singleton wrapper around coverage.%(name)s.
+
+        This wrapper is provided for backward compatibility with legacy code.
+        New code should use coverage.%(name)s directly.
+
+        %(name)s%(argspec)s:
+
+        %(docstring)s
+        """ % locals()
+        )
+
     return wrapper