DOC: Updated docstring for Series.str.cat (pandas-dev#35556)

pandas/core/strings.py

@@ -2371,8 +2371,7 @@ def cat(self, others=None, sep=None, na_rep=None, join="left"):
         join : {'left', 'right', 'outer', 'inner'}, default 'left'
             Determines the join-style between the calling Series/Index and any
             Series/Index/DataFrame in `others` (objects without an index need
-            to match the length of the calling Series/Index). To disable
-            alignment, use `.values` on any Series/Index/DataFrame in `others`.
+            to match the length of the calling Series/Index).
 
             .. versionadded:: 0.23.0
             .. versionchanged:: 1.0.0
@@ -2389,6 +2388,15 @@ def cat(self, others=None, sep=None, na_rep=None, join="left"):
         split : Split each string in the Series/Index.
         join : Join lists contained as elements in the Series/Index.
 
+        Notes
+        -----
+        Since version 1.0.0, index alignment is performed when
+        `others` is a Series/Index/DataFrame (or a list-like containing
+        one). To disable alignment (the behavior in and before v0.23.0),
+        convert `others` to a numpy array while passing it as an argument
+        (using `.to_numpy()`). See the Examples section below for more
+        information.
+
         Examples
         --------
         When not passing `others`, all values are concatenated into a single
@@ -2466,7 +2474,27 @@ def cat(self, others=None, sep=None, na_rep=None, join="left"):
         2    -c
         dtype: object
 
-        For more examples, see :ref:`here <text.concatenate>`.
+        When `others` is a Series/Index/DataFrame, it is advisable
+        to use `to_numpy()` while passing it to the function to
+        avoid unexpected results.
+
+        The following example demostrates this:
+
+        If `others` is a Series/Index/DataFrame and `to_numpy()`
+        **is not** used:
+
+        >>> idx = pd.Index(["a", "b", "c", "d", "e"])
+        >>> ser = pd.Series(["f", "g", "h", "i", "j"])
+        >>> idx.str.cat(ser) # the caller is an Index here
+        Index([nan, nan, nan, nan, nan], dtype='object')
+
+        When `to_numpy()` **is** used:
+
+        >>> idx.str.cat(ser.to_numpy())
+        Index(['af', 'bg', 'ch', 'di', 'ej'], dtype='object')
+
+        For other examples and usages, see
+        :ref:`here <text.concatenate>`.
         """
         from pandas import Index, Series, concat