diff options
author | Pratik Naik <pratiknaik@gmail.com> | 2008-04-05 03:52:58 +0000 |
---|---|---|
committer | Pratik Naik <pratiknaik@gmail.com> | 2008-04-05 03:52:58 +0000 |
commit | aa4af60aad5772458e8ba3bd08505781aeeb53a2 (patch) | |
tree | 22eadb1dc551f95e3150f803dc654eaa125544d9 /activerecord/lib/active_record | |
parent | 08318b8bcd32bae741e672899a33c6a7d52664c8 (diff) | |
download | rails-aa4af60aad5772458e8ba3bd08505781aeeb53a2.tar.gz rails-aa4af60aad5772458e8ba3bd08505781aeeb53a2.tar.bz2 rails-aa4af60aad5772458e8ba3bd08505781aeeb53a2.zip |
Improve documentation.
git-svn-id: http://svn-commit.rubyonrails.org/rails/trunk@9226 5ecf4fe2-1ee6-0310-87b1-e25e094e27de
Diffstat (limited to 'activerecord/lib/active_record')
7 files changed, 73 insertions, 18 deletions
diff --git a/activerecord/lib/active_record/associations.rb b/activerecord/lib/active_record/associations.rb index 62c5adff52..c5cf06cf10 100755 --- a/activerecord/lib/active_record/associations.rb +++ b/activerecord/lib/active_record/associations.rb @@ -136,7 +136,7 @@ module ActiveRecord # #others.create!(attributes={}) | X | X | X # #others.size | X | X | X # #others.length | X | X | X - # #others.count | | X | X + # #others.count | X | X | X # #others.sum(args*,&block) | X | X | X # #others.empty? | X | X | X # #others.clear | X | X | @@ -150,9 +150,9 @@ module ActiveRecord # # == Cardinality and associations # - # ActiveRecord associations can be used to describe relations with one-to-one, one-to-many - # and many-to-many cardinality. Each model uses an association to describe its role in - # the relation. In each case, the +belongs_to+ association is used in the model that has + # ActiveRecord associations can be used to describe one-to-one, one-to-many and many-to-many + # relationships between models. Each model uses an association to describe its role in + # the relation. The +belongs_to+ association is always used in the model that has # the foreign key. # # === One-to-one diff --git a/activerecord/lib/active_record/associations/association_proxy.rb b/activerecord/lib/active_record/associations/association_proxy.rb index 421ddc15ee..26274fff93 100644 --- a/activerecord/lib/active_record/associations/association_proxy.rb +++ b/activerecord/lib/active_record/associations/association_proxy.rb @@ -1,5 +1,50 @@ module ActiveRecord module Associations + # This is the root class of all association proxies: + # + # AssociationProxy + # BelongsToAssociation + # HasOneAssociation + # BelongsToPolymorphicAssociation + # AssociationCollection + # HasManyAssociation + # HasAndBelongsToManyAssociation + # HasManyThroughAssociation + # HasOneThroughAssociation + # + # Association proxies in Active Record are middlemen between the object that + # holds the association, known as the <tt>@owner</tt>, and the actual associated + # object, known as the <tt>@target</tt>. The kind of association any proxy is + # about is available in <tt>@reflection</tt>. That's an instance of the class + # ActiveRecord::Reflection::AssociationReflection. + # + # For example, given + # + # class Blog < ActiveRecord::Base + # has_many :posts + # end + # + # blog = Blog.find(:first) + # + # the association proxy in <tt>blog.posts</tt> has the object in +blog+ as + # <tt>@owner</tt>, the collection of its posts as <tt>@target</tt>, and + # the <tt>@reflection</tt> object represents a <tt>:has_many</tt> macro. + # + # This class has most of the basic instance methods removed, and delegates + # unknown methods to <tt>@target</tt> via <tt>method_missing</tt>. As a + # corner case, it even removes the +class+ method and that's why you get + # + # blog.posts.class # => Array + # + # though the object behind <tt>blog.posts</tt> is not an Array, but an + # ActiveRecord::Associations::HasManyAssociation. + # + # The <tt>@target</tt> object is not loaded until needed. For example, + # + # blog.posts.count + # + # is computed directly through SQL and does not trigger by itself the + # instantiation of the actual post records. class AssociationProxy #:nodoc: alias_method :proxy_respond_to?, :respond_to? alias_method :proxy_extend, :extend diff --git a/activerecord/lib/active_record/base.rb b/activerecord/lib/active_record/base.rb index fe38454226..92417a429f 100755 --- a/activerecord/lib/active_record/base.rb +++ b/activerecord/lib/active_record/base.rb @@ -191,6 +191,10 @@ module ActiveRecord #:nodoc: # # Student.find(:all, :conditions => { :grade => 9..12 }) # + # An array may be used in the hash to use the SQL IN operator: + # + # Student.find(:all, :conditions => { :grade => [9,11,12] }) + # # == Overwriting default accessors # # All column values are automatically available through basic accessors on the Active Record object, but sometimes you @@ -488,6 +492,7 @@ module ActiveRecord #:nodoc: # Examples for find all: # Person.find(:all) # returns an array of objects for all the rows fetched by SELECT * FROM people # Person.find(:all, :conditions => [ "category IN (?)", categories], :limit => 50) + # Person.find(:all, :conditions => { :friends => ["Bob", "Steve", "Fred"] } # Person.find(:all, :offset => 10, :limit => 10) # Person.find(:all, :include => [ :account, :friends ]) # Person.find(:all, :group => "category") diff --git a/activerecord/lib/active_record/connection_adapters/abstract/schema_statements.rb b/activerecord/lib/active_record/connection_adapters/abstract/schema_statements.rb index c8913d0157..393d5c130e 100644 --- a/activerecord/lib/active_record/connection_adapters/abstract/schema_statements.rb +++ b/activerecord/lib/active_record/connection_adapters/abstract/schema_statements.rb @@ -161,12 +161,12 @@ module ActiveRecord # an Array of Symbols. # # The index will be named after the table and the first column name, - # unless you pass +:name+ as an option. + # unless you pass <tt>:name</tt> as an option. # # When creating an index on multiple columns, the first column is used as a name # for the index. For example, when you specify an index on two columns - # [+:first+, +:last+], the DBMS creates an index for both columns as well as an - # index for the first column +:first+. Using just the first name for this index + # [<tt>:first</tt>, <tt>:last</tt>], the DBMS creates an index for both columns as well as an + # index for the first column <tt>:first</tt>. Using just the first name for this index # makes sense, because you will never have to create a singular index with this # name. # diff --git a/activerecord/lib/active_record/reflection.rb b/activerecord/lib/active_record/reflection.rb index 07ea25a885..3f11133e8c 100644 --- a/activerecord/lib/active_record/reflection.rb +++ b/activerecord/lib/active_record/reflection.rb @@ -76,34 +76,39 @@ module ActiveRecord @macro, @name, @options, @active_record = macro, name, options, active_record end - # Returns the name of the macro, so it would return :balance for "composed_of :balance, :class_name => 'Money'" or - # :clients for "has_many :clients". + # 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 type of the macro, so it would return :composed_of for - # "composed_of :balance, :class_name => 'Money'" or :has_many for "has_many :clients". + # 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 end - # Returns the hash of options used for the macro, so it would return { :class_name => "Money" } for - # "composed_of :balance, :class_name => 'Money'" or {} for "has_many :clients". + # Returns the hash of options used for the macro. For example, it would return <tt>{ :class_name => "Money" }</tt> for + # <tt>composed_of :balance, :class_name => 'Money'</tt> or +{}+ for <tt>has_many :clients</tt>. + def options @options end - # Returns the class for the macro, so "composed_of :balance, :class_name => 'Money'" returns the Money class and - # "has_many :clients" returns the Client class. + # Returns the class for the macro. For example, <tt>composed_of :balance, :class_name => 'Money'</tt> returns the +Money+ + # class and <tt>has_many :clients</tt> returns the +Client+ class. def klass @klass ||= class_name.constantize end + # Returns the class name for the macro. For example, <tt>composed_of :balance, :class_name => 'Money'</tt> returns <tt>'Money'</tt> + # and <tt>has_many :clients</tt> returns <tt>'Client'</tt>. def class_name @class_name ||= options[:class_name] || derive_class_name end + # Returns +true+ if +self+ and +other_aggregation+ have the same +name+ attribute, +active_record+ attribute, + # and +other_aggregation+ has an options hash assigned to it. def ==(other_aggregation) name == other_aggregation.name && other_aggregation.options && active_record == other_aggregation.active_record end diff --git a/activerecord/lib/active_record/transactions.rb b/activerecord/lib/active_record/transactions.rb index d1962f0c1f..13cb5f3f48 100644 --- a/activerecord/lib/active_record/transactions.rb +++ b/activerecord/lib/active_record/transactions.rb @@ -28,7 +28,7 @@ module ActiveRecord # # This example will only take money from David and give to Mary if neither +withdrawal+ nor +deposit+ raises an exception. # Exceptions will force a ROLLBACK that returns the database to the state before the transaction was begun. Be aware, though, - # that the objects by default will _not_ have their instance data returned to their pre-transactional state. + # that the objects will _not_ have their instance data returned to their pre-transactional state. # # == Different ActiveRecord classes in a single transaction # diff --git a/activerecord/lib/active_record/validations.rb b/activerecord/lib/active_record/validations.rb index 72c48d1e2a..bd1c67cd84 100755 --- a/activerecord/lib/active_record/validations.rb +++ b/activerecord/lib/active_record/validations.rb @@ -723,7 +723,7 @@ module ActiveRecord # # Configuration options: # * <tt>in</tt> - An enumerable object of available items - # * <tt>message</tt> - Specifies a customer error message (default is: "is not included in the list") + # * <tt>message</tt> - Specifies a custom error message (default is: "is not included in the list") # * <tt>allow_nil</tt> - If set to true, skips this validation if the attribute is null (default is: false) # * <tt>allow_blank</tt> - If set to true, skips this validation if the attribute is blank (default is: false) # * <tt>if</tt> - Specifies a method, proc or string to call to determine if the validation should @@ -755,7 +755,7 @@ module ActiveRecord # # Configuration options: # * <tt>in</tt> - An enumerable object of items that the value shouldn't be part of - # * <tt>message</tt> - Specifies a customer error message (default is: "is reserved") + # * <tt>message</tt> - Specifies a custom error message (default is: "is reserved") # * <tt>allow_nil</tt> - If set to true, skips this validation if the attribute is null (default is: false) # * <tt>allow_blank</tt> - If set to true, skips this validation if the attribute is blank (default is: false) # * <tt>if</tt> - Specifies a method, proc or string to call to determine if the validation should |