#15510: clarify textwrap's handling of whitespace, and add confirming tests.
Patch by Chris Jerdonek.
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 @@
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 @@
.. 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 @@
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)