DOC: update the str_cat() docstring (Delhi)

pandas/core/strings.py

@@ -51,46 +51,56 @@ def str_cat(arr, others=None, sep=None, na_rep=None):
     """
     Concatenate strings in the Series/Index with given separator.
 
+    If `others` is specified, this function concatenates the Series/Index
+    and elements of `others` element-wise.
+    If `others` is not being passed then all values in the Series are
+    concatenated in a single string with a given `sep`.
+
     Parameters
     ----------
-    others : list-like, or list of list-likes
-      If None, returns str concatenating strings of the Series
+    others : list-like, or list of list-likes, optional
+        List-likes (or a list of them) of the same length as calling object.
+        If None, returns str concatenating strings of the Series.
     sep : string or None, default None
+        If None, concatenates without any separator.
     na_rep : string or None, default None
         If None, NA in the series are ignored.
 
     Returns
     -------
     concat : Series/Index of objects or str
 
+    See Also
+    --------
+    split : Split each string in the Series/Index
+
     Examples
     --------
-    When ``na_rep`` is `None` (default behavior), NaN value(s)
-    in the Series are ignored.
+    When not passing `other`, all values are concatenated into a single
+    string:
 
-    >>> Series(['a','b',np.nan,'c']).str.cat(sep=' ')
+    >>> s = pd.Series(['a', 'b', np.nan, 'c'])
+    >>> s.str.cat(sep=' ')
     'a b c'
 
-    >>> Series(['a','b',np.nan,'c']).str.cat(sep=' ', na_rep='?')
+    By default, NA values in the Series are ignored. Using `na_rep`, they
+    can be given a representation:
+
+    >>> pd.Series(['a', 'b', np.nan, 'c']).str.cat(sep=' ', na_rep='?')
     'a b ? c'
 
-    If ``others`` is specified, corresponding values are
+    If `others` is specified, corresponding values are
     concatenated with the separator. Result will be a Series of strings.
 
-    >>> Series(['a', 'b', 'c']).str.cat(['A', 'B', 'C'], sep=',')
+    >>> pd.Series(['a', 'b', 'c']).str.cat(['A', 'B', 'C'], sep=',')
     0    a,A
     1    b,B
     2    c,C
     dtype: object
 
-    Otherwise, strings in the Series are concatenated. Result will be a string.
-
-    >>> Series(['a', 'b', 'c']).str.cat(sep=',')
-    'a,b,c'
-
     Also, you can pass a list of list-likes.
 
-    >>> Series(['a', 'b']).str.cat([['x', 'y'], ['1', '2']], sep=',')
+    >>> pd.Series(['a', 'b']).str.cat([['x', 'y'], ['1', '2']], sep=',')
     0    a,x,1
     1    b,y,2
     dtype: object