DOC: update the Series.str.join docstring

pandas/core/strings.py

@@ -941,17 +941,52 @@ 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
+    --------
+
+    Example with a list that contains non-string elements.
+
+    >>> s = pd.Series({1: ['lion', 'elephant', 'zebra'],
+    ...                2: [1.1, 2.2, 3.3],
+    ...                3: [np.nan, np.nan, np.nan]})
+    >>> s
+    1    [lion, elephant, zebra]
+    2            [1.1, 2.2, 3.3]
+    3            [nan, nan, nan]
+    dtype: object
+
+    Join all lists using an '-', the list of floats will become a NaN.
+
+    >>> s.str.join('-')
+    1    lion-elephant-zebra
+    2                    NaN
+    3                    NaN
+    dtype: object
     """
     return _na_map(sep.join, arr)