convert comments into docstrings in autodoc files

src/PIL/BdfFontFile.py

@@ -17,13 +17,13 @@
 # See the README file for information on usage and redistribution.
 #
 
+"""
+Parse X Bitmap Distribution Format (BDF)
+"""
+
 
 from . import FontFile, Image
 
-# --------------------------------------------------------------------
-# parse X Bitmap Distribution Format (BDF)
-# --------------------------------------------------------------------
-
 bdf_slant = {
     "R": "Roman",
     "I": "Italic",
@@ -78,11 +78,9 @@ def bdf_char(f):
     return id, int(props["ENCODING"]), bbox, im
 
 
-##
-# Font file plugin for the X11 BDF format.
-
-
 class BdfFontFile(FontFile.FontFile):
+    """Font file plugin for the X11 BDF format."""
+
     def __init__(self, fp):
         super().__init__()
 

src/PIL/ContainerIO.py

@@ -14,14 +14,16 @@
 # See the README file for information on usage and redistribution.
 #
 
-##
-# A file object that provides read access to a part of an existing
-# file (for example a TAR file).
 
 import io
 
 
 class ContainerIO:
+    """
+    A file object that provides read access to a part of an existing
+    file (for example a TAR file).
+    """
+
     def __init__(self, file, offset, length):
         """
         Create file object.

src/PIL/FontFile.py

@@ -23,18 +23,15 @@ WIDTH = 800
 
 
 def puti16(fp, values):
-    # write network order (big-endian) 16-bit sequence
+    """write network order (big-endian) 16-bit sequence"""
     for v in values:
         if v < 0:
             v += 65536
         fp.write(_binary.o16be(v))
 
 
-##
-# Base class for raster font file handlers.
-
-
 class FontFile:
+    """Base class for raster font file handlers."""
 
     bitmap = None
 

src/PIL/GdImageFile.py

@@ -14,26 +14,30 @@
 #
 
 
-# NOTE: This format cannot be automatically recognized, so the
-# class is not registered for use with Image.open().  To open a
-# gd file, use the GdImageFile.open() function instead.
+"""
+.. note::
+    This format cannot be automatically recognized, so the
+    class is not registered for use with :py:func:`PIL.Image.open()`.  To open a
+    gd file, use the :py:func:`PIL.GdImageFile.open()` function instead.
 
-# THE GD FORMAT IS NOT DESIGNED FOR DATA INTERCHANGE.  This
-# implementation is provided for convenience and demonstrational
-# purposes only.
+.. warning::
+    THE GD FORMAT IS NOT DESIGNED FOR DATA INTERCHANGE.  This
+    implementation is provided for convenience and demonstrational
+    purposes only.
+"""
 
 
 from . import ImageFile, ImagePalette, UnidentifiedImageError
 from ._binary import i8, i16be as i16, i32be as i32
 
-##
-# Image plugin for the GD uncompressed format.  Note that this format
-# is not supported by the standard <b>Image.open</b> function.  To use
-# this plugin, you have to import the <b>GdImageFile</b> module and
-# use the <b>GdImageFile.open</b> function.
-
 
 class GdImageFile(ImageFile.ImageFile):
+    """
+    Image plugin for the GD uncompressed format.  Note that this format
+    is not supported by the standard :py:func:`PIL.Image.open()` function.  To use
+    this plugin, you have to import the :py:mod:`PIL.GdImageFile` module and
+    use the :py:func:`PIL.GdImageFile.open()` function.
+    """
 
     format = "GD"
     format_description = "GD uncompressed images"

src/PIL/GimpGradientFile.py

@@ -13,17 +13,19 @@
 # See the README file for information on usage and redistribution.
 #
 
+"""
+Stuff to translate curve segments to palette values (derived from
+the corresponding code in GIMP, written by Federico Mena Quintero.
+See the GIMP distribution for more information.)
+"""
+
+
 from math import log, pi, sin, sqrt
 
 from ._binary import o8
 
-# --------------------------------------------------------------------
-# Stuff to translate curve segments to palette values (derived from
-# the corresponding code in GIMP, written by Federico Mena Quintero.
-# See the GIMP distribution for more information.)
-#
-
 EPSILON = 1e-10
+""""""  # Enable auto-doc for data member
 
 
 def linear(middle, pos):
@@ -58,6 +60,7 @@ def sphere_decreasing(middle, pos):
 
 
 SEGMENTS = [linear, curved, sine, sphere_increasing, sphere_decreasing]
+""""""  # Enable auto-doc for data member
 
 
 class GradientFile:
@@ -98,11 +101,9 @@ class GradientFile:
         return b"".join(palette), "RGBA"
 
 
-##
-# File handler for GIMP's gradient format.
-
-
 class GimpGradientFile(GradientFile):
+    """File handler for GIMP's gradient format."""
+
     def __init__(self, fp):
 
         if fp.readline()[:13] != b"GIMP Gradient":

src/PIL/GimpPaletteFile.py

@@ -18,11 +18,9 @@ import re
 
 from ._binary import o8
 
-##
-# File handler for GIMP's palette format.
-
 
 class GimpPaletteFile:
+    """File handler for GIMP's palette format."""
 
     rawmode = "RGB"
 

src/PIL/ImageDraw2.py

@@ -16,6 +16,10 @@
 # See the README file for information on usage and redistribution.
 #
 
+
+"""WCK-style drawing interface operations"""
+
+
 from . import Image, ImageColor, ImageDraw, ImageFont, ImagePath
 
 

src/PIL/PaletteFile.py

@@ -15,11 +15,9 @@
 
 from ._binary import o8
 
-##
-# File handler for Teragon-style palette files.
-
 
 class PaletteFile:
+    """File handler for Teragon-style palette files."""
 
     rawmode = "RGB"
 

src/PIL/PcfFontFile.py

@@ -48,11 +48,8 @@ def sz(s, o):
     return s[o : s.index(b"\0", o)]
 
 
-##
-# Font file plugin for the X11 PCF format.
-
-
 class PcfFontFile(FontFile.FontFile):
+    """Font file plugin for the X11 PCF format."""
 
     name = "name"
 

src/PIL/TarIO.py

@@ -18,12 +18,10 @@ import io
 
 from . import ContainerIO
 
-##
-# A file object that provides read access to a given member of a TAR
-# file.
-
 
 class TarIO(ContainerIO.ContainerIO):
+    """A file object that provides read access to a given member of a TAR file."""
+
     def __init__(self, tarfile, file):
         """
         Create file object.

src/PIL/WalImageFile.py

@@ -12,13 +12,16 @@
 # See the README file for information on usage and redistribution.
 #
 
-# NOTE: This format cannot be automatically recognized, so the reader
-# is not registered for use with Image.open().  To open a WAL file, use
-# the WalImageFile.open() function instead.
+"""
+This reader is based on the specification available from:
+https://www.flipcode.com/archives/Quake_2_BSP_File_Format.shtml
+and has been tested with a few sample files found using google.
 
-# This reader is based on the specification available from:
-#    https://www.flipcode.com/archives/Quake_2_BSP_File_Format.shtml
-# and has been tested with a few sample files found using google.
+.. note::
+    This format cannot be automatically recognized, so the reader
+    is not registered for use with :py:func:`PIL.Image.open()`.
+    To open a WAL file, use the :py:func:`PIL.WalImageFile.open()` function instead.
+"""
 
 import builtins
 
@@ -31,7 +34,7 @@ def open(filename):
     Load texture from a Quake2 WAL texture file.
 
     By default, a Quake2 standard palette is attached to the texture.
-    To override the palette, use the <b>putpalette</b> method.
+    To override the palette, use the :py:func:`PIL.Image.Image.putpalette()` method.
 
     :param filename: WAL file name, or an opened file handle.
     :returns: An image instance.

src/PIL/_binary.py

@@ -11,6 +11,10 @@
 # See the README file for information on usage and redistribution.
 #
 
+
+"""Binary input/output support routines."""
+
+
 from struct import pack, unpack_from