# HG changeset patch
# User Ben Finney <ben@benfinney.id.au>
# Date 1373264974 -36000
#      Mon Jul 08 16:29:34 2013 +1000
# Node ID 9d22bc60bd4f5124070d2af696ddd94b2ea0f2e4
# Parent  65f2c92ed0798343e096cdd86511d65f83ce30cc
issue12645: Clarify (and PEP257-ify) docstring.

As part of understanding the docstring for
`test.support.import_fresh_module`, I re-worded and re-formatted the
docstring for PEP 257 compliance.

diff -r 65f2c92ed079 -r 9d22bc60bd4f Lib/test/support.py
--- a/Lib/test/support.py	Sun Jul 07 23:30:24 2013 +0200
+++ b/Lib/test/support.py	Mon Jul 08 16:29:34 2013 +1000
@@ -166,18 +166,23 @@
 
 
 def import_fresh_module(name, fresh=(), blocked=(), deprecated=False):
-    """Imports and returns a module, deliberately bypassing the sys.modules cache
-    and importing a fresh copy of the module. Once the import is complete,
-    the sys.modules cache is restored to its original state.
+    """ Import and return a fresh copy of the Python module named `name`.
 
-    Modules named in fresh are also imported anew if needed by the import.
-    If one of these modules can't be imported, None is returned.
+        Import and return a module, deliberately bypassing the `sys.modules`
+        cache and importing a fresh copy of the module named `name`. Once the
+        import is complete, restore the `sys.modules` cache to its original
+        state.
 
-    Importing of modules named in blocked is prevented while the fresh import
-    takes place.
+        If the module is named in `fresh` (a collection of names), also
+        import those modules anew if needed by the import. If one of these
+        modules can't be imported, return ``None``.
 
-    If deprecated is True, any module or package deprecation messages
-    will be suppressed."""
+        Prevent modules named in `blocked` while the fresh import takes place.
+
+        If `deprecated` is True, suppress any module or package deprecation
+        messages.
+
+        """
     # NOTE: test_heapq, test_json and test_warnings include extra sanity checks
     # to make sure that this utility function is working as expected
     with _ignore_deprecated_imports(deprecated):