add rdoc comments.

Author: daixque

lib/bulker.rb

@@ -1,3 +1,14 @@
 require 'bulker/buffer'
 require 'bulker/pager'
-require 'bulker/criteria'
+require 'bulker/criteria'
+
+# *bulker* provides Bulker::Pager and Bulker::Buffer.  
+#
+# Bulker::Pager gives you paging functionality to split large number of data to devided segments.
+# When 1000,000 records in your database, and you're going to do some process for each record,
+# Bulker::Pager will help you.
+# It can handle large data very easily such like array with Bulker::Pager#each method.
+#
+# Bulker::Buffer provides simple buffer that enables implimenting bulk insert or bulk upload behavior.
+module Bulker
+end

lib/bulker/buffer.rb

@@ -1,16 +1,31 @@
 module Bulker
+  # Bulker::Buffer provides buffer pool and bulk execution functionality.
+  #
+  #   result = []
+  #   buffer = Bulker::Buffer.new(4) do |ary|
+  #     result << ary # when buffer filled
+  #   end
+  #   (1..10).each do |i|
+  #     buffer << i
+  #   end
+  #   buffer.flush
+  #   result #=> [[1, 2, 3, 4], [5, 6, 7, 8], [9, 10]]
   class Buffer
+    # +size+ specify size of buffer.  
+    # +block+ specify callback on filled buffer.
     def initialize(size, &block)
       @size = size
       @buffer = []
       @on_buffered = block
     end
 
+    # add +obj+ into buffer
     def << (obj)
       @buffer << obj
       flush if @buffer.size == @size
     end
 
+    # do bulk execution and clear buffer.
     def flush
       @on_buffered.call(@buffer)
       @buffer = []

lib/bulker/criteria.rb

@@ -1,6 +1,20 @@
 module Bulker
+  # Bulker::Criteria provides interface for Bulker::Pager.
+  #
+  #  data = (1..20).to_a
+  #  criteria = Bulker::Criteria.new data
+  #  criteria.define_each lambda { |values, offset, limit, block|
+  #    values[offset..(offset + limit - 1)].each do |v|
+  #      block.call(v)
+  #    end
+  #  }
+  #  Bulker::Pager.each(criteria, 10) do |v|
+  #    #  do some process
+  #  end
   class Criteria
+    
     class << self
+      # create criteria from +ary+
       def from_array(ary)
         criteria = Criteria.new ary
         criteria.define_each lambda { |values, offset, limit, block|
@@ -13,31 +27,40 @@ def from_array(ary)
 
     attr_accessor :values
 
+    # create criteria with +values+.  
+    # defaults:  
+    # - +offset+ : 0
+    # - +limit+ : 10
     def initialize(values)
       @values = values
       @offset = 0
       @limit = 10
     end
 
+    # set +offset+ to specify offset from head of data.
     def offset(offset)
       @offset = offset
       self
     end
 
+    # set +limit+ to specify numbers to fetch data.
     def limit(limit)
       @limit = limit
       self
     end
 
+    # get size of +values+.
     def count
       @values.size
     end
 
+    # set implementation of +each+ by lambda.
     def define_each(each_proc)
       @each_proc = each_proc
       self
     end
 
+    # do +block+ for each data
     def each(&block)
       @each_proc.call(values, @offset, @limit, block)
     end

lib/bulker/pager.rb

@@ -1,18 +1,32 @@
 module Bulker
+  # Bulker::Pager provides paging functionality to split large number of data to devided segments.
+  # It can handle large data very easily such like array with each method.
+  #
+  # Bulker::Pager is especially designed for ActiveRecord.
+  #
+  #  class Item < ActiveRecord::Base; end
+  #  Bulker::Pager.each(Item.where(:status => "selling"), 100) do
+  #    # do some process for each item
+  #  end
+  #
+  # For other data source, Bulker::Criteria provides interface for Bulker::Pager.
   class Pager
     class << self
+      # access to every +cursor+ data with fetch limitation +limit+.
       def each(cursor, limit, &block)
         pager = Pager.new cursor, limit
         pager.each { |page| block.call(page) }
       end
     end
 
+    # create pager from +cursor+ data and limitaion +limit+
     def initialize(cursor, limit)
       raise RangeError.new("limit must be positive number, but #{limit}") if limit <= 0
       @cursor = cursor
       @limit = limit
     end
 
+    # access to every data.
     def each(&block)
       size = @cursor.count
       pages = size / @limit + (size % @limit == 0 ? 0 : 1)