DOC: update the Series.str.join docstring

pandas/core/strings.py

@@ -941,17 +941,69 @@ def str_get_dummies(arr, sep='|'):
 
 def str_join(arr, sep):
     """
-    Join lists contained as elements in the Series/Index with
-    passed delimiter. Equivalent to :meth:`str.join`.
+    Join lists contained as elements in the Series/Index with passed delimiter.
+
+    If the elements of a Series are lists themselves, join the content of these
+    lists using the delimiter passed to the function.
+    This function is an equivalent to :meth:`str.join`.
 
     Parameters
     ----------
-    sep : string
-        Delimiter
+    sep : str
+        Delimiter to use between list entries.
 
     Returns
     -------
-    joined : Series/Index of objects
+    Series/Index of objects
+
+    Notes
+    -----
+    If any of the lists does not contain string objects the result of the join
+    will be `NaN`.
+
+    See Also
+    --------
+    str.join : Standard library version of this method.
+    Series.str.split : Split strings around given separator/delimiter.
+
+    Examples
+    --------
+
+    >>> df = pd.Series({1: ['dog', 'cat', 'fish'],
+    ...                 2: ['lion', 'elephant', 'zebra'],
+    ...                 3: ['cow', 'pig', 'chicken']})
+    >>> df
+    1           [dog, cat, fish]
+    2    [lion, elephant, zebra]
+    3        [cow, pig, chicken]
+    dtype: object
+
+    Join all lists using '_'.
+
+    >>> df.str.join('_')
+    1           dog_cat_fish
+    2    lion_elephant_zebra
+    3        cow_pig_chicken
+    dtype: object
+
+    Example with a list that contains non-string elements.
+
+    >>> df = pd.Series({1: [1.1, 2.2, 3.3],
+    ...                 2: ['lion', 'elephant', 'zebra'],
+    ...                 3: ['cow', 'pig', 'chicken']})
+    >>> df
+    1            [1.1, 2.2, 3.3]
+    2    [lion, elephant, zebra]
+    3        [cow, pig, chicken]
+    dtype: object
+
+    Join all lists using an '-', the list of floats will become a NaN.
+
+    >>> df.str.join('-')
+    1                    NaN
+    2    lion-elephant-zebra
+    3        cow-pig-chicken
+    dtype: object
     """
     return _na_map(sep.join, arr)