Document ActiveRecord::QueryMethods#select

activerecord/lib/active_record/relation/query_methods.rb

@@ -37,6 +37,35 @@ def preload(*args)
       relation
     end
 
+    # Works in two unique ways.
+    # 
+    # First: takes a block so it can be used just like Array#select.
+    #
+    #   Model.scoped.select { |m| m.field == value }
+    #
+    # This will build an array of objects from the database for the scope,
+    # converting them into an array and iterating through them using Array#select.
+    #
+    # Second: Modifies the SELECT statement for the query so that only certain
+    # fields are retreived:
+    #
+    #   >> Model.select(:field)
+    #   => [#<Model field:value>]
+    #
+    # Although in the above example it looks as though this method returns an
+    # array, in actual fact it returns a relation object and can have other query
+    # methods appended to it, such as the other methods in ActiveRecord::QueryMethods.
+    #
+    # This method will also take multiple parameters:
+    #
+    #   >> Model.select(:field, :other_field, :and_one_more)
+    #   => [#<Model field: "value", other_field: "value", :and_one_more: "value">]
+    #
+    # Any attributes that do not have fields retreived by a select
+    # will return `nil` when the getter method for that attribute is used:
+    #
+    #   >> Model.select(:field).first.other_field
+    #   => nil
     def select(value = Proc.new)
       if block_given?
         to_a.select {|*block_args| value.call(*block_args) }