From aa4af60aad5772458e8ba3bd08505781aeeb53a2 Mon Sep 17 00:00:00 2001 From: Pratik Naik Date: Sat, 5 Apr 2008 03:52:58 +0000 Subject: Improve documentation. git-svn-id: http://svn-commit.rubyonrails.org/rails/trunk@9226 5ecf4fe2-1ee6-0310-87b1-e25e094e27de --- activerecord/CHANGELOG | 2 + activerecord/README | 11 +----- activerecord/lib/active_record/associations.rb | 8 ++-- .../associations/association_proxy.rb | 45 ++++++++++++++++++++++ activerecord/lib/active_record/base.rb | 5 +++ .../abstract/schema_statements.rb | 6 +-- activerecord/lib/active_record/reflection.rb | 21 ++++++---- activerecord/lib/active_record/transactions.rb | 2 +- activerecord/lib/active_record/validations.rb | 4 +- 9 files changed, 77 insertions(+), 27 deletions(-) (limited to 'activerecord') diff --git a/activerecord/CHANGELOG b/activerecord/CHANGELOG index 2d13ca8deb..6296d9c4f9 100644 --- a/activerecord/CHANGELOG +++ b/activerecord/CHANGELOG @@ -1,5 +1,7 @@ *SVN* +* Improve documentation. [Xavier Noria, Jack Danger Canty, leethal] + * Tweak ActiveRecord::Base#to_json to include a root value in the returned hash: {"post": {"title": ...}} [rick] Post.find(1).to_json # => {"title": ...} diff --git a/activerecord/README b/activerecord/README index 442530184c..7204b44ec4 100755 --- a/activerecord/README +++ b/activerecord/README @@ -102,21 +102,14 @@ A short rundown of the major features: {Learn more}[link:classes/ActiveRecord/Base.html] -* Transaction support on both a database and object level. The latter is implemented - by using Transaction::Simple[http://railsmanual.com/module/Transaction::Simple] +* Transactions - # Just database transaction + # Database transaction Account.transaction do david.withdrawal(100) mary.deposit(100) end - # Database and object transaction - Account.transaction(david, mary) do - david.withdrawal(100) - mary.deposit(100) - end - {Learn more}[link:classes/ActiveRecord/Transactions/ClassMethods.html] 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 @owner, and the actual associated + # object, known as the @target. The kind of association any proxy is + # about is available in @reflection. 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 blog.posts has the object in +blog+ as + # @owner, the collection of its posts as @target, and + # the @reflection object represents a :has_many macro. + # + # This class has most of the basic instance methods removed, and delegates + # unknown methods to @target via method_missing. As a + # corner case, it even removes the +class+ method and that's why you get + # + # blog.posts.class # => Array + # + # though the object behind blog.posts is not an Array, but an + # ActiveRecord::Associations::HasManyAssociation. + # + # The @target 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 :name 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 + # [: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 # 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, composed_of :balance, :class_name => 'Money' will return + # :balance or for has_many :clients it will return :clients. 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, composed_of :balance, :class_name => 'Money' will return :composed_of + # or for has_many :clients will return :has_many. 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 { :class_name => "Money" } for + # composed_of :balance, :class_name => 'Money' or +{}+ for has_many :clients. + 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, composed_of :balance, :class_name => 'Money' returns the +Money+ + # class and has_many :clients returns the +Client+ class. def klass @klass ||= class_name.constantize end + # Returns the class name for the macro. For example, composed_of :balance, :class_name => 'Money' returns 'Money' + # and has_many :clients returns 'Client'. 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: # * in - An enumerable object of available items - # * message - Specifies a customer error message (default is: "is not included in the list") + # * message - Specifies a custom error message (default is: "is not included in the list") # * allow_nil - If set to true, skips this validation if the attribute is null (default is: false) # * allow_blank - If set to true, skips this validation if the attribute is blank (default is: false) # * if - Specifies a method, proc or string to call to determine if the validation should @@ -755,7 +755,7 @@ module ActiveRecord # # Configuration options: # * in - An enumerable object of items that the value shouldn't be part of - # * message - Specifies a customer error message (default is: "is reserved") + # * message - Specifies a custom error message (default is: "is reserved") # * allow_nil - If set to true, skips this validation if the attribute is null (default is: false) # * allow_blank - If set to true, skips this validation if the attribute is blank (default is: false) # * if - Specifies a method, proc or string to call to determine if the validation should -- cgit v1.2.3