#15510: clarify textwrap's handling of whitespace, and add confirming tests.

Patch by Chris Jerdonek.

1 files changed, 13 insertions, 6 deletions

diff --git a/Doc/library/textwrap.rst b/Doc/library/textwrap.rst
index 547db79..3c1ecf6 100644
--- a/Doc/library/textwrap.rst
+++ b/Doc/library/textwrap.rst
@@ -25,6 +25,9 @@ otherwise,  you should use an instance of :class:`TextWrapper` for efficiency.
    Optional keyword arguments correspond to the instance attributes of
    :class:`TextWrapper`, documented below.  *width* defaults to ``70``.
 
+   See the :meth:`TextWrapper.wrap` method for additional details on how
+   :func:`wrap` behaves.
+
 
 .. function:: fill(text, width=70, **kwargs)
 
@@ -131,15 +134,18 @@ indentation from strings that have unwanted whitespace to the left of the text.
 
    .. attribute:: drop_whitespace
 
-      (default: ``True``) If true, whitespace that, after wrapping, happens to
-      end up at the beginning or end of a line is dropped (leading whitespace in
-      the first line is always preserved, though).
+      (default: ``True``) If true, whitespace at the beginning and ending of
+      every line (after wrapping but before indenting) is dropped.
+      Whitespace at the beginning of the paragraph, however, is not dropped
+      if non-whitespace follows it.  If whitespace being dropped takes up an
+      entire line, the whole line is dropped.
 
 
    .. attribute:: initial_indent
 
       (default: ``''``) String that will be prepended to the first line of
-      wrapped output.  Counts towards the length of the first line.
+      wrapped output.  Counts towards the length of the first line.  The empty
+      string is not indented.
 
 
    .. attribute:: subsequent_indent
@@ -200,8 +206,9 @@ indentation from strings that have unwanted whitespace to the left of the text.
 
       Wraps the single paragraph in *text* (a string) so every line is at most
       :attr:`width` characters long.  All wrapping options are taken from
-      instance attributes of the :class:`TextWrapper` instance. Returns a list
-      of output lines, without final newlines.
+      instance attributes of the :class:`TextWrapper` instance.  Returns a list
+      of output lines, without final newlines.  If the wrapped output has no
+      content, the returned list is empty.
 
 
    .. method:: fill(text)