DOC: Improve docstring for pandas.DataFrame.plot.area

Author: DZPM

pandas/plotting/_core.py

@@ -2818,18 +2818,42 @@ def kde(self, bw_method=None, ind=None, **kwds):
 
     def area(self, x=None, y=None, **kwds):
         """
-        Area plot
+        Draw an area plot of the input series using matplotlib.
+
+        An area plot displays graphically quantitative data.
+        This function wraps the matplotlib area function.
 
         Parameters
         ----------
-        x, y : label or position, optional
-            Coordinates for each point.
-        `**kwds` : optional
+        x : label or position, optional
+            Coordinates for X point.
+        y : label or position, optional
+            Coordinates for Y point.
+        kwds : optional
             Keyword arguments to pass on to :py:meth:`pandas.DataFrame.plot`.
 
         Returns
         -------
-        axes : matplotlib.AxesSubplot or np.array of them
+        matplotlib.AxesSubplot or numpy.ndarray
+            Area plot generated.
+
+        See Also
+        --------
+        pandas.DataFrame.plot : Draw a plot using matplotlib.
+
+        Examples
+        --------
+        .. plot::
+            :context: close-figs
+
+            This example draws an area plot based on the length and width of
+            some animals, displayed in three bins
+
+            >>> df = pd.DataFrame({
+            ...     'sales': [3, 2, 3, 9, 10, 6],
+            ...     'visits': [20, 42, 28, 62, 81, 50],
+            ... })
+            >>> area = df.plot.area()
         """
         return self(kind='area', x=x, y=y, **kwds)