From 2a305949d756c054cee349c1ef3b39c6cf1496f8 Mon Sep 17 00:00:00 2001 From: Rick Olson Date: Tue, 27 Mar 2007 14:04:06 +0000 Subject: documentation project patches, closes #7342, #7319, #7316, #7190 [jeremymcanally] git-svn-id: http://svn-commit.rubyonrails.org/rails/trunk@6470 5ecf4fe2-1ee6-0310-87b1-e25e094e27de --- activerecord/lib/active_record/acts/list.rb | 9 +++++++++ activerecord/lib/active_record/acts/tree.rb | 7 +++++++ activerecord/lib/active_record/associations.rb | 9 ++++++++- activerecord/lib/active_record/base.rb | 3 +++ activerecord/lib/active_record/calculations.rb | 4 ++-- activerecord/lib/active_record/deprecated_finders.rb | 6 +++--- 6 files changed, 32 insertions(+), 6 deletions(-) (limited to 'activerecord/lib/active_record') diff --git a/activerecord/lib/active_record/acts/list.rb b/activerecord/lib/active_record/acts/list.rb index 87bb1280e1..cacf6a81f6 100644 --- a/activerecord/lib/active_record/acts/list.rb +++ b/activerecord/lib/active_record/acts/list.rb @@ -74,6 +74,7 @@ module ActiveRecord # lower in the list of all chapters. Likewise, chapter.first? would return true if that chapter is # the first in the list of all chapters. module InstanceMethods + # Insert the item at the given position (defaults to the top position of 1). def insert_at(position = 1) insert_at_position(position) end @@ -118,6 +119,7 @@ module ActiveRecord end end + # Removes the item from the list. def remove_from_list decrement_positions_on_lower_items if in_list? end @@ -162,6 +164,7 @@ module ActiveRecord ) end + # Test if this record is in a list def in_list? !send(position_column).nil? end @@ -178,21 +181,26 @@ module ActiveRecord # Overwrite this method to define the scope of the list changes def scope_condition() "1" end + # Returns the bottom position number in the list. + # bottom_position_in_list # => 2 def bottom_position_in_list(except = nil) item = bottom_item(except) item ? item.send(position_column) : 0 end + # Returns the bottom item def bottom_item(except = nil) conditions = scope_condition conditions = "#{conditions} AND #{self.class.primary_key} != #{except.id}" if except acts_as_list_class.find(:first, :conditions => conditions, :order => "#{position_column} DESC") end + # Forces item to assume the bottom position in the list. def assume_bottom_position update_attribute(position_column, bottom_position_in_list(self).to_i + 1) end + # Forces item to assume the top position in the list. def assume_top_position update_attribute(position_column, 1) end @@ -227,6 +235,7 @@ module ActiveRecord ) end + # Increments position (position_column) of all items in the list. def increment_positions_on_all_items acts_as_list_class.update_all( "#{position_column} = (#{position_column} + 1)", "#{scope_condition}" diff --git a/activerecord/lib/active_record/acts/tree.rb b/activerecord/lib/active_record/acts/tree.rb index 44432d4741..b92587e521 100644 --- a/activerecord/lib/active_record/acts/tree.rb +++ b/activerecord/lib/active_record/acts/tree.rb @@ -70,16 +70,23 @@ module ActiveRecord nodes end + # Returns the root node of the tree. def root node = self node = node.parent while node.parent node end + # Returns all siblings of the current node. + # + # subchild1.siblings # => [subchild2] def siblings self_and_siblings - [self] end + # Returns all siblings and a reference to the current node. + # + # subchild1.self_and_siblings # => [subchild1, subchild2] def self_and_siblings parent ? parent.children : self.class.roots end diff --git a/activerecord/lib/active_record/associations.rb b/activerecord/lib/active_record/associations.rb index c6eb4453ef..5393c3f91f 100755 --- a/activerecord/lib/active_record/associations.rb +++ b/activerecord/lib/active_record/associations.rb @@ -798,6 +798,7 @@ module ActiveRecord deprecated_association_comparison_method(reflection.name, reflection.class_name) end + # Create the callbacks to update counter cache if options[:counter_cache] cache_column = options[:counter_cache] == true ? "#{self.to_s.underscore.pluralize}_count" : @@ -935,6 +936,12 @@ module ActiveRecord end private + # Generate a join table name from two provided tables names. + # The order of names in join name is determined by lexical precedence. + # join_table_name("members", "clubs") + # => "clubs_members" + # join_table_name("members", "special_clubs") + # => "members_special_clubs" def join_table_name(first_table_name, second_table_name) if first_table_name < second_table_name join_table = "#{first_table_name}_#{second_table_name}" @@ -944,7 +951,7 @@ module ActiveRecord table_name_prefix + join_table + table_name_suffix end - + def association_accessor_methods(reflection, association_proxy_class) define_method(reflection.name) do |*params| force_reload = params.first unless params.empty? diff --git a/activerecord/lib/active_record/base.rb b/activerecord/lib/active_record/base.rb index c680d7e304..aa90e8bcc2 100755 --- a/activerecord/lib/active_record/base.rb +++ b/activerecord/lib/active_record/base.rb @@ -1229,6 +1229,9 @@ module ActiveRecord #:nodoc: # # It's even possible to use all the additional parameters to find. For example, the full interface for find_all_by_amount # is actually find_all_by_amount(amount, options). + # + # This also enables you to initialize a record if it is not found, such as find_or_initialize_by_amount(amount) + # or find_or_create_by_user_and_password(user, password). def method_missing(method_id, *arguments) if match = /^find_(all_by|by)_([_a-zA-Z]\w*)$/.match(method_id.to_s) finder, deprecated_finder = determine_finder(match), determine_deprecated_finder(match) diff --git a/activerecord/lib/active_record/calculations.rb b/activerecord/lib/active_record/calculations.rb index 54bedf1294..a54ef468e0 100644 --- a/activerecord/lib/active_record/calculations.rb +++ b/activerecord/lib/active_record/calculations.rb @@ -246,8 +246,8 @@ module ActiveRecord options.assert_valid_keys(CALCULATIONS_OPTIONS) end - # converts a given key to the value that the database adapter returns as - # + # Converts a given key to the value that the database adapter returns as + # as a usable column name. # users.id #=> users_id # sum(id) #=> sum_id # count(distinct users.id) #=> count_distinct_users_id diff --git a/activerecord/lib/active_record/deprecated_finders.rb b/activerecord/lib/active_record/deprecated_finders.rb index 4ab2dde5f0..d4dcaa3fa0 100644 --- a/activerecord/lib/active_record/deprecated_finders.rb +++ b/activerecord/lib/active_record/deprecated_finders.rb @@ -1,7 +1,7 @@ module ActiveRecord class Base class << self - # This method is deprecated in favor of find with the :conditions option. + # DEPRECATION NOTICE: This method is deprecated in favor of find with the :conditions option. # # Works like find, but the record matching +id+ must also meet the +conditions+. # +RecordNotFound+ is raised if no record can be found matching the +id+ or meeting the condition. @@ -12,7 +12,7 @@ module ActiveRecord end deprecate :find_on_conditions => "use find(ids, :conditions => conditions)" - # This method is deprecated in favor of find(:first, options). + # DEPRECATION NOTICE: This method is deprecated in favor of find(:first, options). # # Returns the object for the first record responding to the conditions in +conditions+, # such as "group = 'master'". If more than one record is returned from the query, it's the first that'll @@ -24,7 +24,7 @@ module ActiveRecord end deprecate :find_first => "use find(:first, ...)" - # This method is deprecated in favor of find(:all, options). + # DEPRECATION NOTICE: This method is deprecated in favor of find(:all, options). # # Returns an array of all the objects that could be instantiated from the associated # table in the database. The +conditions+ can be used to narrow the selection of objects (WHERE-part), -- cgit v1.2.3