documentation

lib/generators/kaminari/views_generator.rb

@@ -5,7 +5,7 @@ module Kaminari
 
       class_option :template_engine, :type => :string, :aliases => '-e', :desc => 'Template engine for the views. Available options are "erb" and "haml".'
 
-      def self.banner
+      def self.banner #:nodoc:
         <<-BANNER.chomp
 rails g kaminari:views THEME [options]
 
@@ -21,7 +21,7 @@ BANNER
       end
 
       desc ''
-      def copy_views
+      def copy_views #:nodoc:
         Dir.glob(filename_pattern).map {|f| File.basename f}.each do |f|
           copy_file File.join([template_name.presence, f].compact), "app/views/kaminari/#{f}"
         end

lib/kaminari/engine.rb

@@ -1,4 +1,4 @@
-module Kaminari
-  class Engine < ::Rails::Engine
+module Kaminari #:nodoc:
+  class Engine < ::Rails::Engine #:nodoc:
   end
 end

lib/kaminari/helpers.rb

@@ -5,12 +5,12 @@ module Kaminari
     class PaginationRenderer
       attr_reader :options
 
-      def initialize(template, options)
+      def initialize(template, options) #:nodoc:
         @template, @options = template, options
         @left, @window, @right = (options[:left] || options[:outer_window] || 1), (options[:window] || options[:inner_window] || 4), (options[:right] || options[:outer_window] || 1)
       end
 
-      def tagify_links
+      def tagify_links #:nodoc:
         num_pages, current_page, left, window, right = @options[:num_pages], @options[:current_page], @left, @window, @right
         return [] if num_pages <= 1
 
@@ -35,15 +35,15 @@ module Kaminari
         tags << (num_pages > current_page ? NextLink.new(self) : NextSpan.new(self))
       end
 
-      def context
+      def context #:nodoc:
         @template.instance_variable_get('@lookup_context')
       end
 
-      def resolver
+      def resolver #:nodoc:
         context.instance_variable_get('@view_paths').first
       end
 
-      def to_s
+      def to_s #:nodoc:
         suppress_logging_render_partial do
           clear_content_for :kaminari_paginator_tags
           @template.content_for :kaminari_paginator_tags, tagify_links.join.html_safe
@@ -82,6 +82,19 @@ module Kaminari
       end
     end
 
+    # = Helpers
+    #
+    # A helper that renders the pagination links.
+    #
+    #   <%= paginate @articles %>
+    #
+    # ==== Options
+    # * <tt>:window</tt> - The "inner window" size (2 by default).
+    # * <tt>:outer_window</tt> - The "outer window" size (1 by default).
+    # * <tt>:left</tt> - The "left outer window" size (1 by default).
+    # * <tt>:right</tt> - The "right outer window" size (1 by default).
+    # * <tt>:remote</tt> - Ajax? (false by default)
+    # * <tt>:ANY_OTHER_VALUES</tt> - Any other hash key & values would be directly passed into each tag as :locals value.
     def paginate(scope, options = {}, &block)
       PaginationRenderer.new self, options.reverse_merge(:current_page => scope.current_page, :num_pages => scope.num_pages, :per_page => scope.limit_value, :remote => false)
     end

lib/kaminari/railtie.rb

@@ -5,7 +5,7 @@ require File.join(File.dirname(__FILE__), 'active_record')
 require File.join(File.dirname(__FILE__), 'helpers')
 
 module Kaminari
-  class Railtie < ::Rails::Railtie
+  class Railtie < ::Rails::Railtie #:nodoc:
     initializer 'paginatablize' do |app|
       ::ActiveRecord::Base.send :include, Kaminari::ActiveRecord
       ::ActionView::Base.send :include, Kaminari::Helpers

lib/kaminari/tags.rb

@@ -1,15 +1,31 @@
 module Kaminari
   module Helpers
+    # A tag stands for an HTML tag inside the paginator.
+    # Basically, a tag has its own partial template file, so every tag can be
+    # rendered into String using its partial template.
+    #
+    # The template file should be placed in your app/views/kaminari/ directory
+    # with underscored class name (besides the "Tag" class. Tag is an abstract
+    # class, so _tag parital is not needed).
+    #   e.g.)  PrevLink  ->  app/views/kaminari/_prev_link.html.erb
+    #
+    # If the template file does not exist, it falls back to ancestor classes.
+    #   e.g.)  FirstPageLink  ->  app/views/kaminari/_first_page_link.html.erb
+    #                         ->  app/views/kaminari/_page_link.html.erb
+    #
+    # When no template were found in your app, finally the engine's pre insatalled
+    # template will be used.
+    #   e.g.)  Paginator  ->  $GEM_HOME/kaminari-x.x.x/app/views/kaminari/_paginator.html.erb
     class Tag
-      def self.template_filename
+      def self.template_filename #:nodoc:
         name.demodulize.underscore
       end
 
-      def initialize(renderer, options = {})
+      def initialize(renderer, options = {}) #:nodoc:
         @renderer, @options = renderer, renderer.options.merge(options)
       end
 
-      def to_s(locals = {})
+      def to_s(locals = {}) #:nodoc:
         @renderer.render :partial => find_template, :locals => @options.merge(locals)
       end
 
@@ -44,45 +60,55 @@ module Kaminari
       end
     end
 
+    # "Previous" without link
     class PrevSpan < Tag
     end
 
+    # "Previous" with link
     class PrevLink < Tag
-      def to_s
+      def to_s #:nodoc:
         super :prev_url => page_url_for(@options[:current_page] - 1)
       end
     end
 
+    # "Next" without link
     class NextSpan < Tag
     end
 
+    # "Next" with link
     class NextLink < Tag
-      def to_s
+      def to_s #:nodoc:
         super :next_url => page_url_for(@options[:current_page] + 1)
       end
     end
 
+    # A link showing page number
     class PageLink < Tag
-      def to_s
+      def to_s #:nodoc:
         super :page_url => page_url_for(@options[:page])
       end
     end
 
+    # A non-link tag showing the current page number
     class CurrentPage < Tag
-      def to_s
+      def to_s #:nodoc:
         super :page_url => page_url_for(@options[:page])
       end
     end
 
+    # A link with page number that appears at the leftmost
     class FirstPageLink < PageLink
     end
 
+    # A link with page number that appears at the rightmost
     class LastPageLink < PageLink
     end
 
+    # A non-link tag that stands for skipped pages...
     class TruncatedSpan < Tag
     end
 
+    # The container tag
     class Paginator < Tag
     end
   end