From 348daf9490cde850e7d5c5c71b7ea3010ff123c9 Mon Sep 17 00:00:00 2001
From: Stephen Johnson <steve@steveasleep.com>
Date: Sat, 12 Oct 2013 13:57:27 -0700
Subject: [PATCH] Document ImageFile.Parser

---
 PIL/ImageFile.py             | 10 ++++++---
 docs/PIL.rst                 |  8 -------
 docs/reference/ImageFile.rst | 41 ++++++++++++++++++++++++++++++++++++
 docs/reference/index.rst     |  1 +
 4 files changed, 49 insertions(+), 11 deletions(-)
 create mode 100644 docs/reference/ImageFile.rst

diff --git a/PIL/ImageFile.py b/PIL/ImageFile.py
index c86f0a177..70762b4b0 100644
--- a/PIL/ImageFile.py
+++ b/PIL/ImageFile.py
@@ -137,7 +137,7 @@ class ImageFile(Image.Image):
         readonly = 0
 
         if self.filename and len(self.tile) == 1 and not hasattr(sys, 'pypy_version_info'):
-            # As of pypy 2.1.0, memory mapping was failing here. 
+            # As of pypy 2.1.0, memory mapping was failing here.
             # try memory mapping
             d, e, o, a = self.tile[0]
             if d == "raw" and a[0] == self.mode and a[0] in Image._MAPMODES:
@@ -299,6 +299,8 @@ class Parser:
     """
     Incremental image parser.  This class implements the standard
     feed/close consumer interface.
+
+    In Python 2.x, this is an old-style class.
     """
     incremental = None
     image = None
@@ -318,7 +320,7 @@ class Parser:
         """
         (Consumer) Feed data to the parser.
 
-        :param data" A string buffer.
+        :param data: A string buffer.
         :exception IOError: If the parser failed to parse the image file.
         """
         # collect data
@@ -404,7 +406,9 @@ class Parser:
         (Consumer) Close the stream.
 
         :returns: An image object.
-        :exception IOError: If the parser failed to parse the image file.
+        :exception IOError: If the parser failed to parse the image file either
+                            because it cannot be identified or cannot be
+                            decoded.
         """
         # finish decoding
         if self.decoder:
diff --git a/docs/PIL.rst b/docs/PIL.rst
index 32e9fe4ea..2665ce9c4 100644
--- a/docs/PIL.rst
+++ b/docs/PIL.rst
@@ -76,14 +76,6 @@ can be found here.
     :undoc-members:
     :show-inheritance:
 
-:mod:`ImageFile` Module
------------------------
-
-.. automodule:: PIL.ImageFile
-    :members:
-    :undoc-members:
-    :show-inheritance:
-
 :mod:`ImageFileIO` Module
 -------------------------
 
diff --git a/docs/reference/ImageFile.rst b/docs/reference/ImageFile.rst
new file mode 100644
index 000000000..57476780d
--- /dev/null
+++ b/docs/reference/ImageFile.rst
@@ -0,0 +1,41 @@
+.. py:module:: PIL.ImageFile
+.. py:currentmodule:: PIL.ImageFile
+
+:mod:`ImageFile` Module
+=======================
+
+The :py:mod:`ImageFile` module provides support functions for the image open
+and save functions.
+
+In addition, it provides a :py:class:`Parser` class which can be used to decode
+an image piece by piece (e.g. while receiving it over a network connection).
+This class implements the same consumer interface as the standard **sgmllib**
+and **xmllib** modules.
+
+Example: Parse an image
+-----------------------
+
+.. code-block:: python
+
+    from PIL import ImageFile
+
+    fp = open("lena.pgm", "rb")
+
+    p = ImageFile.Parser()
+
+    while 1:
+        s = fp.read(1024)
+        if not s:
+            break
+        p.feed(s)
+
+    im = p.close()
+
+    im.save("copy.jpg")
+
+
+:py:class:`~PIL.ImageFile.Parser`
+---------------------------------
+
+.. autoclass:: PIL.ImageFile.Parser()
+    :members:
diff --git a/docs/reference/index.rst b/docs/reference/index.rst
index 8198fdcbc..0ef01aa56 100644
--- a/docs/reference/index.rst
+++ b/docs/reference/index.rst
@@ -9,4 +9,5 @@ Reference
    ImageColor
    ImageDraw
    ImageEnhance
+   ImageFile
    ../PIL