From a8d13da119050c69c6dc48c8654a4c76811da506 Mon Sep 17 00:00:00 2001
From: Willem van Bergen <willem@vanbergen.org>
Date: Sun, 31 Oct 2010 21:07:50 +0100
Subject: [PATCH] Added RDoc to adam7 interlacing module.

---
 lib/chunky_png/canvas/adam7_interlacing.rb | 28 +++++++++++++++++++---
 1 file changed, 25 insertions(+), 3 deletions(-)

diff --git a/lib/chunky_png/canvas/adam7_interlacing.rb b/lib/chunky_png/canvas/adam7_interlacing.rb
index 1eed6145..7ad57041 100644
--- a/lib/chunky_png/canvas/adam7_interlacing.rb
+++ b/lib/chunky_png/canvas/adam7_interlacing.rb
@@ -1,25 +1,44 @@
 module ChunkyPNG
   class Canvas
     
-    # Methods for decoding and encoding adam7 interlacing
+    # Methods for decoding and encoding Adam7 interlacing.
     #
+    # Adam7 interlacing extractg 7 pass images out of a single image, that can be encoded to a 
+    # stream separately so the image can be built up progressively. The module is included into
+    # ChunkyPNG canvas and is used to extract the pass images from the original image, or to
+    # reconstruct an original image from separate pass images.
     module Adam7Interlacing
       
+      # Returns an array with the x-shift, x-offset, y-shift and y-offset for the requested pass.
+      # @param [Integer] pass The pass number, should be in 0..6.
       def adam7_multiplier_offset(pass)
         [3 - (pass >> 1), (pass & 1 == 0) ? 0 : 8 >> ((pass + 1) >> 1),
          pass == 0 ? 3 : 3 - ((pass - 1) >> 1), (pass == 0 || pass & 1 == 1) ? 0 : 8 >> (pass >> 1)]
       end
 
+      # Returns the pixel dimensions of the requested pass.
+      # @param [Integer] pass The pass number, should be in 0..6.
+      # @param [Integer] original_width The width of the original image.
+      # @param [Integer] original_height The height of the original image.
       def adam7_pass_size(pass, original_width, original_height)
         x_shift, x_offset, y_shift, y_offset = adam7_multiplier_offset(pass)
         [ (original_width  - x_offset + (1 << x_shift) - 1) >> x_shift,
           (original_height - y_offset + (1 << y_shift) - 1) >> y_shift]
       end
-
+      
+      # Returns an array of the dimension of all the pass images.
+      # @param [Integer] original_width The width of the original image.
+      # @param [Integer] original_height The height of the original image.
+      # @return [Array<Array<Integer>>] Returns an array with 7 pairs of dimensions.
+      # @see #adam7_pass_size
       def adam7_pass_sizes(original_width, original_height)
         (0...7).map { |pass| adam7_pass_size(pass, original_width, original_height) }
       end
 
+      # Merges a pass image into a total image that is being constructed.
+      # @param [Integer] pass The pass number, should be in 0..6.
+      # @param [ChunkyPNG::Canvas] canvas The image that is being constructed.
+      # @param [ChunkyPNG::Canvas] subcanvas The pass image that should be merged
       def adam7_merge_pass(pass, canvas, subcanvas)
         x_shift, x_offset, y_shift, y_offset = adam7_multiplier_offset(pass)
         for y in 0...subcanvas.height do
@@ -29,9 +48,12 @@ def adam7_merge_pass(pass, canvas, subcanvas)
             canvas[new_x, new_y] = subcanvas[x, y]
           end
         end
-        canvas
       end
       
+      # Extracts a pass from a complete image
+      # @param [Integer] pass The pass number, should be in 0..6.
+      # @param [ChunkyPNG::Canvas] canvas The image that is being deconstructed.
+      # @return [ChunkyPNG::Canvas] The extracted pass image.
       def adam7_extract_pass(pass, canvas)
         x_shift, x_offset, y_shift, y_offset = adam7_multiplier_offset(pass)
         sm_pixels = []