Update the pandas.Series.str.repeat docstring

pandas/core/strings.py

@@ -594,17 +594,59 @@ def str_replace(arr, pat, repl, n=-1, case=None, flags=0, regex=True):
 
 def str_repeat(arr, repeats):
     """
-    Duplicate each string in the Series/Index by indicated number
-    of times.
+    Duplicate each string repeated by indicated number of times.
 
     Parameters
     ----------
     repeats : int or array
-        Same value for all (int) or different value per (array)
+        Same value for all (int) or different value per (array).
 
     Returns
     -------
     repeated : Series/Index of objects
+        Same type as the original object
+
+    Examples
+    --------
+    >>> s = pd.Series(['a', 'b', 'c', 'd', 'e'])
+
+    Using same value for all:
+
+    >>> s.str.repeat(4)
+    0    aaaa
+    1    bbbb
+    2    cccc
+    3    dddd
+    4    eeee
+    dtype: object
+
+    Using different value per element:
+
+    >>> s.str.repeat([3, 2, 5, 1, 4])
+    0      aaa
+    1       bb
+    2    ccccc
+    3        d
+    4     eeee
+    dtype: object
+
+    Passing zero or negative integer will return an empty string
+
+    >>> s.str.repeat([0, 0, -2, -1, 0])
+    0
+    1
+    2
+    3
+    4
+    dtype: object
+
+    Notes
+    --------
+    A passed value of zero or negative integer will return an empty string.
+
+    See also
+    --------
+    numpy.ndarray.repeat: Repeat elements of an array.
     """
     if is_scalar(repeats):