0
@@ -18,31 +18,24 @@ module WillPaginate
0
 
0
     # = Paginating finders for ActiveRecord models
0
     # 
0
-    # WillPaginate doesn't really add extra methods to your ActiveRecord models
0
-    # (except +per_page+ unless it's already available). It simply intercepts
0
-    # the calls to paginating finders such as +paginate+, +paginate_by_user_id+
0
-    # (and so on) and translates them to ordinary finders: +find+,
0
-    # +find_by_user_id+, etc. It does so with some +method_missing+ magic, but
0
-    # you don't need to care for that. You simply use paginating finders same
0
-    # way you used ordinary ones. You only need to specify what page do you want:
0
+    # WillPaginate adds +paginate+ and +per_page+ methods to ActiveRecord::Base
0
+    # class methods and associations. It also hooks into +method_missing+ to
0
+    # intercept pagination calls to dynamic finders such as
0
+    # +paginate_by_user_id+ and translate them to ordinary finders
0
+    # (+find_all_by_user_id+ in this case).
0
+    # 
0
+    # In short, paginating finders are equivalent to ActiveRecord finders; the
0
+    # only difference is that we start with "paginate" instead of "find" and
0
+    # that <tt>:page</tt> is required parameter:
0
     #
0
-    #   @posts = Post.paginate :page => params[:page], :order => 'created_at DESC'
0
+    #   @posts = Post.paginate :all, :page => params[:page], :order => 'created_at DESC'
0
     # 
0
-    # In paginating finders, "all" is implicit. No sense in paginating a single
0
-    # record, right? So:
0
+    # In paginating finders, "all" is implicit. There is no sense in paginating
0
+    # a single record, right? So, you can drop the <tt>:all</tt> argument:
0
     # 
0
-    #   Post.paginate                  => Post.find :all
0
-    #   Post.paginate_all_by_something => Post.find_all_by_something
0
-    #   Post.paginate_by_something     => Post.find_all_by_something
0
-    #
0
-    # Don't forget to pass the +page+ parameter! Without it, paginating finders
0
-    # will raise an error.
0
-    #
0
-    # == Options for paginating finders
0
-    # * <tt>:page</tt> -- REQUIRED, but defaults to 1 if false or nil
0
-    # * <tt>:per_page</tt> -- defaults to <tt>CurrentModel.per_page</tt> (which is 30 if not overridden)
0
-    # * <tt>:total_entries</tt> -- use only if you manually count total entries
0
-    # * <tt>:count</tt> -- additional options that are passed on to +count+
0
+    #   Post.paginate(...)              =>  Post.find :all
0
+    #   Post.paginate_all_by_something  =>  Post.find_all_by_something
0
+    #   Post.paginate_by_something      =>  Post.find_all_by_something
0
     #
0
     # == The importance of the <tt>:order</tt> parameter
0
     #
0
@@ -53,6 +46,17 @@ module WillPaginate
0
     # for PostgreSQL.
0
     # 
0
     module ClassMethods
0
+      # This is the main paginating finder.
0
+      #
0
+      # == Special parameters for paginating finders
0
+      # * <tt>:page</tt> -- REQUIRED, but defaults to 1 if false or nil
0
+      # * <tt>:per_page</tt> -- defaults to <tt>CurrentModel.per_page</tt> (which is 30 if not overridden)
0
+      # * <tt>:total_entries</tt> -- use only if you manually count total entries
0
+      # * <tt>:count</tt> -- additional options that are passed on to +count+
0
+      # * <tt>:finder</tt> -- name of the ActiveRecord finder used (default: "find")
0
+      #
0
+      # All other options (+conditions+, +order+, ...) are forwarded to +find+
0
+      # and +count+ calls.
0
       def paginate(*args, &block)
0
         options = args.pop
0
         page, per_page, total_entries = wp_parse_options(options)
0
@@ -78,8 +82,9 @@ module WillPaginate
0
         end
0
       end
0
       
0
-      # This methods wraps +find_by_sql+ by simply adding LIMIT and OFFSET to your SQL string
0
-      # based on the params otherwise used by paginating finds: +page+ and +per_page+.
0
+      # Wraps +find_by_sql+ by simply adding LIMIT and OFFSET to your SQL string
0
+      # based on the params otherwise used by paginating finds: +page+ and
0
+      # +per_page+.
0
       #
0
       # Example:
0
       # 
0
@@ -109,7 +114,7 @@ module WillPaginate
0
         end
0
       end
0
 
0
-      def respond_to?(method, include_priv = false)
0
+      def respond_to?(method, include_priv = false) #:nodoc:
0
         case method.to_sym
0
         when :paginate, :paginate_by_sql
0
           true
0
@@ -120,7 +125,7 @@ module WillPaginate
0
 
0
     protected
0
       
0
-      def method_missing_with_paginate(method, *args, &block)
0
+      def method_missing_with_paginate(method, *args, &block) #:nodoc:
0
         # did somebody tried to paginate? if not, let them be
0
         unless method.to_s.index('paginate') == 0
0
           return method_missing_without_paginate(method, *args, &block) 
0
@@ -139,6 +144,8 @@ module WillPaginate
0
         paginate(*args, &block)
0
       end
0
 
0
+      # Does the not-so-trivial job of finding out the total number of entries
0
+      # in the database. It relies on the ActiveRecord +count+ method.
0
       def wp_count(options, args, finder)
0
         excludees = [:count, :order, :limit, :offset, :readonly]
0
         unless options[:select] and options[:select] =~ /^\s*DISTINCT\b/i
0
@@ -173,7 +180,7 @@ module WillPaginate
0
         count.respond_to?(:length) ? count.length : count
0
       end
0
 
0
-      def wp_parse_options(options)
0
+      def wp_parse_options(options) #:nodoc:
0
         raise ArgumentError, 'parameter hash expected' unless options.respond_to? :symbolize_keys
0
         options = options.symbolize_keys
0
         raise ArgumentError, ':page parameter required' unless options.key? :page