#1123: fix the docs for the str.split(None, sep) case.

Also expand a few other methods' docs, which had more info in the deprecated string module docs.

1 files changed, 32 insertions, 23 deletions

diff --git a/Doc/library/stdtypes.rst b/Doc/library/stdtypes.rst
index b509e2e..0d46cc6 100644
--- a/Doc/library/stdtypes.rst
+++ b/Doc/library/stdtypes.rst
@@ -686,9 +686,9 @@ string functions based on regular expressions.
 
 .. method:: str.count(sub[, start[, end]])
 
-   Return the number of occurrences of substring *sub* in string S\
-   ``[start:end]``.  Optional arguments *start* and *end* are interpreted as in
-   slice notation.
+   Return the number of occurrences of substring *sub* in the range [*start*,
+   *end*].  Optional arguments *start* and *end* are interpreted as in slice
+   notation.
 
 
 .. method:: str.decode([encoding[, errors]])
@@ -737,8 +737,11 @@ string functions based on regular expressions.
 
 .. method:: str.expandtabs([tabsize])
 
-   Return a copy of the string where all tab characters are expanded using spaces.
-   If *tabsize* is not given, a tab size of ``8`` characters is assumed.
+   Return a copy of the string where all tab characters are replaced by one or
+   more spaces, depending on the current column and the given tab size.  The
+   column number is reset to zero after each newline occurring in the string.
+   If *tabsize* is not given, a tab size of ``8`` characters is assumed.  This
+   doesn't understand other non-printing characters or escape sequences.
 
 
 .. method:: str.find(sub[, start[, end]])
@@ -927,25 +930,29 @@ string functions based on regular expressions.
       Support for the *chars* argument.
 
 
-.. method:: str.split([sep [,maxsplit]])
+.. method:: str.split([sep[, maxsplit]])
 
-   Return a list of the words in the string, using *sep* as the delimiter string.
-   If *maxsplit* is given, at most *maxsplit* splits are done. (thus, the list will
-   have at most ``maxsplit+1`` elements).  If *maxsplit* is not specified, then
-   there is no limit on the number of splits (all possible splits are made).
-   Consecutive delimiters are not grouped together and are deemed to delimit empty
-   strings (for example, ``'1,,2'.split(',')`` returns ``['1', '', '2']``).  The
-   *sep* argument may consist of multiple characters (for example, ``'1, 2,
-   3'.split(', ')`` returns ``['1', '2', '3']``).  Splitting an empty string with a
-   specified separator returns ``['']``.
+   Return a list of the words in the string, using *sep* as the delimiter
+   string.  If *maxsplit* is given, at most *maxsplit* splits are done (thus,
+   the list will have at most ``maxsplit+1`` elements).  If *maxsplit* is not
+   specified, then there is no limit on the number of splits (all possible
+   splits are made).
+
+   If *sep is given, consecutive delimiters are not grouped together and are
+   deemed to delimit empty strings (for example, ``'1,,2'.split(',')`` returns
+   ``['1', '', '2']``).  The *sep* argument may consist of multiple characters
+   (for example, ``'1<>2<>3'.split('<>')`` returns ``['1', '2', '3']``).
+   Splitting an empty string with a specified separator returns ``['']``.
 
    If *sep* is not specified or is ``None``, a different splitting algorithm is
-   applied.  First, whitespace characters (spaces, tabs, newlines, returns, and
-   formfeeds) are stripped from both ends.  Then, words are separated by arbitrary
-   length strings of whitespace characters. Consecutive whitespace delimiters are
-   treated as a single delimiter (``'1  2  3'.split()`` returns ``['1', '2',
-   '3']``). Splitting an empty string or a string consisting of just whitespace
-   returns an empty list.
+   applied: runs of consecutive whitespace are regarded as a single separator,
+   and the result will contain no empty strings at the start or end if the
+   string has leading or trailing whitespace.  Consequently, splitting an empty
+   string or a string consisting of just whitespace with a ``None`` separator
+   returns ``[]``.
+
+   For example, ``' 1  2   3  '.split()`` returns ``['1', '2', '3']``, and
+   ``'  1  2   3  '.split(None, 1)`` returns ``['1', '2   3  ']``.
 
 
 .. method:: str.splitlines([keepends])
@@ -1035,8 +1042,10 @@ string functions based on regular expressions.
 
 .. method:: str.zfill(width)
 
-   Return the numeric string left filled with zeros in a string of length *width*.
-   The original string is returned if *width* is less than ``len(s)``.
+   Return the numeric string left filled with zeros in a string of length
+   *width*.  A sign prefix is handled correctly.  The original string is
+   returned if *width* is less than ``len(s)``.
+   
 
    .. versionadded:: 2.2.2