Document ImageEnhance, ImageFile, ImageFilter, ImageFont, ImageGrab, ImageMath, and ImageOps

PIL/ImageEnhance.py

@@ -20,71 +20,68 @@
 
 from PIL import Image, ImageFilter, ImageStat
 
-class _Enhance:
 
-    ##
-    # Returns an enhanced image. The enhancement factor is a floating
-    # point value controlling the enhancement. Factor 1.0 always
-    # returns a copy of the original image, lower factors mean less
-    # colour (brightness, contrast, etc), and higher values more.
-    # There are no restrictions on this value.
-    #
-    # @param factor Enhancement factor.
-    # @return An enhanced image.
+class _Enhance:
 
     def enhance(self, factor):
+        """
+        Returns an enhanced image.
+
+        :param factor: A floating point value controlling the enhancement.
+                       Factor 1.0 always returns a copy of the original image,
+                       lower factors mean less color (brightness, contrast,
+                       etc), and higher values more. There are no restrictions
+                       on this value.
+        :rtype: :py:class:`~PIL.Image.Image`
+        """
         return Image.blend(self.degenerate, self.image, factor)
 
-##
-# Color enhancement object.
-# <p>
-# This class can be used to adjust the colour balance of an image, in
-# a manner similar to the controls on a colour TV set.  An enhancement
-# factor of 0.0 gives a black and white image, a factor of 1.0 gives
-# the original image.
 
 class Color(_Enhance):
-    "Adjust image colour balance"
+    """Adjust image color balance.
+
+    This class can be used to adjust the colour balance of an image, in
+    a manner similar to the controls on a colour TV set. An enhancement
+    factor of 0.0 gives a black and white image. A factor of 1.0 gives
+    the original image.
+    """
     def __init__(self, image):
         self.image = image
         self.degenerate = image.convert("L").convert(image.mode)
 
-##
-# Contrast enhancement object.
-# <p>
-# This class can be used to control the contrast of an image, similar
-# to the contrast control on a TV set.  An enhancement factor of 0.0
-# gives a solid grey image, factor 1.0 gives the original image.
 
 class Contrast(_Enhance):
-    "Adjust image contrast"
+    """Adjust image contrast.
+
+    This class can be used to control the contrast of an image, similar
+    to the contrast control on a TV set. An enhancement factor of 0.0
+    gives a solid grey image. A factor of 1.0 gives the original image.
+    """
     def __init__(self, image):
         self.image = image
         mean = int(ImageStat.Stat(image.convert("L")).mean[0] + 0.5)
         self.degenerate = Image.new("L", image.size, mean).convert(image.mode)
 
-##
-# Brightness enhancement object.
-# <p>
-# This class can be used to control the brighntess of an image.  An
-# enhancement factor of 0.0 gives a black image, factor 1.0 gives the
-# original image.
 
 class Brightness(_Enhance):
-    "Adjust image brightness"
+    """Adjust image brightness.
+
+    This class can be used to control the brighntess of an image.  An
+    enhancement factor of 0.0 gives a black image. A factor of 1.0 gives the
+    original image.
+    """
     def __init__(self, image):
         self.image = image
         self.degenerate = Image.new(image.mode, image.size, 0)
 
-##
-# Sharpness enhancement object.
-# <p>
-# This class can be used to adjust the sharpness of an image.  The
-# enhancement factor 0.0 gives a blurred image, 1.0 gives the original
-# image, and a factor of 2.0 gives a sharpened image.
 
 class Sharpness(_Enhance):
-    "Adjust image sharpness"
+    """Adjust image sharpness.
+
+    This class can be used to adjust the sharpness of an image. An
+    enhancement factor of 0.0 gives a blurred image, a factor of 1.0 gives the
+    original image, and a factor of 2.0 gives a sharpened image.
+    """
     def __init__(self, image):
         self.image = image
         self.degenerate = image.filter(ImageFilter.SMOOTH)

PIL/ImageFile.py

@@ -137,7 +137,7 @@ def load(self):
         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 @@ def feed(self, data):
         """
         (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 @@ def close(self):
         (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: