From cf7b72f9b9159dd919110ea662fb696d6c560331 Mon Sep 17 00:00:00 2001
From: Stephen Johnson <steve@steveasleep.com>
Date: Sat, 12 Oct 2013 17:22:02 -0700
Subject: [PATCH] Fully document PIL.ImageGrab

---
 PIL/ImageGrab.py             | 51 ++++++++++++++++++------------------
 docs/reference/ImageGrab.rst | 15 +++++++++++
 docs/reference/index.rst     |  1 +
 3 files changed, 42 insertions(+), 25 deletions(-)
 create mode 100644 docs/reference/ImageGrab.rst

diff --git a/PIL/ImageGrab.py b/PIL/ImageGrab.py
index 59cc04706..52668ab04 100644
--- a/PIL/ImageGrab.py
+++ b/PIL/ImageGrab.py
@@ -17,33 +17,31 @@
 
 from PIL import Image
 
-##
-# (New in 1.1.3)  The <b>ImageGrab</b> module can be used to copy
-# the contents of the screen to a PIL image memory.
-# <p>
-# The current version works on Windows only.</p>
-#
-# @since 1.1.3
-##
 
 try:
     # built-in driver (1.1.3 and later)
     grabber = Image.core.grabscreen
 except AttributeError:
-    # stand-alone driver (pil plus)
-    import _grabscreen
-    grabber = _grabscreen.grab
+    try:
+        # stand-alone driver (pil plus)
+        import _grabscreen
+        grabber = _grabscreen.grab
+    except ImportError:
+        # allow the module to be imported by autodoc
+        grabber = None
 
-##
-# (New in 1.1.3) Take a snapshot of the screen.  The pixels inside the
-# bounding box are returned as an "RGB" image.  If the bounding box is
-# omitted, the entire screen is copied.
-#
-# @param bbox What region to copy.  Default is the entire screen.
-# @return An image
-# @since 1.1.3
 
 def grab(bbox=None):
+    """
+    Take a snapshot of the screen. The pixels inside the bounding box are
+    returned as an "RGB" image. If the bounding box is omitted, the entire
+    screen is copied.
+
+    .. versionadded:: 1.1.3
+
+    :param bbox: What region to copy. Default is the entire screen.
+    :return: An image
+    """
     size, data = grabber()
     im = Image.frombytes(
         "RGB", size, data,
@@ -55,14 +53,17 @@ def grab(bbox=None):
     return im
 
 ##
-# (New in 1.1.4) Take a snapshot of the clipboard image, if any.
-#
-# @return An image, a list of filenames, or None if the clipboard does
-#     not contain image data or filenames.  Note that if a list is
-#     returned, the filenames may not represent image files.
-# @since 1.1.4
 
 def grabclipboard():
+    """
+    Take a snapshot of the clipboard image, if any.
+
+    .. versionadded:: 1.1.4
+
+    :return: An image, a list of filenames, or None if the clipboard does
+             not contain image data or filenames.  Note that if a list is
+             returned, the filenames may not represent image files.
+    """
     debug = 0 # temporary interface
     data = Image.core.grabclipboard(debug)
     if isinstance(data, bytes):
diff --git a/docs/reference/ImageGrab.rst b/docs/reference/ImageGrab.rst
new file mode 100644
index 000000000..28865ccc3
--- /dev/null
+++ b/docs/reference/ImageGrab.rst
@@ -0,0 +1,15 @@
+.. py:module:: PIL.ImageGrab
+.. py:currentmodule:: PIL.ImageGrab
+
+:mod:`ImageGrab` Module (Windows-only)
+======================================
+
+The :py:mod:`ImageGrab` module can be used to copy the contents of the screen
+or the clipboard to a PIL image memory.
+
+.. note:: The current version works on Windows only.
+
+.. versionadded:: 1.1.3
+
+.. autofunction:: PIL.ImageGrab.grab
+.. autofunction:: PIL.ImageGrab.grabclipboard
diff --git a/docs/reference/index.rst b/docs/reference/index.rst
index 5f8d6fac3..5bee86b49 100644
--- a/docs/reference/index.rst
+++ b/docs/reference/index.rst
@@ -12,4 +12,5 @@ Reference
    ImageFile
    ImageFilter
    ImageFont
+   ImageGrab
    ../PIL