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

Author: mananpal1997

pandas/core/strings.py

@@ -1095,24 +1095,48 @@ def str_pad(arr, width, side='left', fillchar=' '):
 
 def str_split(arr, pat=None, n=None):
     """
+    Split strings around given separator/delimiter.
+
     Split each string (a la re.split) in the Series/Index by given
     pattern, propagating NA 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, splits on whitespace.
     n : int, default -1 (all)
-        None, 0 and -1 will be interpreted as return all splits
+        * None, 0 and -1 will be interpreted as return all splits.
+        * Vary output dimensionality if `expand` is True:
+            - If n >= default splits, return all splits.
+            - If n < default splits, makes first n splits only.
     expand : bool, default False
-        * If True, return DataFrame/MultiIndex expanding dimensionality.
+        * If True, return DataFrame/MultiIndex expanding dimensionality.\
+         Appends None for padding.
         * If False, return Series/Index.
 
-    return_type : deprecated, use `expand`
-
     Returns
     -------
     split : Series/Index or DataFrame/MultiIndex of objects
+
+    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(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: