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

doc/ext/coverage.rst

@@ -14,6 +14,7 @@ This extension features one additional builder, the :class:`CoverageBuilder`.
 
 .. todo:: Write this section.
 
+
 Several new configuration values can be used to specify what the builder
 should check:
 
@@ -30,3 +31,14 @@ should check:
 .. confval:: coverage_ignore_c_items
 
 .. confval:: coverage_write_headline
+
+   Set to ``False`` to not write headlines.
+
+   .. versionadded:: 1.1
+
+.. confval:: coverage_skip_undoc_in_source
+
+   Skip objects that are not documented in the source with a docstring.
+   ``False`` by default.
+
+   .. versionadded:: 1.1

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)
+                            if not (inspect.ismethod(attr) or
-                                and not inspect.isfunction(attr)):
+                                    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)

tests/test_coverage.py

@@ -27,6 +27,8 @@ def test_build(app):
     assert ' * function\n' not in py_undoc  # these two are documented
     assert ' * Class\n' not in py_undoc     # in autodoc.txt
 
+    assert ' * mod -- No module named mod'  # in the "failed import" section
+
     c_undoc = (app.outdir / 'c.txt').text()
     assert c_undoc.startswith('Undocumented C API elements\n'
                               '===========================\n')