Add description for metadata argument of savefig

timhoffm · timhoffm · commit ddbb0f660e99 · 2018-07-23T13:08:09.000+02:00
diff --git a/lib/matplotlib/backends/backend_agg.py b/lib/matplotlib/backends/backend_agg.py
@@ -485,6 +485,42 @@ def print_raw(self, filename_or_obj, *args, **kwargs):
     print_rgba = print_raw
 
     def print_png(self, filename_or_obj, *args, **kwargs):
+        """
+        Write the png data to the given file.
+
+        Parameters
+        ----------
+        filename_or_obj : str or PathLike of file-handle
+            The file to write to.
+
+        metadata : dict, optional
+            Metadata in the PNG file as key-value pairs of strings.
+            According to the PNG specification, keys must be shorter than 79
+            chars. The only supported encoding for both keywords and values is
+            Latin-1 (ISO 8859-1).
+
+            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.
+
+        """
         FigureCanvasAgg.draw(self)
         renderer = self.get_renderer()
 
diff --git 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
+              `.PdfPages`.
+            - 'eps' and 'ps' with PS backend: Only 'Creator' is supported.
+
         """
         kwargs.setdefault('dpi', rcParams['savefig.dpi'])
         if frameon is None:
