AS guide: documents the file where each method is defined to allow cherry-picking (covers up to Hash)

1 files changed, 77 insertions, 1 deletions

diff --git a/railties/guides/source/active_support_core_extensions.textile b/railties/guides/source/active_support_core_extensions.textile
index 4292993c55..e4d0859933 100644
--- a/railties/guides/source/active_support_core_extensions.textile
+++ b/railties/guides/source/active_support_core_extensions.textile
@@ -675,6 +675,8 @@ The method +String#squish+ strips leading and trailing whitespace, and substitut
 
 There's also the destructive version +String#squish!+.
 
+NOTE: Defined in +active_support/core_ext/string/filters.rb+.
+
 h4. Key-based Interpolation
 
 In Ruby 1.9 the <tt>%</tt> string operator supports key-based interpolation, both formatted and unformatted:
@@ -687,6 +689,8 @@ In Ruby 1.9 the <tt>%</tt> string operator supports key-based interpolation, bot
 
 Active Support adds that functionality to <tt>%</tt> in previous versions of Ruby.
 
+NOTE: Defined in +active_support/core_ext/string/interpolation.rb+.
+
 h4. +starts_with?+ and +ends_width?+
 
 Active Support defines 3rd person aliases of +String#start_with?+ and +String#end_with?+:
@@ -696,6 +700,8 @@ Active Support defines 3rd person aliases of +String#start_with?+ and +String#en
 "foo".ends_with?("o")   # => true
 </ruby>
 
+NOTE: Defined in +active_support/core_ext/string/starts_ends_with.rb+.
+
 h4. Access
 
 h5. +at(position)+
@@ -709,6 +715,8 @@ Returns the character of the string at position +position+:
 "hello".at(10) # => ERROR if < 1.9, nil in 1.9
 </ruby>
 
+NOTE: Defined in +active_support/core_ext/string/access.rb+.
+
 h5. +from(position)+
 
 Returns the substring of the string starting at position +position+:
@@ -720,6 +728,8 @@ Returns the substring of the string starting at position +position+:
 "hello".from(10) # => "" if < 1.9, nil in 1.9
 </ruby>
 
+NOTE: Defined in +active_support/core_ext/string/access.rb+.
+
 h5. +to(position)+
 
 Returns the substring of the string up to position +position+:
@@ -731,14 +741,20 @@ Returns the substring of the string up to position +position+:
 "hello".to(10) # => "hello"
 </ruby>
 
+NOTE: Defined in +active_support/core_ext/string/access.rb+.
+
 h5. +first(limit = 1)+
 
 The call +str.first(n)+ is equivalent to +str.to(n-1)+ if +n+ > 0, and returns an empty string for +n+ == 0.
 
+NOTE: Defined in +active_support/core_ext/string/access.rb+.
+
 h5. +last(limit = 1)+
 
 The call +str.last(n)+ is equivalent to +str.from(-n)+ if +n+ > 0, and returns an empty string for +n+ == 0.
 
+NOTE: Defined in +active_support/core_ext/string/access.rb+.
+
 h3. Extensions to +Numeric+
 
 h4. Bytes
@@ -770,6 +786,8 @@ Singular forms are aliased so you are able to say:
 1.megabyte # => 1048576
 </ruby>
 
+NOTE: Defined in +active_support/core_ext/numeric/bytes.rb+.
+
 h3. Extensions to +Integer+
 
 h4. +multiple_of?+
@@ -783,6 +801,8 @@ The method +multiple_of?+ tests whether an integer is multiple of the argument:
 
 WARNING: Due the way it is implemented the argument must be nonzero, otherwise +ZeroDivisionError+ is raised.
 
+NOTE: Defined in +active_support/core_ext/integer/multiple.rb+.
+
 h4. +ordinalize+
 
 The method +ordinalize+ returns the ordinal string corresponding to the receiver integer:
@@ -794,6 +814,8 @@ The method +ordinalize+ returns the ordinal string corresponding to the receiver
 2009.ordinalize # => "2009th"
 </ruby>
 
+NOTE: Defined in +active_support/core_ext/integer/inflections.rb+.
+
 h3. Extensions to +Float+
 
 ...
@@ -818,6 +840,8 @@ end
 
 WARNING. Active Support redefines +group_by+ in Ruby 1.8.7 so that it still returns an ordered hash.
 
+NOTE: Defined in +active_support/core_ext/enumerable.rb+.
+
 h4. +sum+
 
 The method +sum+ adds the elements of an enumerable:
@@ -863,6 +887,8 @@ def observed_subclasses
 end
 </ruby>
 
+NOTE: Defined in +active_support/core_ext/enumerable.rb+.
+
 h4. +each_with_object+
 
 The +inject+ method offers iteration with an accumulator:
@@ -887,6 +913,8 @@ Active Support backports +each_with_object+ from Ruby 1.9, which addresses that
 
 WARNING. Note that the item of the collection and the accumulator come in different order in +inject+ and +each_with_object+.
 
