Add an option for the coverage builder if source-undocumented items are matched.

1 files changed, 16 insertions, 7 deletions

diff --git a/sphinx/ext/coverage.py b/sphinx/ext/coverage.py
index e7a7425f3..e3e3a65eb 100644
--- a/sphinx/ext/coverage.py
+++ b/sphinx/ext/coverage.py
@@ -105,7 +105,8 @@ class CoverageBuilder(Builder):
         output_file = path.join(self.outdir, 'c.txt')
         op = open(output_file, 'w')
         try:
-            write_header(op, 'Undocumented C API elements', '=')
+            if self.config.coverage_write_headline:
+                write_header(op, 'Undocumented C API elements', '=')
             op.write('\n')
 
             for filename, undoc in self.c_undoc.iteritems():
@@ -120,6 +121,8 @@ class CoverageBuilder(Builder):
         objects = self.env.domaindata['py']['objects']
         modules = self.env.domaindata['py']['modules']
 
+        skip_undoc = self.config.coverage_skip_undoc_in_source
+
         for mod_name in modules:
             ignore = False
             for exp in self.mod_ignorexps:
@@ -160,13 +163,17 @@ class CoverageBuilder(Builder):
                             if exp.match(name):
                                 break
                         else:
+                            if skip_undoc and not obj.__doc__:
+                                continue
                             funcs.append(name)
                 elif inspect.isclass(obj):
                     for exp in self.cls_ignorexps:
                         if exp.match(name):
                             break
                     else:
-                        if full_name not in objects and not obj.__doc__:
+                        if full_name not in objects:
+                            if skip_undoc and not obj.__doc__:
+                                continue
                             # not documented at all
                             classes[name] = []
                             continue
@@ -177,17 +184,18 @@ class CoverageBuilder(Builder):
                             if attr_name not in obj.__dict__:
                                 continue
                             attr = getattr(obj, attr_name)
-                            if (not inspect.ismethod(attr)
-                                and not inspect.isfunction(attr)):
+                            if not (inspect.ismethod(attr) or
+                                    inspect.isfunction(attr)):
                                 continue
                             if attr_name[0] == '_':
                                 # starts with an underscore, ignore it
                                 continue
+                            if skip_undoc and not attr.__doc__:
+                                # skip methods without docstring if wished
+                                continue
 
                             full_attr_name = '%s.%s' % (full_name, attr_name)
                             if full_attr_name not in objects:
-                                if len(obj.__doc__) > 0:
-                                    continue
                                 attrs.append(attr_name)
 
                         if attrs:
@@ -252,4 +260,5 @@ def setup(app):
     app.add_config_value('coverage_c_path', [], False)
     app.add_config_value('coverage_c_regexes', {}, False)
     app.add_config_value('coverage_ignore_c_items', {}, False)
-    app.add_config_value('coverage_write_headline', {}, False)
+    app.add_config_value('coverage_write_headline', True, False)
+    app.add_config_value('coverage_skip_undoc_in_source', False, False)