Change blocks() to block_windows() and add docstrings.

Closes #6.

rasterio/_io.pyx

@@ -276,7 +276,11 @@ cdef class RasterReader:
 
     @property
     def block_shapes(self):
-        """Returns an ordered list of block shapes for all bands."""
+        """Returns an ordered list of block shapes for all bands.
+        
+        Shapes are tuples and have the same ordering as the dataset's
+        shape: (count of image rows, count of image columns).
+        """
         cdef void *hband = NULL
         cdef int xsize, ysize
         if not self._block_shapes:
@@ -285,11 +289,22 @@ cdef class RasterReader:
             for i in range(self._count):
                 hband = _gdal.GDALGetRasterBand(self._hds, i+1)
                 _gdal.GDALGetBlockSize(hband, &xsize, &ysize)
-                # w, h = xsize, ysize
                 self._block_shapes.append((ysize, xsize))
         return self._block_shapes
 
-    def blocks(self, bdix):
+    def block_windows(self, bdix):
+        """Returns an iterator over a band's block windows.
+
+        The positional parameter `bidx` takes the index (starting at 1)
+        of the desired band. Block windows are tuples of four integers, 
+        (xoffset, yoffset, width, height), the first two are the offsets
+        in number of raster pixels from the upper left corner of the
+        dataset and the second two are the dimensions in number of pixels
+        of the raster block.
+
+        The primary use of this function is to obtain windows to pass to
+        read_band() for highly efficient access to raster block data.
+        """
         cdef int i, j
         h, w = self.block_shapes[bdix-1]
         d, m = divmod(self.width, w)

rasterio/tests/test_blocks.py

@@ -7,8 +7,11 @@ def test_blocks(self):
         with rasterio.open('rasterio/tests/data/RGB.byte.tif') as s:
             self.assertEqual(len(s.block_shapes), 3)
             self.assertEqual(s.block_shapes, [(3, 791), (3, 791), (3, 791)])
-            blocks = list(s.blocks(1))
-            self.assertEqual(blocks[0], (0, 0, 791, 3))
-            self.assertEqual(blocks[1], (0, 3, 791, 3))
-            self.assertEqual(blocks[~0], (0, 717, 791, 1))
+            windows = s.block_windows(1)
+            first = next(windows)
+            self.assertEqual(first, (0, 0, 791, 3))
+            second = next(windows)
+            self.assertEqual(second, (0, 3, 791, 3))
+            last = list(windows)[~0]
+            self.assertEqual(last, (0, 717, 791, 1))