+NOTE: Defined in +active_support/core_ext/enumerable.rb+.
+
 h4. +index_by+
 
 The method +index_by+ generates a hash with the elements of an enumerable indexed by some key.
@@ -900,6 +928,8 @@ invoices.index_by(&:number)
 
 WARNING. Keys should normally be unique. If the block returns the same value for different elements no collection is built for that key. The last item will win.
 
+NOTE: Defined in +active_support/core_ext/enumerable.rb+.
+
 h4. +many?+
 
 The method +many?+ is shorthand for +collection.size > 1+:
@@ -916,6 +946,8 @@ If an optional block is given +many?+ only takes into account those elements tha
 @see_more = videos.many? {|video| video.category == params[:category]}
 </ruby>
 
+NOTE: Defined in +active_support/core_ext/enumerable.rb+.
+
 h4. +exclude?+
 
 The predicate +exclude?+ tests whether a given object does *not* belong to the collection. It is the negation of the builtin +include?+:
@@ -924,6 +956,8 @@ The predicate +exclude?+ tests whether a given object does *not* belong to the c
 to_visit << node if visited.exclude?(node)
 </ruby>
 
+NOTE: Defined in +active_support/core_ext/enumerable.rb+.
+
 h3. Extensions to +Array+
 
 h4. Accessing
@@ -951,6 +985,8 @@ You can pick a random element with +rand+:
 shape_type = [Circle, Square, Triangle].rand
 </ruby>
 
+NOTE: Defined in +active_support/core_ext/array/access.rb+.
+
 h4. Options Extraction
 
 When the last argument in a method call is a hash, except perhaps for a +&block+ argument, Ruby allows you to omit the brackets:
@@ -977,6 +1013,8 @@ end
 
 This method receives an arbitrary number of action names, and an optional hash of options as last argument. With the call to +extract_options!+ you obtain the options hash and remove it from +actions+ in a simple and explicit way.
 
+NOTE: Defined in +active_support/core_ext/array/extract_options.rb+.
+
 h4. Conversions
 
 h5. +to_sentence+
@@ -1005,6 +1043,8 @@ The defaults for these options can be localised, their keys are:
 
 Options <tt>:connector</tt> and <tt>:skip_last_comma</tt> are deprecated.
 
+NOTE: Defined in +active_support/core_ext/array/conversions.rb+.
+
 h5. +to_formatted_s+
 
 The method +to_formatted_s+ acts like +to_s+ by default.
@@ -1019,6 +1059,8 @@ invoice.lines.to_formatted_s(:db) # => "23,567,556,12"
 
 Integers in the example above are supposed to come from the respective calls to +id+.
 
+NOTE: Defined in +active_support/core_ext/array/conversions.rb+.
+
 h5. +to_xml+
 
 The method +to_xml+ returns a string containing an XML representation of its receiver:
@@ -1118,6 +1160,8 @@ Contributor.all(:limit => 2, :order => 'rank ASC').to_xml(:skip_types => true)
 # </contributors>
 </ruby>
 
+NOTE: Defined in +active_support/core_ext/array/conversions.rb+.
+
 h4. Wrapping
 
 The class method +Array.wrap+ behaves like the function +Array()+ except that it does not try to call +to_a+ on its argument. That changes the behaviour for enumerables:
@@ -1130,6 +1174,8 @@ Array.wrap("foo\nbar")   # => ["foo\nbar"]
 Array("foo\nbar")        # => ["foo\n", "bar"], in Ruby 1.8
 </ruby>
 
+NOTE: Defined in +active_support/core_ext/array/wrap.rb+.
+
 h4. Grouping
 
 h5. +in_groups_of(number, fill_with = nil)+
@@ -1166,6 +1212,8 @@ And you can tell the method not to fill the last group passing +false+:
 
 As a consequence +false+ can't be a used as a padding value.
 
+NOTE: Defined in +active_support/core_ext/array/grouping.rb+.
+
 h5. +in_groups(number, fill_with = nil)+
 
 The method +in_groups+ splits an array into a certain number of groups. The method returns and array with the groups:
@@ -1202,6 +1250,8 @@ And you can tell the method not to fill the smaller groups passing +false+:
 
 As a consequence +false+ can't be a used as a padding value.
 
+NOTE: Defined in +active_support/core_ext/array/grouping.rb+.
+
 h5. +split(value = nil)+
 
 The method +split+ divides an array by a separator and returns the resulting chunks.
@@ -1220,7 +1270,9 @@ Otherwise, the value received as argument, which defaults to +nil+, is the separ
 # => [[0], [-5], [], ["foo", "bar"]]
 </ruby>
 
-NOTE: Observe in the previous example that consecutive separators result in empty arrays.
+TIP: Observe in the previous example that consecutive separators result in empty arrays.
+
+NOTE: Defined in +active_support/core_ext/array/grouping.rb+.
 
 h3. Extensions to +Hash+
 
