updated doc for pandas.Series.str.split() method

pandas/core/strings.py

@@ -1095,24 +1095,61 @@ def str_pad(arr, width, side='left', fillchar=' '):
 
 def str_split(arr, pat=None, n=None):
     """
-    Split each string (a la re.split) in the Series/Index by given
-    pattern, propagating NA values. Equivalent to :meth:`str.split`.
+    Split strings around given separator/delimiter.
+
+    Split each string in the Series/Index by given
+    pattern, propagating NaN values. Equivalent to :meth:`str.split`.
 
     Parameters
     ----------
     pat : string, default None
-        String or regular expression to split on. If None, splits on whitespace
+        String or regular expression to split on.\
+         If `None`, split on whitespace.
     n : int, default -1 (all)
-        None, 0 and -1 will be interpreted as return all splits
+        Vary dimensionality of output.
+
+        * `None`, 0 and -1 will be interpreted as return all splits
     expand : bool, default False
-        * If True, return DataFrame/MultiIndex expanding dimensionality.
-        * If False, return Series/Index.
+        Expand the split strings into separate columns.
 
-    return_type : deprecated, use `expand`
+        * If `True`, return DataFrame/MultiIndex expanding dimensionality.
+        * If `False`, return Series/Index.
 
     Returns
     -------
+    Type matches caller unless `expand=True` (return type is `DataFrame`)
     split : Series/Index or DataFrame/MultiIndex of objects
+
+    Notes
+    -----
+    If `expand` parameter is `True` and:
+      - If n >= default splits, makes all splits
+      - If n < default splits, makes first n splits only
+      - Appends `None` for padding.
+
+    Examples
+    --------
+    >>> s = pd.Series(["this is good text", "but this is even better"])
+    >>> s.str.split()
+    0           [this, is, good, text]
+    1    [but, this, is, even, better]
+    dtype: object
+    >>> s.str.split("random")
+    0          [this is good text]
+    1    [but this is even better]
+    dtype: object
+    >>> s.str.split(expand=True)
+          0     1     2     3       4
+    0  this    is  good  text    None
+    1   but  this    is  even  better
+    >>> s.str.split(" is ", expand=True)
+              0            1
+    0      this    good text
+    1  but this  even better
+    >>> s.str.split("is", n=1, expand=True)
+            0                1
+    0      th     is good text
+    1  but th   is even better
     """
     if pat is None:
         if n is None or n == 0: