From 428d47adfed8d6aa7b21aec2bf5ad890961c9de3 Mon Sep 17 00:00:00 2001 From: Yves Senn Date: Wed, 8 Jul 2015 12:16:16 +0200 Subject: applies new doc guidelines to Active Record. The focus of this change is to make the API more accessible. References to method and classes should be linked to make it easy to navigate around. This patch makes exzessiv use of `rdoc-ref:` to provide more readable docs. This makes it possible to document `ActiveRecord::Base#save` even though the method is within a separate module `ActiveRecord::Persistence`. The goal here is to bring the API closer to the actual code that you would write. This commit only deals with Active Record. The other gems will be updated accordingly but in different commits. The pass through Active Record is not completely finished yet. A follow up commit will change the spots I haven't yet had the time to update. /cc @fxn --- .../lib/active_record/relation/finder_methods.rb | 40 +++++++++++----------- 1 file changed, 20 insertions(+), 20 deletions(-) (limited to 'activerecord/lib/active_record/relation/finder_methods.rb') diff --git a/activerecord/lib/active_record/relation/finder_methods.rb b/activerecord/lib/active_record/relation/finder_methods.rb index 009b2bad57..435cef901b 100644 --- a/activerecord/lib/active_record/relation/finder_methods.rb +++ b/activerecord/lib/active_record/relation/finder_methods.rb @@ -17,7 +17,7 @@ module ActiveRecord # Person.where("administrator = 1").order("created_on DESC").find(1) # # NOTE: The returned records may not be in the same order as the ids you - # provide since database rows are unordered. You'd need to provide an explicit order + # provide since database rows are unordered. You'd need to provide an explicit QueryMethods#order # option if you want the results are sorted. # # ==== Find with lock @@ -34,7 +34,7 @@ module ActiveRecord # person.save! # end # - # ==== Variations of +find+ + # ==== Variations of #find # # Person.where(name: 'Spartacus', rating: 4) # # returns a chainable list (which can be empty). @@ -48,7 +48,7 @@ module ActiveRecord # Person.where(name: 'Spartacus', rating: 4).first_or_create # # returns the first item or creates it and returns it. # - # ==== Alternatives for +find+ + # ==== Alternatives for #find # # Person.where(name: 'Spartacus', rating: 4).exists?(conditions = :none) # # returns a boolean indicating if any record with the given conditions exist. @@ -80,8 +80,8 @@ module ActiveRecord nil end - # Like find_by, except that if no record is found, raises - # an ActiveRecord::RecordNotFound error. + # Like #find_by, except that if no record is found, raises + # an ActiveRecord::RecordNotFound error. def find_by!(arg, *args) where(arg, *args).take! rescue RangeError @@ -100,8 +100,8 @@ module ActiveRecord limit ? limit(limit).to_a : find_take end - # Same as +take+ but raises ActiveRecord::RecordNotFound if no record - # is found. Note that take! accepts no arguments. + # Same as #take but raises ActiveRecord::RecordNotFound if no record + # is found. Note that #take! accepts no arguments. def take! take or raise RecordNotFound.new("Couldn't find #{@klass.name} with [#{arel.where_sql(@klass.arel_engine)}]") end @@ -123,8 +123,8 @@ module ActiveRecord end end - # Same as +first+ but raises ActiveRecord::RecordNotFound if no record - # is found. Note that first! accepts no arguments. + # Same as #first but raises ActiveRecord::RecordNotFound if no record + # is found. Note that #first! accepts no arguments. def first! find_nth! 0 end @@ -156,8 +156,8 @@ module ActiveRecord end end - # Same as +last+ but raises ActiveRecord::RecordNotFound if no record - # is found. Note that last! accepts no arguments. + # Same as #last but raises ActiveRecord::RecordNotFound if no record + # is found. Note that #last! accepts no arguments. def last! last or raise RecordNotFound.new("Couldn't find #{@klass.name} with [#{arel.where_sql(@klass.arel_engine)}]") end @@ -172,7 +172,7 @@ module ActiveRecord find_nth(1, offset_index) end - # Same as +second+ but raises ActiveRecord::RecordNotFound if no record + # Same as #second but raises ActiveRecord::RecordNotFound if no record # is found. def second! find_nth! 1 @@ -188,7 +188,7 @@ module ActiveRecord find_nth(2, offset_index) end - # Same as +third+ but raises ActiveRecord::RecordNotFound if no record + # Same as #third but raises ActiveRecord::RecordNotFound if no record # is found. def third! find_nth! 2 @@ -204,7 +204,7 @@ module ActiveRecord find_nth(3, offset_index) end - # Same as +fourth+ but raises ActiveRecord::RecordNotFound if no record + # Same as #fourth but raises ActiveRecord::RecordNotFound if no record # is found. def fourth! find_nth! 3 @@ -220,7 +220,7 @@ module ActiveRecord find_nth(4, offset_index) end - # Same as +fifth+ but raises ActiveRecord::RecordNotFound if no record + # Same as #fifth but raises ActiveRecord::RecordNotFound if no record # is found. def fifth! find_nth! 4 @@ -236,14 +236,14 @@ module ActiveRecord find_nth(41, offset_index) end - # Same as +forty_two+ but raises ActiveRecord::RecordNotFound if no record + # Same as #forty_two but raises ActiveRecord::RecordNotFound if no record # is found. def forty_two! find_nth! 41 end - # Returns +true+ if a record exists in the table that matches the +id+ or - # conditions given, or +false+ otherwise. The argument can take six forms: + # Returns true if a record exists in the table that matches the +id+ or + # conditions given, or false otherwise. The argument can take six forms: # # * Integer - Finds the record with this primary key. # * String - Finds the record with a primary key corresponding to this @@ -256,7 +256,7 @@ module ActiveRecord # * No args - Returns +false+ if the table is empty, +true+ otherwise. # # For more information about specifying conditions as a hash or array, - # see the Conditions section in the introduction to ActiveRecord::Base. + # see the Conditions section in the introduction to ActiveRecord::Base. # # Note: You can't pass in a condition as a string (like name = # 'Jamie'), since it would be sanitized and then queried against @@ -298,7 +298,7 @@ module ActiveRecord end # This method is called whenever no records are found with either a single - # id or multiple ids and raises a +ActiveRecord::RecordNotFound+ exception. + # id or multiple ids and raises a ActiveRecord::RecordNotFound exception. # # The error message is different depending on whether a single id or # multiple ids are provided. If multiple ids are provided, then the number -- cgit v1.2.3