@@ -1270,6 +1322,8 @@ By default the root node is "hash", but that's configurable via the <tt>:root</t
 
 The default XML builder is a fresh instance of <tt>Builder::XmlMarkup</tt>. You can configure your own builder with the <tt>:builder</tt> option. The method also accepts options like <tt>:dasherize</tt> and friends, they are forwarded to the builder.
 
+NOTE: Defined in +active_support/core_ext/hash/conversions.rb+.
+
 h4. Merging
 
 Ruby has a builtin method +Hash#merge+ that merges two hashes:
@@ -1303,12 +1357,16 @@ options.reverse_merge!(:length => 30, :omission => "...")
 
 WARNING. Take into account that +reverse_merge!+ may change the hash in the caller, which may or may not be a good idea.
 
+NOTE: Defined in +active_support/core_ext/hash/reverse_merge.rb+.
+
 h5. +reverse_update+
 
 The method +reverse_update+ is an alias for +reverse_merge!+, explained above.
 
 WARNING. Note that +reverse_update+ has no bang.
 
+NOTE: Defined in +active_support/core_ext/hash/reverse_merge.rb+.
+
 h5. +deep_merge+ and +deep_merge!+
 
 As you can see in the previous example if a key is found in both hashes the value in the one in the argument wins.
@@ -1322,6 +1380,8 @@ Active Support defines +Hash#deep_merge+. In a deep merge, if a key is found in
 
 The method +deep_merge!+ performs a deep merge in place.
 
+NOTE: Defined in +active_support/core_ext/hash/deep_merge.rb+.
+
 h4. Diffing
 
 The method +diff+ returns a hash that represents a diff of the receiver and the argument with the following logic:
@@ -1358,6 +1418,8 @@ hash.diff(hash2).diff(hash2) == hash
 
 Diffing hashes may be useful for error messages related to expected option hashes for example.
 
+NOTE: Defined in +active_support/core_ext/hash/diff.rb+.
+
 h4. Working with Keys
 
 h5. +except+ and +except!+
@@ -1384,6 +1446,8 @@ params[:account] = params[:account].except(:plan_id) unless admin?
 
 There's also the bang variant +except!+ that removes keys in the very receiver.
 
+NOTE: Defined in +active_support/core_ext/hash/except.rb+.
+
 h5. +stringify_keys+ and +stringify_keys!+
 
 The method +stringify_keys+ returns a hash that has a stringified version of the keys in the receiver. It does so by sending +to_s+ to them:
@@ -1414,6 +1478,8 @@ The second line can safely access the "type" key, and let the user to pass eithe
 
 There's also the bang variant +stringify_keys!+ that stringifies keys in the very receiver.
 
+NOTE: Defined in +active_support/core_ext/hash/keys.rb+.
+
 h5. +symbolize_keys+ and +symbolize_keys!+
 
 The method +symbolize_keys+ returns a hash that has a symbolized version of the keys in the receiver, where possible. It does so by sending +to_sym+ to them:
@@ -1446,10 +1512,14 @@ The second line can safely access the +:params+ key, and let the user to pass ei
 
 There's also the bang variant +symbolize_keys!+ that symbolizes keys in the very receiver.
 
+NOTE: Defined in +active_support/core_ext/hash/keys.rb+.
+
 h5. +to_options+ and +to_options!+
 
 The methods +to_options+ and +to_options!+ are respectively aliases of +symbolize_keys+ and +symbolize_keys!+.
 
+NOTE: Defined in +active_support/core_ext/hash/keys.rb+.
+
 h5. +assert_valid_keys+
 
 The method +assert_valid_keys+ receives an arbitrary number of arguments, and checks whether the receiver has any key outside that white list. If it does +ArgumentError+ is raised.
@@ -1481,6 +1551,8 @@ def create_has_many_reflection(association_id, options, &extension)
 end
 </ruby>
 
+NOTE: Defined in +active_support/core_ext/hash/keys.rb+.
+
 h4. Slicing
 
 Ruby has builtin support for taking slices out of strings and arrays. Active Support extends slicing to hashes:
@@ -1510,6 +1582,8 @@ rest = hash.slice!(:a) # => {:b => 2}
 hash                   # => {:a => 1}
 </ruby>
 
+NOTE: Defined in +active_support/core_ext/hash/slice.rb+.
+
 h4. Indifferent Access
 
 The method +with_indifferent_access+ returns an +ActiveSupport::HashWithIndifferentAccess+ out of its receiver:
@@ -1518,6 +1592,8 @@ The method +with_indifferent_access+ returns an +ActiveSupport::HashWithIndiffer
 {:a => 1}.with_indifferent_access["a"] # => 1
 </ruby>
 
+NOTE: Defined in +active_support/core_ext/hash/indifferent_access.rb+.
+
 h3. Extensions to +Regexp+
 
 h4. +number_of_captures+