From c3de637362e309c1f78424144ca7ef668efe909b Mon Sep 17 00:00:00 2001
From: Stephen Johnson <steve@steveasleep.com>
Date: Sun, 13 Oct 2013 22:30:00 -0700
Subject: [PATCH] Fully document PIL.PSDraw

---
 PIL/PSDraw.py             | 42 ++++++++++++++++++++++++++++++++++++---
 docs/PIL.rst              |  8 --------
 docs/reference/PSDraw.rst | 11 ++++++++++
 docs/reference/index.rst  |  1 +
 4 files changed, 51 insertions(+), 11 deletions(-)
 create mode 100644 docs/reference/PSDraw.rst

diff --git a/PIL/PSDraw.py b/PIL/PSDraw.py
index dd4acd8af..88593bb9d 100644
--- a/PIL/PSDraw.py
+++ b/PIL/PSDraw.py
@@ -23,6 +23,10 @@ from PIL import EpsImagePlugin
 # Simple Postscript graphics interface.
 
 class PSDraw:
+    """
+    Sets up printing to the given file. If **file** is omitted,
+    :py:attr:`sys.stdout` is assumed.
+    """
 
     def __init__(self, fp=None):
         if not fp:
@@ -31,7 +35,7 @@ class PSDraw:
         self.fp = fp
 
     def begin_document(self, id = None):
-        "Write Postscript DSC header"
+        """Set up printing of a document. (Write Postscript DSC header.)"""
         # FIXME: incomplete
         self.fp.write("%!PS-Adobe-3.0\n"
                       "save\n"
@@ -45,7 +49,7 @@ class PSDraw:
         self.isofont = {}
 
     def end_document(self):
-        "Write Postscript DSC footer"
+        """Ends printing. (Write Postscript DSC footer.)"""
         self.fp.write("%%EndDocument\n"
                       "restore showpage\n"
                       "%%End\n")
@@ -53,6 +57,12 @@ class PSDraw:
             self.fp.flush()
 
     def setfont(self, font, size):
+        """
+        Selects which font to use.
+
+        :param font: A Postscript font name
+        :param size: Size in points.
+        """
         if font not in self.isofont:
             # reencode font
             self.fp.write("/PSDraw-%s ISOLatin1Encoding /%s E\n" %\
@@ -62,23 +72,49 @@ class PSDraw:
         self.fp.write("/F0 %d /PSDraw-%s F\n" % (size, font))
 
     def setink(self, ink):
+        """
+        .. warning::
+
+            This has been in the PIL API for ages but was never implemented.
+        """
         print("*** NOT YET IMPLEMENTED ***")
 
     def line(self, xy0, xy1):
+        """
+        Draws a line between the two points. Coordinates are given in
+        Postscript point coordinates (72 points per inch, (0, 0) is the lower
+        left corner of the page).
+        """
         xy = xy0 + xy1
         self.fp.write("%d %d %d %d Vl\n" % xy)
 
     def rectangle(self, box):
+        """
+        Draws a rectangle.
+
+        :param box: A 4-tuple of integers whose order and function is currently
+                    undocumented.
+
+                    Hint: the tuple is passed into this format string:
+
+                    .. code-block:: python
+
+                        %d %d M %d %d 0 Vr\n
+        """
         self.fp.write("%d %d M %d %d 0 Vr\n" % box)
 
     def text(self, xy, text):
+        """
+        Draws text at the given position. You must use
+        :py:meth:`~PIL.PSDraw.PSDraw.setfont` before calling this method.
+        """
         text = "\\(".join(text.split("("))
         text = "\\)".join(text.split(")"))
         xy = xy + (text,)
         self.fp.write("%d %d M (%s) S\n" % xy)
 
     def image(self, box, im, dpi = None):
-        "Write an PIL image"
+        """Draw a PIL image, centered in the given box."""
         # default resolution depends on mode
         if not dpi:
             if im.mode == "1":
diff --git a/docs/PIL.rst b/docs/PIL.rst
index 99f029596..6726f661f 100644
--- a/docs/PIL.rst
+++ b/docs/PIL.rst
@@ -118,14 +118,6 @@ can be found here.
     :undoc-members:
     :show-inheritance:
 
-:mod:`PSDraw` Module
---------------------
-
-.. automodule:: PIL.PSDraw
-    :members:
-    :undoc-members:
-    :show-inheritance:
-
 :mod:`PaletteFile` Module
 -------------------------
 
diff --git a/docs/reference/PSDraw.rst b/docs/reference/PSDraw.rst
new file mode 100644
index 000000000..2b5b9b340
--- /dev/null
+++ b/docs/reference/PSDraw.rst
@@ -0,0 +1,11 @@
+.. py:module:: PIL.PSDraw
+.. py:currentmodule:: PIL.PSDraw
+
+:py:mod:`PSDraw` Module
+=======================
+
+The :py:mod:`PSDraw` module provides simple print support for Postscript
+printers. You can print text, graphics and images through this module.
+
+.. autoclass:: PIL.PSDraw.PSDraw
+    :members:
diff --git a/docs/reference/index.rst b/docs/reference/index.rst
index 2e148e65a..2d57e37be 100644
--- a/docs/reference/index.rst
+++ b/docs/reference/index.rst
@@ -22,4 +22,5 @@ Reference
    ImageStat
    ImageTk
    ImageWin
+   PSDraw
    ../PIL