From c770984867cfbb38124f3c803860c5b354bb84b9 Mon Sep 17 00:00:00 2001
From: wiredfool <eric-github@soroos.net>
Date: Wed, 19 Nov 2014 15:35:01 -0800
Subject: [PATCH] Document all the save params for PNG, and their references
 [ci skip]

---
 PIL/PngImagePlugin.py                | 47 +++++++++++++++++++++++-----
 docs/PIL.rst                         | 23 ++++++++++++++
 docs/handbook/image-file-formats.rst |  9 ++++++
 3 files changed, 72 insertions(+), 7 deletions(-)

diff --git a/PIL/PngImagePlugin.py b/PIL/PngImagePlugin.py
index fcf27aba0..8403461be 100644
--- a/PIL/PngImagePlugin.py
+++ b/PIL/PngImagePlugin.py
@@ -149,31 +149,56 @@ class ChunkStream:
         return cids
 
 
-# --------------------------------------------------------------------
-# Subclass of string to allow iTXt chunks to look like strings while
-# keeping their extra information
-
 class iTXt(str):
+    """
+    Subclass of string to allow iTXt chunks to look like strings while
+    keeping their extra information
+
+    """
     @staticmethod
     def __new__(cls, text, lang, tkey):
+        """
+        :param value: value for this key
+        :param lang: language code
+        :param tkey: UTF-8 version of the key name
+        """
+        
         self = str.__new__(cls, text)
         self.lang = lang
         self.tkey = tkey
         return self
 
 
-# --------------------------------------------------------------------
-# PNG chunk container (for use with save(pnginfo=))
-
 class PngInfo:
+    """
+    PNG chunk container (for use with save(pnginfo=))
+
+    """
 
     def __init__(self):
         self.chunks = []
 
     def add(self, cid, data):
+        """Appends an arbitrary chunk. Use with caution.
+
+        :param cid: a byte string, 4 bytes long.
+        :param data: a byte string of the encoded data
+
+        """
+        
         self.chunks.append((cid, data))
 
     def add_itxt(self, key, value, lang="", tkey="", zip=False):
+        """Appends an iTXt chunk.
+
+        :param key: latin-1 encodable text key name
+        :param value: value for this key
+        :param lang: language code
+        :param tkey: UTF-8 version of the key name
+        :param zip: compression flag
+
+        """
+        
         if not isinstance(key, bytes):
             key = key.encode("latin-1", "strict")
         if not isinstance(value, bytes):
@@ -191,6 +216,14 @@ class PngInfo:
                      value)
 
     def add_text(self, key, value, zip=0):
+        """Appends a text chunk.
+
+        :param key: latin-1 encodable text key name
+        :param value: value for this key, text or an
+           :py:class:`PIL.PngImagePlugin.iTXt` instance
+        :param zip: compression flag
+        
+        """
         if isinstance(value, iTXt):
             return self.add_itxt(key, value, value.lang, value.tkey, bool(zip))
 
diff --git a/docs/PIL.rst b/docs/PIL.rst
index 8bf89c685..53a61872b 100644
--- a/docs/PIL.rst
+++ b/docs/PIL.rst
@@ -113,6 +113,29 @@ can be found here.
     :undoc-members:
     :show-inheritance:
 
+:class:`PngImagePlugin.iTXt` Class
+----------------------------------
+
+.. autoclass:: PIL.PngImagePlugin.iTXt
+    :members:
+    :undoc-members:
+    :show-inheritance:
+
+    .. method:: __new__(cls, text, lang, tkey)
+
+        :param value: value for this key
+        :param lang: language code
+        :param tkey: UTF-8 version of the key name
+
+:class:`PngImagePlugin.PngInfo` Class
+-------------------------------------
+
+.. autoclass:: PIL.PngImagePlugin.PngInfo
+    :members:
+    :undoc-members:
+    :show-inheritance:
+
+
 :mod:`TarIO` Module
 -------------------
 
diff --git a/docs/handbook/image-file-formats.rst b/docs/handbook/image-file-formats.rst
index a1961fa7c..f9216818d 100644
--- a/docs/handbook/image-file-formats.rst
+++ b/docs/handbook/image-file-formats.rst
@@ -332,6 +332,9 @@ The :py:meth:`~PIL.Image.Image.open` method sets the following
     Transparency color index. This key is omitted if the image is not a
     transparent palette image.
 
+``Open`` also sets ``Image.text`` to a list of the values of the
+``tEXt``, ``zTXt``, and ``iTXt`` chunks of the PNG image.
+
 The :py:meth:`~PIL.Image.Image.save` method supports the following options:
 
 **optimize**
@@ -343,6 +346,12 @@ The :py:meth:`~PIL.Image.Image.save` method supports the following options:
     For ``P``, ``L``, and ``RGB`` images, this option controls what
     color image to mark as transparent.
 
+**dpi**
+    A tuple of two numbers corresponding to the desired dpi in each direction. 
+
+**pnginfo**
+    A :py:class:`PIL.PngImagePlugin.PngInfo` instance containing text tags.
+
 **bits (experimental)**
     For ``P`` images, this option controls how many bits to store. If omitted,
     the PNG writer uses 8 bits (256 colors).