Add documentation for the extending method in ActiveRecord:QueryMethods

1 files changed, 36 insertions, 0 deletions

diff --git a/activerecord/lib/active_record/relation/query_methods.rb b/activerecord/lib/active_record/relation/query_methods.rb
index 7eda9ad8e8..8dc59583c1 100644
--- a/activerecord/lib/active_record/relation/query_methods.rb
+++ b/activerecord/lib/active_record/relation/query_methods.rb
@@ -147,6 +147,42 @@ module ActiveRecord
       relation
     end
 
+    # Used to extend a scope with additional methods, either through
+    # a module or through a block provided. 
+    # 
+    # The object returned is a relation, which can be further extended.
+    #
+    # === Using a module
+    #
+    #   module Pagination
+    #     def page(number)
+    #       # pagination code goes here
+    #     end
+    #   end
+    #
+    #   scope = Model.scoped.extending(Pagination)
+    #   scope.page(params[:page])
+    #
+    # This can also take a list of modules also:
+    #
+    #   scope = Model.scoped.extending(Pagination, SomethingElse)
+    #
+    # === Using a block
+    #
+    #   scope = Model.scoped.extending do
+    #     def page(number)
+    #       # pagination code goes here 
+    #     end
+    #   end
+    #   scope.page(params[:page])
+    #
+    # You can also use a block and a module list:
+    #
+    #   scope = Model.scoped.extending(Pagination) do
+    #     def per_page(number)
+    #       # pagination code goes here 
+    #     end
+    #   end
     def extending(*modules)
       modules << Module.new(&Proc.new) if block_given?