diff options
Diffstat (limited to 'activerecord')
37 files changed, 231 insertions, 106 deletions
diff --git a/activerecord/lib/active_record/aggregations.rb b/activerecord/lib/active_record/aggregations.rb index 45aaea062d..51ffc7542c 100644 --- a/activerecord/lib/active_record/aggregations.rb +++ b/activerecord/lib/active_record/aggregations.rb @@ -1,4 +1,5 @@ module ActiveRecord + # = Active Record Aggregations module Aggregations # :nodoc: extend ActiveSupport::Concern diff --git a/activerecord/lib/active_record/associations.rb b/activerecord/lib/active_record/associations.rb index 567218e6fb..399c1bf58a 100644 --- a/activerecord/lib/active_record/associations.rb +++ b/activerecord/lib/active_record/associations.rb @@ -88,8 +88,8 @@ module ActiveRecord end end - # This error is raised when trying to destroy a parent instance in a N:1, 1:1 assosications - # (has_many, has_one) when there is at least 1 child assosociated instance. + # This error is raised when trying to destroy a parent instance in N:1 or 1:1 associations + # (has_many, has_one) when there is at least 1 child associated instance. # ex: if @project.tasks.size > 0, DeleteRestrictionError will be raised when trying to destroy @project class DeleteRestrictionError < ActiveRecordError #:nodoc: def initialize(reflection) @@ -890,7 +890,7 @@ module ActiveRecord # [:inverse_of] # Specifies the name of the <tt>belongs_to</tt> association on the associated object that is the inverse of this <tt>has_many</tt> # association. Does not work in combination with <tt>:through</tt> or <tt>:as</tt> options. - # See ActiveRecord::Associations::ClassMethods's overview on Bi-directional assocations for more detail. + # See ActiveRecord::Associations::ClassMethods's overview on Bi-directional associations for more detail. # # Option examples: # has_many :comments, :order => "posted_on" @@ -1005,7 +1005,7 @@ module ActiveRecord # [:inverse_of] # Specifies the name of the <tt>belongs_to</tt> association on the associated object that is the inverse of this <tt>has_one</tt> # association. Does not work in combination with <tt>:through</tt> or <tt>:as</tt> options. - # See ActiveRecord::Associations::ClassMethods's overview on Bi-directional assocations for more detail. + # See ActiveRecord::Associations::ClassMethods's overview on Bi-directional associations for more detail. # # Option examples: # has_one :credit_card, :dependent => :destroy # destroys the associated credit card @@ -1110,7 +1110,7 @@ module ActiveRecord # [:inverse_of] # Specifies the name of the <tt>has_one</tt> or <tt>has_many</tt> association on the associated object that is the inverse of this <tt>belongs_to</tt> # association. Does not work in combination with the <tt>:polymorphic</tt> options. - # See ActiveRecord::Associations::ClassMethods's overview on Bi-directional assocations for more detail. + # See ActiveRecord::Associations::ClassMethods's overview on Bi-directional associations for more detail. # # Option examples: # belongs_to :firm, :foreign_key => "client_of" diff --git a/activerecord/lib/active_record/associations/association_collection.rb b/activerecord/lib/active_record/associations/association_collection.rb index bd67516518..f8d46bcb48 100644 --- a/activerecord/lib/active_record/associations/association_collection.rb +++ b/activerecord/lib/active_record/associations/association_collection.rb @@ -3,6 +3,8 @@ require 'active_support/core_ext/array/wrap' module ActiveRecord module Associations + # = Active Record Association Collection + # # AssociationCollection is an abstract class that provides common stuff to # ease the implementation of association proxies that represent # collections. See the class hierarchy in AssociationProxy. diff --git a/activerecord/lib/active_record/associations/association_proxy.rb b/activerecord/lib/active_record/associations/association_proxy.rb index e88618d278..f333f4d603 100644 --- a/activerecord/lib/active_record/associations/association_proxy.rb +++ b/activerecord/lib/active_record/associations/association_proxy.rb @@ -2,6 +2,8 @@ require 'active_support/core_ext/array/wrap' module ActiveRecord module Associations + # = Active Record Associations + # # This is the root class of all association proxies: # # AssociationProxy diff --git a/activerecord/lib/active_record/associations/belongs_to_association.rb b/activerecord/lib/active_record/associations/belongs_to_association.rb index d2f2267e5c..c2a6495db5 100644 --- a/activerecord/lib/active_record/associations/belongs_to_association.rb +++ b/activerecord/lib/active_record/associations/belongs_to_association.rb @@ -1,4 +1,5 @@ module ActiveRecord + # = Active Record Belongs To Associations module Associations class BelongsToAssociation < AssociationProxy #:nodoc: def create(attributes = {}) diff --git a/activerecord/lib/active_record/associations/belongs_to_polymorphic_association.rb b/activerecord/lib/active_record/associations/belongs_to_polymorphic_association.rb index f6edd6383c..38454ec242 100644 --- a/activerecord/lib/active_record/associations/belongs_to_polymorphic_association.rb +++ b/activerecord/lib/active_record/associations/belongs_to_polymorphic_association.rb @@ -1,4 +1,5 @@ module ActiveRecord + # = Active Record Belongs To Polymorphic Association module Associations class BelongsToPolymorphicAssociation < AssociationProxy #:nodoc: def replace(record) diff --git a/activerecord/lib/active_record/associations/has_and_belongs_to_many_association.rb b/activerecord/lib/active_record/associations/has_and_belongs_to_many_association.rb index 7f39a189e4..c989c3536d 100644 --- a/activerecord/lib/active_record/associations/has_and_belongs_to_many_association.rb +++ b/activerecord/lib/active_record/associations/has_and_belongs_to_many_association.rb @@ -1,4 +1,5 @@ module ActiveRecord + # = Active Record Has And Belongs To Many Association module Associations class HasAndBelongsToManyAssociation < AssociationCollection #:nodoc: def create(attributes = {}) diff --git a/activerecord/lib/active_record/associations/has_many_association.rb b/activerecord/lib/active_record/associations/has_many_association.rb index 0464e8ceea..92c6b3e770 100644 --- a/activerecord/lib/active_record/associations/has_many_association.rb +++ b/activerecord/lib/active_record/associations/has_many_association.rb @@ -1,4 +1,5 @@ module ActiveRecord + # = Active Record Has Many Association module Associations # This is the proxy that handles a has many association. # diff --git a/activerecord/lib/active_record/associations/has_many_through_association.rb b/activerecord/lib/active_record/associations/has_many_through_association.rb index 5338bb099d..17f850756f 100644 --- a/activerecord/lib/active_record/associations/has_many_through_association.rb +++ b/activerecord/lib/active_record/associations/has_many_through_association.rb @@ -2,6 +2,7 @@ require "active_record/associations/through_association_scope" require 'active_support/core_ext/object/blank' module ActiveRecord + # = Active Record Has Many Through Association module Associations class HasManyThroughAssociation < HasManyAssociation #:nodoc: include ThroughAssociationScope diff --git a/activerecord/lib/active_record/associations/has_one_association.rb b/activerecord/lib/active_record/associations/has_one_association.rb index ea769fd48b..68b8b792ad 100644 --- a/activerecord/lib/active_record/associations/has_one_association.rb +++ b/activerecord/lib/active_record/associations/has_one_association.rb @@ -1,4 +1,5 @@ module ActiveRecord + # = Active Record Belongs To Has One Association module Associations class HasOneAssociation < AssociationProxy #:nodoc: def initialize(owner, reflection) diff --git a/activerecord/lib/active_record/associations/has_one_through_association.rb b/activerecord/lib/active_record/associations/has_one_through_association.rb index a79bf943d1..fba0a2bfcc 100644 --- a/activerecord/lib/active_record/associations/has_one_through_association.rb +++ b/activerecord/lib/active_record/associations/has_one_through_association.rb @@ -1,6 +1,7 @@ require "active_record/associations/through_association_scope" module ActiveRecord + # = Active Record Has One Through Association module Associations class HasOneThroughAssociation < HasOneAssociation include ThroughAssociationScope diff --git a/activerecord/lib/active_record/associations/through_association_scope.rb b/activerecord/lib/active_record/associations/through_association_scope.rb index 1d2f323112..22e1033a9d 100644 --- a/activerecord/lib/active_record/associations/through_association_scope.rb +++ b/activerecord/lib/active_record/associations/through_association_scope.rb @@ -1,4 +1,5 @@ module ActiveRecord + # = Active Record Through Association Scope module Associations module ThroughAssociationScope @@ -91,7 +92,7 @@ module ActiveRecord # Construct attributes for :through pointing to owner and associate. def construct_join_attributes(associate) - # TODO: revist this to allow it for deletion, supposing dependent option is supported + # TODO: revisit this to allow it for deletion, supposing dependent option is supported raise ActiveRecord::HasManyThroughCantAssociateThroughHasOneOrManyReflection.new(@owner, @reflection) if [:has_one, :has_many].include?(@reflection.source_reflection.macro) join_attributes = construct_owner_attributes(@reflection.through_reflection).merge(@reflection.source_reflection.primary_key_name => associate.id) diff --git a/activerecord/lib/active_record/attribute_methods.rb b/activerecord/lib/active_record/attribute_methods.rb index c117271c71..56e18eced0 100644 --- a/activerecord/lib/active_record/attribute_methods.rb +++ b/activerecord/lib/active_record/attribute_methods.rb @@ -1,6 +1,7 @@ require 'active_support/core_ext/enumerable' module ActiveRecord + # = Active Record Attribute Methods module AttributeMethods #:nodoc: extend ActiveSupport::Concern include ActiveModel::AttributeMethods diff --git a/activerecord/lib/active_record/autosave_association.rb b/activerecord/lib/active_record/autosave_association.rb index 0dcadfab5f..c378e19864 100644 --- a/activerecord/lib/active_record/autosave_association.rb +++ b/activerecord/lib/active_record/autosave_association.rb @@ -1,6 +1,8 @@ require 'active_support/core_ext/array/wrap' module ActiveRecord + # = Active Record Autosave Association + # # AutosaveAssociation is a module that takes care of automatically saving # your associations when the parent is saved. In addition to saving, it # also destroys any associations that were marked for destruction. @@ -375,7 +377,7 @@ module ActiveRecord if association.updated? association_id = association.send(reflection.options[:primary_key] || :id) self[reflection.primary_key_name] = association_id - # TODO: Removing this code doesn't seem to matter… + # TODO: Removing this code doesn't seem to matter... if reflection.options[:polymorphic] self[reflection.options[:foreign_type]] = association.class.base_class.name.to_s end diff --git a/activerecord/lib/active_record/base.rb b/activerecord/lib/active_record/base.rb index def0fdaa2f..3f81ca7555 100644 --- a/activerecord/lib/active_record/base.rb +++ b/activerecord/lib/active_record/base.rb @@ -22,6 +22,8 @@ require 'arel' require 'active_record/errors' module ActiveRecord #:nodoc: + # = Active Record + # # Active Record objects don't specify their attributes directly, but rather infer them from the table definition with # which they're linked. Adding, removing, and changing attributes and their type is done directly in the database. Any change # is instantly reflected in the Active Record objects. The mapping that binds a given Active Record class to a certain @@ -1417,7 +1419,7 @@ module ActiveRecord #:nodoc: # For example in the test suite the topic model's after_initialize method sets the author_email_address to # test@test.com. I would have thought this would mean that all cloned models would have an author email address # of test@test.com. However the test_clone test method seems to test that this is not the case. As a result the - # after_initialize callback has to be run *before* the copying of the atrributes rather than afterwards in order + # after_initialize callback has to be run *before* the copying of the attributes rather than afterwards in order # for all tests to pass. This makes no sense to me. callback(:after_initialize) if respond_to_without_attributes?(:after_initialize) cloned_attributes = other.clone_attributes(:read_attribute_before_type_cast) diff --git a/activerecord/lib/active_record/callbacks.rb b/activerecord/lib/active_record/callbacks.rb index 997c85ef8c..637dac450b 100644 --- a/activerecord/lib/active_record/callbacks.rb +++ b/activerecord/lib/active_record/callbacks.rb @@ -1,6 +1,8 @@ require 'active_support/core_ext/array/wrap' module ActiveRecord + # = Active Record Callbacks + # # Callbacks are hooks into the lifecycle of an Active Record object that allow you to trigger logic # before or after an alteration of the object state. This can be used to make sure that associated and # dependent objects are deleted when +destroy+ is called (by overwriting +before_destroy+) or to massage attributes diff --git a/activerecord/lib/active_record/counter_cache.rb b/activerecord/lib/active_record/counter_cache.rb index 9601ed6afd..999322129a 100644 --- a/activerecord/lib/active_record/counter_cache.rb +++ b/activerecord/lib/active_record/counter_cache.rb @@ -1,4 +1,5 @@ module ActiveRecord + # = Active Record Counter Cache module CounterCache # Resets one or more counter caches to their correct value using an SQL # count query. This is useful when adding new counter caches, or if the diff --git a/activerecord/lib/active_record/dynamic_finder_match.rb b/activerecord/lib/active_record/dynamic_finder_match.rb index fa7a19487c..b39b291352 100644 --- a/activerecord/lib/active_record/dynamic_finder_match.rb +++ b/activerecord/lib/active_record/dynamic_finder_match.rb @@ -1,4 +1,9 @@ module ActiveRecord + + # = Active Record Dynamic Finder Match + # + # Provides dynamic attribute-based finders such as <tt>find_by_country</tt> + # if, for example, the <tt>Person</tt> has an attribute with that name. class DynamicFinderMatch def self.match(method) df_match = self.new(method) diff --git a/activerecord/lib/active_record/dynamic_scope_match.rb b/activerecord/lib/active_record/dynamic_scope_match.rb index f796ba669a..15f65be6bc 100644 --- a/activerecord/lib/active_record/dynamic_scope_match.rb +++ b/activerecord/lib/active_record/dynamic_scope_match.rb @@ -1,4 +1,11 @@ module ActiveRecord + + # = Active Record Dynamic Scope Match + # + # Provides dynamic attribute-based scopes such as <tt>scoped_by_price(4.99)</tt> + # if, for example, the <tt>Product</tt> has an attribute with that name. You can + # chain more <tt>scoped_by_* </tt> methods after the other. It acts like a named + # scope except that it's dynamic. class DynamicScopeMatch def self.match(method) ds_match = self.new(method) diff --git a/activerecord/lib/active_record/errors.rb b/activerecord/lib/active_record/errors.rb index cf5ddca2ba..7aa725d095 100644 --- a/activerecord/lib/active_record/errors.rb +++ b/activerecord/lib/active_record/errors.rb @@ -1,4 +1,7 @@ module ActiveRecord + + # = Active Record Errors + # # Generic Active Record exception class. class ActiveRecordError < StandardError end diff --git a/activerecord/lib/active_record/migration.rb b/activerecord/lib/active_record/migration.rb index 940f825038..b273c33e50 100644 --- a/activerecord/lib/active_record/migration.rb +++ b/activerecord/lib/active_record/migration.rb @@ -29,11 +29,15 @@ module ActiveRecord end end - # Migrations can manage the evolution of a schema used by several physical databases. It's a solution - # to the common problem of adding a field to make a new feature work in your local database, but being unsure of how to - # push that change to other developers and to the production server. With migrations, you can describe the transformations - # in self-contained classes that can be checked into version control systems and executed against another database that - # might be one, two, or five versions behind. + # = Active Record Migrations + # + # Migrations can manage the evolution of a schema used by several physical + # databases. It's a solution to the common problem of adding a field to make + # a new feature work in your local database, but being unsure of how to + # push that change to other developers and to the production server. With + # migrations, you can describe the transformations in self-contained classes + # that can be checked into version control systems and executed against + # another database that might be one, two, or five versions behind. # # Example of a simple migration: # @@ -47,10 +51,13 @@ module ActiveRecord # end # end # - # This migration will add a boolean flag to the accounts table and remove it if you're backing out of the migration. - # It shows how all migrations have two class methods +up+ and +down+ that describes the transformations required to implement - # or remove the migration. These methods can consist of both the migration specific methods like add_column and remove_column, - # but may also contain regular Ruby code for generating data needed for the transformations. + # This migration will add a boolean flag to the accounts table and remove it + # if you're backing out of the migration. It shows how all migrations have + # two class methods +up+ and +down+ that describes the transformations + # required to implement or remove the migration. These methods can consist + # of both the migration specific methods like add_column and remove_column, + # but may also contain regular Ruby code for generating data needed for the + # transformations. # # Example of a more complex migration that also needs to initialize data: # @@ -64,7 +71,9 @@ module ActiveRecord # t.integer :position # end # - # SystemSetting.create :name => "notice", :label => "Use notice?", :value => 1 + # SystemSetting.create :name => "notice", + # :label => "Use notice?", + # :value => 1 # end # # def self.down @@ -72,35 +81,49 @@ module ActiveRecord # end # end # - # This migration first adds the system_settings table, then creates the very first row in it using the Active Record model - # that relies on the table. It also uses the more advanced create_table syntax where you can specify a complete table schema - # in one block call. + # This migration first adds the system_settings table, then creates the very + # first row in it using the Active Record model that relies on the table. It + # also uses the more advanced create_table syntax where you can specify a + # complete table schema in one block call. # # == Available transformations # - # * <tt>create_table(name, options)</tt> Creates a table called +name+ and makes the table object available to a block - # that can then add columns to it, following the same format as add_column. See example above. The options hash is for - # fragments like "DEFAULT CHARSET=UTF-8" that are appended to the create table definition. + # * <tt>create_table(name, options)</tt> Creates a table called +name+ and + # makes the table object available to a block that can then add columns to it, + # following the same format as add_column. See example above. The options hash + # is for fragments like "DEFAULT CHARSET=UTF-8" that are appended to the create + # table definition. # * <tt>drop_table(name)</tt>: Drops the table called +name+. - # * <tt>rename_table(old_name, new_name)</tt>: Renames the table called +old_name+ to +new_name+. - # * <tt>add_column(table_name, column_name, type, options)</tt>: Adds a new column to the table called +table_name+ + # * <tt>rename_table(old_name, new_name)</tt>: Renames the table called +old_name+ + # to +new_name+. + # * <tt>add_column(table_name, column_name, type, options)</tt>: Adds a new column + # to the table called +table_name+ # named +column_name+ specified to be one of the following types: - # <tt>:string</tt>, <tt>:text</tt>, <tt>:integer</tt>, <tt>:float</tt>, <tt>:decimal</tt>, <tt>:datetime</tt>, <tt>:timestamp</tt>, <tt>:time</tt>, - # <tt>:date</tt>, <tt>:binary</tt>, <tt>:boolean</tt>. A default value can be specified by passing an - # +options+ hash like <tt>{ :default => 11 }</tt>. Other options include <tt>:limit</tt> and <tt>:null</tt> (e.g. <tt>{ :limit => 50, :null => false }</tt>) - # -- see ActiveRecord::ConnectionAdapters::TableDefinition#column for details. - # * <tt>rename_column(table_name, column_name, new_column_name)</tt>: Renames a column but keeps the type and content. - # * <tt>change_column(table_name, column_name, type, options)</tt>: Changes the column to a different type using the same - # parameters as add_column. - # * <tt>remove_column(table_name, column_name)</tt>: Removes the column named +column_name+ from the table called +table_name+. - # * <tt>add_index(table_name, column_names, options)</tt>: Adds a new index with the name of the column. Other options include - # <tt>:name</tt> and <tt>:unique</tt> (e.g. <tt>{ :name => "users_name_index", :unique => true }</tt>). - # * <tt>remove_index(table_name, index_name)</tt>: Removes the index specified by +index_name+. + # <tt>:string</tt>, <tt>:text</tt>, <tt>:integer</tt>, <tt>:float</tt>, + # <tt>:decimal</tt>, <tt>:datetime</tt>, <tt>:timestamp</tt>, <tt>:time</tt>, + # <tt>:date</tt>, <tt>:binary</tt>, <tt>:boolean</tt>. A default value can be + # specified by passing an +options+ hash like <tt>{ :default => 11 }</tt>. + # Other options include <tt>:limit</tt> and <tt>:null</tt> (e.g. + # <tt>{ :limit => 50, :null => false }</tt>) -- see + # ActiveRecord::ConnectionAdapters::TableDefinition#column for details. + # * <tt>rename_column(table_name, column_name, new_column_name)</tt>: Renames + # a column but keeps the type and content. + # * <tt>change_column(table_name, column_name, type, options)</tt>: Changes + # the column to a different type using the same parameters as add_column. + # * <tt>remove_column(table_name, column_name)</tt>: Removes the column named + # +column_name+ from the table called +table_name+. + # * <tt>add_index(table_name, column_names, options)</tt>: Adds a new index + # with the name of the column. Other options include + # <tt>:name</tt> and <tt>:unique</tt> (e.g. + # <tt>{ :name => "users_name_index", :unique => true }</tt>). + # * <tt>remove_index(table_name, index_name)</tt>: Removes the index specified + # by +index_name+. # # == Irreversible transformations # - # Some transformations are destructive in a manner that cannot be reversed. Migrations of that kind should raise - # an <tt>ActiveRecord::IrreversibleMigration</tt> exception in their +down+ method. + # Some transformations are destructive in a manner that cannot be reversed. + # Migrations of that kind should raise an <tt>ActiveRecord::IrreversibleMigration</tt> + # exception in their +down+ method. # # == Running migrations from within Rails # @@ -110,13 +133,15 @@ module ActiveRecord # rails generate migration MyNewMigration # # where MyNewMigration is the name of your migration. The generator will - # create an empty migration file <tt>timestamp_my_new_migration.rb</tt> in the <tt>db/migrate/</tt> - # directory where <tt>timestamp</tt> is the UTC formatted date and time that the migration was generated. + # create an empty migration file <tt>timestamp_my_new_migration.rb</tt> + # in the <tt>db/migrate/</tt> directory where <tt>timestamp</tt> is the + # UTC formatted date and time that the migration was generated. # # You may then edit the <tt>self.up</tt> and <tt>self.down</tt> methods of # MyNewMigration. # # There is a special syntactic shortcut to generate migrations that add fields to a table. + # # rails generate migration add_fieldname_to_tablename fieldname:string # # This will generate the file <tt>timestamp_add_fieldname_to_tablename</tt>, which will look like this: @@ -191,9 +216,10 @@ module ActiveRecord # # == Using a model after changing its table # - # Sometimes you'll want to add a column in a migration and populate it immediately after. In that case, you'll need - # to make a call to Base#reset_column_information in order to ensure that the model has the latest column data from - # after the new column was added. Example: + # Sometimes you'll want to add a column in a migration and populate it + # immediately after. In that case, you'll need to make a call to + # <tt>Base#reset_column_information</tt> in order to ensure that the model has the + # latest column data from after the new column was added. Example: # # class AddPeopleSalary < ActiveRecord::Migration # def self.up diff --git a/activerecord/lib/active_record/named_scope.rb b/activerecord/lib/active_record/named_scope.rb index 3d8f4a030b..ec0a98c6df 100644 --- a/activerecord/lib/active_record/named_scope.rb +++ b/activerecord/lib/active_record/named_scope.rb @@ -4,11 +4,12 @@ require 'active_support/core_ext/kernel/singleton_class' require 'active_support/core_ext/object/blank' module ActiveRecord + # = Active Record Named \Scopes module NamedScope extend ActiveSupport::Concern module ClassMethods - # Returns an anonymous scope. + # Returns an anonymous \scope. # # posts = Post.scoped # posts.size # Fires "select count(*) from posts" and returns the count @@ -18,10 +19,12 @@ module ActiveRecord # fruits = fruits.where(:colour => 'red') if options[:red_only] # fruits = fruits.limit(10) if limited? # - # Anonymous \scopes tend to be useful when procedurally generating complex queries, where passing - # intermediate values (scopes) around as first-class objects is convenient. + # Anonymous \scopes tend to be useful when procedurally generating complex + # queries, where passing intermediate values (\scopes) around as first-class + # objects is convenient. # - # You can define a scope that applies to all finders using ActiveRecord::Base.default_scope. + # You can define a \scope that applies to all finders using + # ActiveRecord::Base.default_scope. def scoped(options = {}, &block) if options.present? relation = scoped.apply_finder_options(options) @@ -35,7 +38,7 @@ module ActiveRecord read_inheritable_attribute(:scopes) || write_inheritable_attribute(:scopes, {}) end - # Adds a class method for retrieving and querying objects. A scope represents a narrowing of a database query, + # Adds a class method for retrieving and querying objects. A \scope represents a narrowing of a database query, # such as <tt>where(:color => :red).select('shirts.*').includes(:washing_instructions)</tt>. # # class Shirt < ActiveRecord::Base diff --git a/activerecord/lib/active_record/nested_attributes.rb b/activerecord/lib/active_record/nested_attributes.rb index eb9e792dd8..12a75f5d16 100644 --- a/activerecord/lib/active_record/nested_attributes.rb +++ b/activerecord/lib/active_record/nested_attributes.rb @@ -15,7 +15,7 @@ module ActiveRecord self.nested_attributes_options = {} end - # == Nested Attributes + # = Active Record Nested Attributes # # Nested attributes allow you to save attributes on associated records # through the parent. By default nested attribute updating is turned off, @@ -25,6 +25,7 @@ module ActiveRecord # # The attribute writer is named after the association, which means that # in the following example, two new methods are added to your model: + # # <tt>author_attributes=(attributes)</tt> and # <tt>pages_attributes=(attributes)</tt>. # @@ -132,7 +133,7 @@ module ActiveRecord # member.posts.first.title # => 'Kari, the awesome Ruby documentation browser!' # member.posts.second.title # => 'The egalitarian assumption of the modern citizen' # - # Alternatively, :reject_if also accepts a symbol for using methods: + # Alternatively, :reject_if also accepts a symbol for using methods: # # class Member < ActiveRecord::Base # has_many :posts @@ -144,7 +145,7 @@ module ActiveRecord # accepts_nested_attributes_for :posts, :reject_if => :reject_posts # # def reject_posts(attributed) - # attributed['title].blank? + # attributed['title'].blank? # end # end # @@ -278,7 +279,7 @@ module ActiveRecord # Assigns the given attributes to the association. # # If update_only is false and the given attributes include an <tt>:id</tt> - # that matches the existing record’s id, then the existing record will be + # that matches the existing record's id, then the existing record will be # modified. If update_only is true, a new record is only created when no # object exists. Otherwise a new record will be built. # diff --git a/activerecord/lib/active_record/observer.rb b/activerecord/lib/active_record/observer.rb index fabbc33005..5f80bd86df 100644 --- a/activerecord/lib/active_record/observer.rb +++ b/activerecord/lib/active_record/observer.rb @@ -1,6 +1,8 @@ require 'active_support/core_ext/class/attribute' module ActiveRecord + # = Active Record Observer + # # Observer classes respond to lifecycle callbacks to implement trigger-like # behavior outside the original class. This is a great way to reduce the # clutter that normally comes when the model class is burdened with diff --git a/activerecord/lib/active_record/persistence.rb b/activerecord/lib/active_record/persistence.rb index 10788630a5..9e28aa2a05 100644 --- a/activerecord/lib/active_record/persistence.rb +++ b/activerecord/lib/active_record/persistence.rb @@ -1,6 +1,8 @@ module ActiveRecord + # = Active Record Persistence module Persistence - # Returns true if this object hasn't been saved yet -- that is, a record for the object doesn't exist yet; otherwise, returns false. + # Returns true if this object hasn't been saved yet -- that is, a record + # for the object doesn't exist in the data store yet; otherwise, returns false. def new_record? @new_record end @@ -10,7 +12,8 @@ module ActiveRecord @destroyed end - # Returns if the record is persisted, i.e. it's not a new record and it was not destroyed. + # Returns if the record is persisted, i.e. it's not a new record and it was + # not destroyed. def persisted? !(new_record? || destroyed?) end @@ -69,8 +72,8 @@ module ActiveRecord freeze end - # Deletes the record in the database and freezes this instance to reflect that no changes should - # be made (since they can't be persisted). + # Deletes the record in the database and freezes this instance to reflect + # that no changes should be made (since they can't be persisted). def destroy if persisted? self.class.unscoped.where(self.class.arel_table[self.class.primary_key].eq(id)).delete_all @@ -80,10 +83,13 @@ module ActiveRecord freeze end - # Returns an instance of the specified +klass+ with the attributes of the current record. This is mostly useful in relation to - # single-table inheritance structures where you want a subclass to appear as the superclass. This can be used along with record - # identification in Action Pack to allow, say, <tt>Client < Company</tt> to do something like render <tt>:partial => @client.becomes(Company)</tt> - # to render that instance using the companies/company partial instead of clients/client. + # Returns an instance of the specified +klass+ with the attributes of the + # current record. This is mostly useful in relation to single-table + # inheritance structures where you want a subclass to appear as the + # superclass. This can be used along with record identification in + # Action Pack to allow, say, <tt>Client < Company</tt> to do something + # like render <tt>:partial => @client.becomes(Company)</tt> to render that + # instance using the companies/company partial instead of clients/client. # # Note: The new instance will share a link to the same attributes as the original class. So any change to the attributes in either # instance will affect the other. @@ -104,14 +110,15 @@ module ActiveRecord save(:validate => false) end - # Updates all the attributes from the passed-in Hash and saves the record. If the object is invalid, the saving will - # fail and false will be returned. + # Updates all the attributes from the passed-in Hash and saves the record. + # If the object is invalid, the saving will fail and false will be returned. def update_attributes(attributes) self.attributes = attributes save end - # Updates an object just like Base.update_attributes but calls save! instead of save so an exception is raised if the record is invalid. + # Updates an object just like Base.update_attributes but calls save! instead + # of save so an exception is raised if the record is invalid. def update_attributes!(attributes) self.attributes = attributes save! diff --git a/activerecord/lib/active_record/query_cache.rb b/activerecord/lib/active_record/query_cache.rb index 093c6c1e55..d9f85a4e5e 100644 --- a/activerecord/lib/active_record/query_cache.rb +++ b/activerecord/lib/active_record/query_cache.rb @@ -1,6 +1,7 @@ require 'active_support/core_ext/object/blank' module ActiveRecord + # = Active Record Query Cache class QueryCache module ClassMethods # Enable the query cache within the block if Active Record is configured. diff --git a/activerecord/lib/active_record/railtie.rb b/activerecord/lib/active_record/railtie.rb index 0386fd4651..36df878e1b 100644 --- a/activerecord/lib/active_record/railtie.rb +++ b/activerecord/lib/active_record/railtie.rb @@ -9,6 +9,7 @@ require "active_model/railtie" require "action_controller/railtie" module ActiveRecord + # = Active Record Railtie class Railtie < Rails::Railtie config.active_record = ActiveSupport::OrderedOptions.new diff --git a/activerecord/lib/active_record/reflection.rb b/activerecord/lib/active_record/reflection.rb index 0e48e229b3..a82e5d7ed1 100644 --- a/activerecord/lib/active_record/reflection.rb +++ b/activerecord/lib/active_record/reflection.rb @@ -1,12 +1,16 @@ module ActiveRecord + # = Active Record Reflection module Reflection # :nodoc: extend ActiveSupport::Concern - # Reflection allows you to interrogate Active Record classes and objects about their associations and aggregations. - # This information can, for example, be used in a form builder that took an Active Record object and created input - # fields for all of the attributes depending on their type and displayed the associations to other objects. + # Reflection allows you to interrogate Active Record classes and objects + # about their associations and aggregations. This information can, + # for example, be used in a form builder that took an Active Record object + # and created input fields for all of the attributes depending on their type + # and displayed the associations to other objects. # - # You can find the interface for the AggregateReflection and AssociationReflection classes in the abstract MacroReflection class. + # You can find the interface for the AggregateReflection and AssociationReflection + # classes in the abstract MacroReflection class. module ClassMethods def create_reflection(macro, name, options, active_record) case macro @@ -43,8 +47,11 @@ module ActiveRecord reflections[aggregation].is_a?(AggregateReflection) ? reflections[aggregation] : nil end - # Returns an array of AssociationReflection objects for all the associations in the class. If you only want to reflect on a - # certain association type, pass in the symbol (<tt>:has_many</tt>, <tt>:has_one</tt>, <tt>:belongs_to</tt>) for that as the first parameter. + # Returns an array of AssociationReflection objects for all the + # associations in the class. If you only want to reflect on a certain + # association type, pass in the symbol (<tt>:has_many</tt>, <tt>:has_one</tt>, + # <tt>:belongs_to</tt>) for that as the first parameter. + # # Example: # # Account.reflect_on_all_associations # returns an array of all associations @@ -71,8 +78,9 @@ module ActiveRecord end - # Abstract base class for AggregateReflection and AssociationReflection that describes the interface available for both of - # those classes. Objects of AggregateReflection and AssociationReflection are returned by the Reflection::ClassMethods. + # Abstract base class for AggregateReflection and AssociationReflection that + # describes the interface available for both of those classes. Objects of + # AggregateReflection and AssociationReflection are returned by the Reflection::ClassMethods. class MacroReflection attr_reader :active_record @@ -80,13 +88,15 @@ module ActiveRecord @macro, @name, @options, @active_record = macro, name, options, active_record end - # Returns the name of the macro. For example, <tt>composed_of :balance, :class_name => 'Money'</tt> will return - # <tt>:balance</tt> or for <tt>has_many :clients</tt> it will return <tt>:clients</tt>. + # Returns the name of the macro. For example, <tt>composed_of :balance, + # :class_name => 'Money'</tt> will return <tt>:balance</tt> or for + # <tt>has_many :clients</tt> it will return <tt>:clients</tt>. def name @name end - # Returns the macro type. For example, <tt>composed_of :balance, :class_name => 'Money'</tt> will return <tt>:composed_of</tt> + # Returns the macro type. For example, + # <tt>composed_of :balance, :class_name => 'Money'</tt> will return <tt>:composed_of</tt> # or for <tt>has_many :clients</tt> will return <tt>:has_many</tt>. def macro @macro @@ -132,11 +142,13 @@ module ActiveRecord end - # Holds all the meta-data about an aggregation as it was specified in the Active Record class. + # Holds all the meta-data about an aggregation as it was specified in the + # Active Record class. class AggregateReflection < MacroReflection #:nodoc: end - # Holds all the meta-data about an association as it was specified in the Active Record class. + # Holds all the meta-data about an association as it was specified in the + # Active Record class. class AssociationReflection < MacroReflection #:nodoc: # Returns the target association's class: # @@ -165,14 +177,14 @@ module ActiveRecord klass.new(*options) end - # Creates a new instance of the associated class, and immediates saves it + # Creates a new instance of the associated class, and immediately saves it # with ActiveRecord::Base#save. +options+ will be passed to the class's # creation method. Returns the newly created object. def create_association(*options) klass.create(*options) end - # Creates a new instance of the associated class, and immediates saves it + # Creates a new instance of the associated class, and immediately saves it # with ActiveRecord::Base#save!. +options+ will be passed to the class's # creation method. If the created record doesn't pass validations, then an # exception will be raised. @@ -267,10 +279,10 @@ module ActiveRecord # Returns whether or not the association should be validated as part of # the parent's validation. # - # Unless you explicitely disable validation with + # Unless you explicitly disable validation with # <tt>:validate => false</tt>, it will take place when: # - # * you explicitely enable validation; <tt>:validate => true</tt> + # * you explicitly enable validation; <tt>:validate => true</tt> # * you use autosave; <tt>:autosave => true</tt> # * the association is a +has_many+ association def validate? @@ -306,9 +318,12 @@ module ActiveRecord end end - # Holds all the meta-data about a :through association as it was specified in the Active Record class. + # Holds all the meta-data about a :through association as it was specified + # in the Active Record class. class ThroughReflection < AssociationReflection #:nodoc: - # Gets the source of the through reflection. It checks both a singularized and pluralized form for <tt>:belongs_to</tt> or <tt>:has_many</tt>. + # Gets the source of the through reflection. It checks both a singularized + # and pluralized form for <tt>:belongs_to</tt> or <tt>:has_many</tt>. + # # (The <tt>:tags</tt> association on Tagging below.) # # class Post < ActiveRecord::Base diff --git a/activerecord/lib/active_record/relation.rb b/activerecord/lib/active_record/relation.rb index 99c914d7fc..66970a5ea1 100644 --- a/activerecord/lib/active_record/relation.rb +++ b/activerecord/lib/active_record/relation.rb @@ -1,6 +1,7 @@ require 'active_support/core_ext/object/blank' module ActiveRecord + # = Active Record Relation class Relation JoinOperation = Struct.new(:relation, :join_class, :on) ASSOCIATION_METHODS = [:includes, :eager_load, :preload] @@ -67,7 +68,7 @@ module ActiveRecord preload += @includes_values unless eager_loading? preload.each {|associations| @klass.send(:preload_associations, @records, associations) } - # @readonly_value is true only if set explicity. @implicit_readonly is true if there are JOINS and no explicit SELECT. + # @readonly_value is true only if set explicitly. @implicit_readonly is true if there are JOINS and no explicit SELECT. readonly = @readonly_value.nil? ? @implicit_readonly : @readonly_value @records.each { |record| record.readonly! } if readonly @@ -75,10 +76,12 @@ module ActiveRecord @records end + # Returns size of the records. def size loaded? ? @records.length : count end + # Returns true if there are no records. def empty? loaded? ? @records.empty? : count.zero? end @@ -240,8 +243,9 @@ module ActiveRecord # Post.delete_all("person_id = 5 AND (category = 'Something' OR category = 'Else')") # Post.delete_all(["person_id = ? AND (category = ? OR category = ?)", 5, 'Something', 'Else']) # - # Both calls delete the affected posts all at once with a single DELETE statement. If you need to destroy dependent - # associations or call your <tt>before_*</tt> or +after_destroy+ callbacks, use the +destroy_all+ method instead. + # Both calls delete the affected posts all at once with a single DELETE statement. + # If you need to destroy dependent associations or call your <tt>before_*</tt> or + # +after_destroy+ callbacks, use the +destroy_all+ method instead. def delete_all(conditions = nil) conditions ? where(conditions).delete_all : arel.delete.tap { reset } end diff --git a/activerecord/lib/active_record/schema.rb b/activerecord/lib/active_record/schema.rb index a833356d15..e2783087ec 100644 --- a/activerecord/lib/active_record/schema.rb +++ b/activerecord/lib/active_record/schema.rb @@ -1,6 +1,8 @@ require 'active_support/core_ext/object/blank' module ActiveRecord + # = Active Record Schema + # # Allows programmers to programmatically define a schema in a portable # DSL. This means you can define tables, indexes, etc. without using SQL # directly, so your applications can more easily support multiple diff --git a/activerecord/lib/active_record/schema_dumper.rb b/activerecord/lib/active_record/schema_dumper.rb index cd54653581..a4757773d8 100644 --- a/activerecord/lib/active_record/schema_dumper.rb +++ b/activerecord/lib/active_record/schema_dumper.rb @@ -2,6 +2,8 @@ require 'stringio' require 'active_support/core_ext/big_decimal' module ActiveRecord + # = Active Record Schema Dumper + # # This class is used to dump the database schema for some connection to some # output format (i.e., ActiveRecord::Schema). class SchemaDumper #:nodoc: @@ -39,13 +41,14 @@ module ActiveRecord define_params = @version ? ":version => #{@version}" : "" stream.puts <<HEADER -# This file is auto-generated from the current state of the database. Instead of editing this file, -# please use the migrations feature of Active Record to incrementally modify your database, and -# then regenerate this schema definition. +# This file is auto-generated from the current state of the database. Instead +# of editing this file, please use the migrations feature of Active Record to +# incrementally modify your database, and then regenerate this schema definition. # -# Note that this schema.rb definition is the authoritative source for your database schema. If you need -# to create the application database on another system, you should be using db:schema:load, not running -# all the migrations from scratch. The latter is a flawed and unsustainable approach (the more migrations +# Note that this schema.rb definition is the authoritative source for your +# database schema. If you need to create the application database on another +# system, you should be using db:schema:load, not running all the migrations +# from scratch. The latter is a flawed and unsustainable approach (the more migrations # you'll amass, the slower it'll run and the greater likelihood for issues). # # It's strongly recommended to check this file into your version control system. @@ -173,15 +176,15 @@ HEADER def indexes(table, stream) if (indexes = @connection.indexes(table)).any? add_index_statements = indexes.map do |index| - statment_parts = [ ('add_index ' + index.table.inspect) ] - statment_parts << index.columns.inspect - statment_parts << (':name => ' + index.name.inspect) - statment_parts << ':unique => true' if index.unique + statement_parts = [ ('add_index ' + index.table.inspect) ] + statement_parts << index.columns.inspect + statement_parts << (':name => ' + index.name.inspect) + statement_parts << ':unique => true' if index.unique index_lengths = index.lengths.compact if index.lengths.is_a?(Array) - statment_parts << (':length => ' + Hash[*index.columns.zip(index.lengths).flatten].inspect) if index_lengths.present? + statement_parts << (':length => ' + Hash[*index.columns.zip(index.lengths).flatten].inspect) if index_lengths.present? - ' ' + statment_parts.join(', ') + ' ' + statement_parts.join(', ') end stream.puts add_index_statements.sort.join("\n") diff --git a/activerecord/lib/active_record/serialization.rb b/activerecord/lib/active_record/serialization.rb index b49471f7ab..2d8bd184f3 100644 --- a/activerecord/lib/active_record/serialization.rb +++ b/activerecord/lib/active_record/serialization.rb @@ -1,4 +1,5 @@ module ActiveRecord #:nodoc: + # = Active Record Serialization module Serialization extend ActiveSupport::Concern include ActiveModel::Serializers::JSON @@ -22,6 +23,7 @@ module ActiveRecord #:nodoc: private # Add associations specified via the <tt>:includes</tt> option. + # # Expects a block that takes as arguments: # +association+ - name of the association # +records+ - the association record(s) to be serialized diff --git a/activerecord/lib/active_record/session_store.rb b/activerecord/lib/active_record/session_store.rb index 931872eded..f712a2c94f 100644 --- a/activerecord/lib/active_record/session_store.rb +++ b/activerecord/lib/active_record/session_store.rb @@ -1,4 +1,6 @@ module ActiveRecord + # = Active Record Session Store + # # A session store backed by an Active Record class. A default class is # provided, but any object duck-typing to an Active Record Session class # with text +session_id+ and +data+ attributes is sufficient. @@ -7,6 +9,7 @@ module ActiveRecord # +id+ (numeric primary key), # +session_id+ (text, or longtext if your session data exceeds 65K), and # +data+ (text or longtext; careful if your session data exceeds 65KB). + # # The +session_id+ column should always be indexed for speedy lookups. # Session data is marshaled to the +data+ column in Base64 format. # If the data you write is larger than the column's size limit, @@ -14,9 +17,11 @@ module ActiveRecord # # You may configure the table name, primary key, and data column. # For example, at the end of <tt>config/environment.rb</tt>: + # # ActiveRecord::SessionStore::Session.table_name = 'legacy_session_table' # ActiveRecord::SessionStore::Session.primary_key = 'session_id' # ActiveRecord::SessionStore::Session.data_column_name = 'legacy_session_data' + # # Note that setting the primary key to the +session_id+ frees you from # having a separate +id+ column if you don't want it. However, you must # set <tt>session.model.id = session.session_id</tt> by hand! A before filter @@ -29,8 +34,11 @@ module ActiveRecord # You may provide your own session class implementation, whether a # feature-packed Active Record or a bare-metal high-performance SQL # store, by setting + # # ActiveRecord::SessionStore.session_class = MySessionClass + # # You must implement these methods: + # # self.find_by_session_id(session_id) # initialize(hash_of_session_id_and_data) # attr_reader :session_id diff --git a/activerecord/lib/active_record/test_case.rb b/activerecord/lib/active_record/test_case.rb index 0a77ad5fd7..e61a378d17 100644 --- a/activerecord/lib/active_record/test_case.rb +++ b/activerecord/lib/active_record/test_case.rb @@ -1,4 +1,7 @@ module ActiveRecord + # = Active Record Test Case + # + # Defines some test assertions to test against SQL queries. class TestCase < ActiveSupport::TestCase #:nodoc: def assert_date_from_db(expected, actual, message = nil) # SybaseAdapter doesn't have a separate column type just for dates, diff --git a/activerecord/lib/active_record/timestamp.rb b/activerecord/lib/active_record/timestamp.rb index 9fba8f0aca..ffd12d2082 100644 --- a/activerecord/lib/active_record/timestamp.rb +++ b/activerecord/lib/active_record/timestamp.rb @@ -1,11 +1,16 @@ module ActiveRecord - # Active Record automatically timestamps create and update operations if the table has fields - # named created_at/created_on or updated_at/updated_on. + # = Active Record Timestamp + # + # Active Record automatically timestamps create and update operations if the + # table has fields named <tt>created_at/created_on</tt> or + # <tt>updated_at/updated_on</tt>. + # + # Timestamping can be turned off by setting: # - # Timestamping can be turned off by setting # <tt>ActiveRecord::Base.record_timestamps = false</tt> # - # Timestamps are in the local timezone by default but you can use UTC by setting + # Timestamps are in the local timezone by default but you can use UTC by setting: + # # <tt>ActiveRecord::Base.default_timezone = :utc</tt> module Timestamp extend ActiveSupport::Concern @@ -16,8 +21,9 @@ module ActiveRecord end # Saves the record with the updated_at/on attributes set to the current time. - # If the save fails because of validation errors, an ActiveRecord::RecordInvalid exception is raised. - # If an attribute name is passed, that attribute is used for the touch instead of the updated_at/on attributes. + # If the save fails because of validation errors, an + # ActiveRecord::RecordInvalid exception is raised. If an attribute name is passed, + # that attribute is used for the touch instead of the updated_at/on attributes. # # Examples: # diff --git a/activerecord/lib/active_record/transactions.rb b/activerecord/lib/active_record/transactions.rb index 775d9f0fb8..a7709b9489 100644 --- a/activerecord/lib/active_record/transactions.rb +++ b/activerecord/lib/active_record/transactions.rb @@ -11,7 +11,8 @@ module ActiveRecord included do define_callbacks :commit, :rollback, :terminator => "result == false", :scope => [:kind, :name] end - + # = Active Record Transactions + # # Transactions are protective blocks where SQL statements are only permanent # if they can all succeed as one atomic action. The classic example is a # transfer between two accounts where you can only have a deposit if the @@ -19,7 +20,8 @@ module ActiveRecord # the database and guard the data against program errors or database # break-downs. So basically you should use transaction blocks whenever you # have a number of statements that must be executed together or not at all. - # Example: + # + # For example: # # ActiveRecord::Base.transaction do # david.withdrawal(100) diff --git a/activerecord/lib/active_record/validations.rb b/activerecord/lib/active_record/validations.rb index 6ef9382b2a..b98fd353aa 100644 --- a/activerecord/lib/active_record/validations.rb +++ b/activerecord/lib/active_record/validations.rb @@ -1,6 +1,9 @@ module ActiveRecord + # = Active Record Validations + # # Raised by <tt>save!</tt> and <tt>create!</tt> when the record is invalid. Use the # +record+ method to retrieve the record which did not validate. + # # begin # complex_operation_that_calls_save!_internally # rescue ActiveRecord::RecordInvalid => invalid |