moar docs

Author: jreback

doc/source/user_guide/reshaping.rst

@@ -809,7 +809,7 @@ Exploding a List-like Column
 
 .. versionadded:: 0.25.0
 
-Sometimes the value column is list-like:
+Sometimes the value column is list-like.
 
 .. ipython:: python
 
@@ -818,15 +818,23 @@ Sometimes the value column is list-like:
    df = pd.DataFrame({'keys': keys, 'values': values})
    df
 
-But we actually want to put each value onto its own row.
-For this purpose we can use ``~Series.explode``. This will replicate the index values:
+We can 'explode' this transforming each element of a list-like to a row, by using ``~Series.explode``. This will replicate the index values:
 
 .. ipython:: python
 
    df['values'].explode()
 
-You can merge this back into the original to expand the dataframe.
+You can join this with the original to get an expanded ``DataFrame``.
 
 .. ipython:: python
 
-   pd.merge(df, df['values'].explode(), left_index=True, right_index=True)
+   df[['keys']]join(df['values'].explode())
+
+
+This routine will preserve replace empty lists with ``np.nan`` and preserve scalar entries. The dtype of the resulting ``Series`` is always ``object``.
+
+.. ipython:: python
+
+   s = pd.Series([[1, 2, 3], np.nan, [], ['a', 'b']])
+   s
+   s.explode()

doc/source/whatsnew/v0.25.0.rst

@@ -187,7 +187,7 @@ The repr now looks like this:
 Series.explode to split list-like values to rows
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
-:class:`Series` has gained the :meth:`Series.explode` method to tranform list-likes to onto individual rows. See :ref:`section on Exploding list-like column <reshaping.html>` in docs for more information (:issue:`16538`)
+:class:`Series` has gained the :meth:`Series.explode` method to transform list-likes to individual rows. See :ref:`section on Exploding list-like column <reshaping.html>` in docs for more information (:issue:`16538`)
 
 
 .. ipython:: python

pandas/core/series.py

@@ -3637,7 +3637,7 @@ def reorder_levels(self, order):
         result.index = result.index.reorder_levels(order)
         return result
 
-    def explode(self):
+    def explode(self) -> 'Series':
         """
         Create new Series expanding a list-like column.
 
@@ -3674,6 +3674,13 @@ def explode(self):
         3      3
         3      4
         dtype: object
+
+        Notes
+        -----
+        This routine will explode list-likes including lists, tuples, Series, and np.ndarray.
+        The result dtype of the returned Series will always be object.
+        Scalars will be returned unchanged.
+        Empty list-likes will result in a np.nan for that row.
         """
         if not len(self):
             return self.copy()