matplotlib
diff --git a/‎lib/matplotlib/backends/backend_pdf.py
Lines changed: 43 additions & 22 deletions b/‎lib/matplotlib/backends/backend_pdf.py
Lines changed: 43 additions & 22 deletions
@@ -2249,29 +2249,41 @@ class PdfPages(object):
     """
     A multi-page PDF file.
 
-    Use like this::
-
-        # Initialize:
-        with PdfPages('foo.pdf') as pdf:
-
-            # As many times as you like, create a figure fig and save it:
-            # When no figure is specified the current figure is saved
-            pdf.savefig(fig)
-            pdf.savefig()
-
-    (In reality PdfPages is a thin wrapper around PdfFile, in order to
-    avoid confusion when using savefig and forgetting the format
-    argument.)
+    Examples
+    --------
+
+    >>> import matplotlib.pyplot as plt
+    >>> # Initialize:
+    >>> with PdfPages('foo.pdf') as pdf:
+    ...     # As many times as you like, create a figure fig and save it:
+    ...     fig = plt.figure()
+    ...     pdf.savefig(fig)
+    ...     # When no figure is specified the current figure is saved
+    ...     pdf.savefig()
+
+    Notes
+    -----
+
+    In reality :class:`PdfPages` is a thin wrapper around :class:`PdfFile`, in
+    order to avoid confusion when using :func:`~matplotlib.pyplot.savefig` and
+    forgetting the format argument.
     """
     __slots__ = ('_file', 'keep_empty')
 
     def __init__(self, filename, keep_empty=True):
         """
-        Create a new PdfPages object that will be written to the file
-        named *filename*. The file is opened at once and any older
-        file with the same name is overwritten.
-        If keep_empty is set to False then empty pdf files will be deleted when
-        closed.
+        Create a new PdfPages object.
+
+        Parameters
+        ----------
+
+        filename: str
+            Plots using :meth:`PdfPages.savefig` will be written to a file at
+            this location. The file is opened at once and any older file with
+            the same name is overwritten.
+        keep_empty: bool, optional
+            If set to False, then empty pdf files will be deleted automatically
+            when closed.
         """
         self._file = PdfFile(filename)
         self.keep_empty = keep_empty
@@ -2302,10 +2314,19 @@ def infodict(self):
 
     def savefig(self, figure=None, **kwargs):
         """
-        Save the Figure instance *figure* to this file as a new page.
-        If *figure* is a number, the figure instance is looked up by
-        number, and if *figure* is None, the active figure is saved.
-        Any other keyword arguments are passed to Figure.savefig.
+        Saves a :class:`~matplotlib.figure.Figure` to this file as a new page.
+
+        Any other keyword arguments are passed to
+        :meth:`~matplotlib.figure.Figure.savefig`.
+
+        Parameters
+        ----------
+
+        figure: :class:`~matplotlib.figure.Figure` or int, optional
+            Specifies what figure is saved to file. If not specified, the
+            active figure is saved. If a :class:`~matplotlib.figure.Figure`
+            instance is provided, this figure is saved. If an int is specified,
+            the figure instance to save is looked up by number.
         """
         if isinstance(figure, Figure):
             figure.savefig(self, format='pdf', **kwargs)