#14649: clarify DocTestSuite error when there are no docstrings.

Also adds tests to verify the documented behavior (which is probably a bug, as
indicated in the added comments).

Patch by Chris Jerdonek.

1 files changed, 10 insertions, 0 deletions

diff --git a/Doc/library/doctest.rst b/Doc/library/doctest.rst
index cdd6c26..cad03bd 100644
--- a/Doc/library/doctest.rst
+++ b/Doc/library/doctest.rst
@@ -1024,6 +1024,16 @@ from text files and modules with doctests:
 
    This function uses the same search technique as :func:`testmod`.
 
+   .. note::
+      Unlike :func:`testmod` and :class:`DocTestFinder`, this function raises
+      a :exc:`ValueError` if *module* contains no docstrings.  You can prevent
+      this error by passing a :class:`DocTestFinder` instance as the
+      *test_finder* argument with its *exclude_empty* keyword argument set
+      to ``False``::
+
+         >>> finder = doctest.DocTestFinder(exclude_empty=False)
+         >>> suite = doctest.DocTestSuite(test_finder=finder)
+
 
 Under the covers, :func:`DocTestSuite` creates a :class:`unittest.TestSuite` out
 of :class:`doctest.DocTestCase` instances, and :class:`DocTestCase` is a