Fully document PIL.ImageEnhance

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.
-
     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)

docs/PIL.rst

@@ -76,14 +76,6 @@ can be found here.
     :undoc-members:
     :show-inheritance:
 
-:mod:`ImageEnhance` Module
---------------------------
-
-.. automodule:: PIL.ImageEnhance
-    :members:
-    :undoc-members:
-    :show-inheritance:
-
 :mod:`ImageFile` Module
 -----------------------
 

docs/reference/ImageEnhance.rst

@@ -0,0 +1,41 @@
+.. py:module:: PIL.ImageEnhance
+.. py:currentmodule:: PIL.ImageEnhance
+
+:mod:`ImageEnhance` Module
+==========================
+
+The :py:mod:`ImageEnhance` module contains a number of classes that can be used
+for image enhancement.
+
+Example
+-------
+
+Vary the Sharpness of an Image
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+.. code-block:: python
+
+    import ImageEnhance
+
+    enhancer = ImageEnhance.Sharpness(image)
+
+    for i in range(8):
+        factor = i / 4.0
+        enhancer.enhance(factor).show("Sharpness %f" % factor)
+
+Also see the :file:`enhancer.py` demo program in the :file:`Scripts/`
+directory.
+
+Classes
+-------
+
+All enhancement classes implement a common interface, containing a single
+method:
+
+.. autoclass:: PIL.ImageEnhance._Enhance
+    :members:
+
+.. autoclass:: PIL.ImageEnhance.Color
+.. autoclass:: PIL.ImageEnhance.Contrast
+.. autoclass:: PIL.ImageEnhance.Brightness
+.. autoclass:: PIL.ImageEnhance.Sharpness

docs/reference/index.rst

@@ -8,4 +8,5 @@ Reference
    ImageChops
    ImageColor
    ImageDraw
+   ImageEnhance
    ../PIL