From d6c3885c9eb06d79613da0a055639d222fdfe65e Mon Sep 17 00:00:00 2001
From: Tim Hoffmann <2836374+timhoffm@users.noreply.github.com>
Date: Mon, 23 Jul 2018 12:37:03 +0200
Subject: [PATCH] Add description for metadata argument of savefig

---
 lib/matplotlib/backends/backend_agg.py | 54 ++++++++++++++++++++++++--
 lib/matplotlib/figure.py               | 12 +++++-
 src/_png.cpp                           |  3 ++
 3 files changed, 65 insertions(+), 4 deletions(-)

diff --git a/lib/matplotlib/backends/backend_agg.py b/lib/matplotlib/backends/backend_agg.py
index ca7a44700bcd..42e946ac892e 100644
--- a/lib/matplotlib/backends/backend_agg.py
+++ b/lib/matplotlib/backends/backend_agg.py
@@ -410,7 +410,7 @@ def restore_region(self, region, bbox=None, xy=None):
 
     def draw(self):
         """
-        Draw the figure using the renderer
+        Draw the figure using the renderer.
         """
         self.renderer = self.get_renderer(cleared=True)
         # acquire a lock on the shared font cache
@@ -440,7 +440,7 @@ def get_renderer(self, cleared=False):
         return self.renderer
 
     def tostring_rgb(self):
-        '''Get the image as an RGB byte string
+        '''Get the image as an RGB byte string.
 
         `draw` must be called at least once before this function will work and
         to update the renderer for any subsequent changes to the Figure.
@@ -465,7 +465,7 @@ def tostring_argb(self):
         return self.renderer.tostring_argb()
 
     def buffer_rgba(self):
-        '''Get the image as an RGBA byte string
+        '''Get the image as an RGBA byte string.
 
         `draw` must be called at least once before this function will work and
         to update the renderer for any subsequent changes to the Figure.
@@ -485,6 +485,47 @@ def print_raw(self, filename_or_obj, *args, **kwargs):
     print_rgba = print_raw
 
     def print_png(self, filename_or_obj, *args, **kwargs):
+        """
+        Write the figure to a PNG file.
+
+        Parameters
+        ----------
+        filename_or_obj : str or PathLike or file-like object
+            The file to write to.
+
+        metadata : dict, optional
+            Metadata in the PNG file as key-value pairs of bytes or latin-1
+            encodable strings.
+            According to the PNG specification, keys must be shorter than 79
+            chars.
+
+            The `PNG specification`_ defines some common keywords that may be
+            used as appropriate:
+
+            - Title: Short (one line) title or caption for image.
+            - Author: Name of image's creator.
+            - Description: Description of image (possibly long).
+            - Copyright: Copyright notice.
+            - Creation Time: Time of original image creation
+              (usually RFC 1123 format).
+            - Software: Software used to create the image.
+            - Disclaimer: Legal disclaimer.
+            - Warning: Warning of nature of content.
+            - Source: Device used to create the image.
+            - Comment: Miscellaneous comment;
+              conversion from other image format.
+
+            Other keywords may be invented for other purposes.
+
+            If 'Software' is not given, an autogenerated value for matplotlib
+            will be used.
+
+            For more details see the `PNG specification`_.
+
+            .. _PNG specification: \
+                https://www.w3.org/TR/2003/REC-PNG-20031110/#11keywords
+
+        """
         FigureCanvasAgg.draw(self)
         renderer = self.get_renderer()
 
@@ -511,6 +552,13 @@ def print_to_buffer(self):
         # add JPEG support
         def print_jpg(self, filename_or_obj, *args, dryrun=False, **kwargs):
             """
+            Write the figure to a JPEG file.
+
+            Parameters
+            ----------
+            filename_or_obj : str or PathLike or file-like object
+                The file to write to.
+
             Other Parameters
             ----------------
             quality : int
diff --git a/lib/matplotlib/figure.py b/lib/matplotlib/figure.py
index cd21216a3956..1f41fa4b755a 100644
--- a/lib/matplotlib/figure.py
+++ b/lib/matplotlib/figure.py
@@ -1979,7 +1979,7 @@ def savefig(self, fname, *, frameon=None, transparent=None, **kwargs):
           savefig(fname, dpi=None, facecolor='w', edgecolor='w',
                   orientation='portrait', papertype=None, format=None,
                   transparent=False, bbox_inches=None, pad_inches=0.1,
-                  frameon=None)
+                  frameon=None, metadata=None)
 
         The output formats available depend on the backend being used.
 
@@ -2059,6 +2059,16 @@ def savefig(self, fname, *, frameon=None, transparent=None, **kwargs):
             A list of extra artists that will be considered when the
             tight bbox is calculated.
 
+        metadata : dict, optional
+            Key/value pairs to store in the image metadata. The supported keys
+            and defaults depend on the image format and backend:
+
+            - 'png' with Agg backend: See the parameter ``metadata`` of
+              `~.FigureCanvasAgg.print_png`.
+            - 'pdf' with pdf backend: See the parameter ``metadata`` of
+              `~.backend_pdf.PdfPages`.
+            - 'eps' and 'ps' with PS backend: Only 'Creator' is supported.
+
         """
         kwargs.setdefault('dpi', rcParams['savefig.dpi'])
         if frameon is None:
diff --git a/src/_png.cpp b/src/_png.cpp
index 043c42f77923..574e1f645ef4 100644
--- a/src/_png.cpp
+++ b/src/_png.cpp
@@ -128,6 +128,9 @@ const char *Py_write_png__doc__ =
     "    - Comment: Miscellaneous comment; conversion\n"
     "               from other image format\n"
     "\n"
+    "    For more details see the PNG specification:\n"
+    "    https://www.w3.org/TR/2003/REC-PNG-20031110/#11keywords\n"
+    "\n"
     "Returns\n"
     "-------\n"
     "buffer : bytes or None\n"