From 4d719c185ac17d30c624add296872111570bf5b6 Mon Sep 17 00:00:00 2001 From: "Hongli Lai (Phusion)" Date: Fri, 18 Jul 2008 22:15:02 +0200 Subject: Improve readability of ActiveRecord::Assocations.has_many's documentation. --- activerecord/lib/active_record/associations.rb | 133 +++++++++++++++++-------- 1 file changed, 89 insertions(+), 44 deletions(-) (limited to 'activerecord') diff --git a/activerecord/lib/active_record/associations.rb b/activerecord/lib/active_record/associations.rb index b0b5af8bce..53ca17511e 100755 --- a/activerecord/lib/active_record/associations.rb +++ b/activerecord/lib/active_record/associations.rb @@ -150,6 +150,7 @@ module ActiveRecord # #others.destroy_all | X | X | X # #others.find(*args) | X | X | X # #others.find_first | X | | + # #others.exist? | X | X | X # #others.uniq | X | X | X # #others.reset | X | X | X # @@ -612,31 +613,53 @@ module ActiveRecord # All of the association macros can be specialized through options. This makes cases more complex than the simple and guessable ones # possible. module ClassMethods - # Adds the following methods for retrieval and query of collections of associated objects: - # +collection+ is replaced with the symbol passed as the first argument, so - # has_many :clients would add among others clients.empty?. - # * collection(force_reload = false) - Returns an array of all the associated objects. + # Specifies a one-to-many association. The following methods for retrieval and query of + # collections of associated objects will be added: + # + # [collection(force_reload = false)] + # Returns an array of all the associated objects. # An empty array is returned if none are found. - # * collection<<(object, ...) - Adds one or more objects to the collection by setting their foreign keys to the collection's primary key. - # * collection.delete(object, ...) - Removes one or more objects from the collection by setting their foreign keys to +NULL+. + # [collection<<(object, ...)] + # Adds one or more objects to the collection by setting their foreign keys to the collection's primary key. + # [collection.delete(object, ...)] + # Removes one or more objects from the collection by setting their foreign keys to +NULL+. # This will also destroy the objects if they're declared as +belongs_to+ and dependent on this model. - # * collection=objects - Replaces the collections content by deleting and adding objects as appropriate. - # * collection_singular_ids - Returns an array of the associated objects' ids - # * collection_singular_ids=ids - Replace the collection with the objects identified by the primary keys in +ids+ - # * collection.clear - Removes every object from the collection. This destroys the associated objects if they - # are associated with :dependent => :destroy, deletes them directly from the database if :dependent => :delete_all, - # otherwise sets their foreign keys to +NULL+. - # * collection.empty? - Returns +true+ if there are no associated objects. - # * collection.size - Returns the number of associated objects. - # * collection.find - Finds an associated object according to the same rules as Base.find. - # * collection.build(attributes = {}, ...) - Returns one or more new objects of the collection type that have been instantiated - # with +attributes+ and linked to this object through a foreign key, but have not yet been saved. *Note:* This only works if an - # associated object already exists, not if it's +nil+! - # * collection.create(attributes = {}) - Returns a new object of the collection type that has been instantiated - # with +attributes+, linked to this object through a foreign key, and that has already been saved (if it passed the validation). - # *Note:* This only works if an associated object already exists, not if it's +nil+! + # [collection=objects] + # Replaces the collections content by deleting and adding objects as appropriate. + # [collection_singular_ids] + # Returns an array of the associated objects' ids + # [collection_singular_ids=ids] + # Replace the collection with the objects identified by the primary keys in +ids+ + # [collection.clear] + # Removes every object from the collection. This destroys the associated objects if they + # are associated with :dependent => :destroy, deletes them directly from the + # database if :dependent => :delete_all, otherwise sets their foreign keys to +NULL+. + # [collection.empty?] + # Returns +true+ if there are no associated objects. + # [collection.size] + # Returns the number of associated objects. + # [collection.find(...)] + # Finds an associated object according to the same rules as Base.find. + # [collection.exist?(...)] + # Checks whether an associated object with the given conditions exists. + # Uses the same rules as Base.exists?. + # [collection.build(attributes = {}, ...)] + # Returns one or more new objects of the collection type that have been instantiated + # with +attributes+ and linked to this object through a foreign key, but have not yet + # been saved. *Note:* This only works if an associated object already exists, not if + # it's +nil+! + # [collection.create(attributes = {})] + # Returns a new object of the collection type that has been instantiated + # with +attributes+, linked to this object through a foreign key, and that has already + # been saved (if it passed the validation). *Note:* This only works if an associated + # object already exists, not if it's +nil+! + # + # (*Note*: +collection+ is replaced with the symbol passed as the first argument, so + # has_many :clients would add among others clients.empty?.) # - # Example: A Firm class declares has_many :clients, which will add: + # === Example + # + # A Firm class declares has_many :clients, which will add: # * Firm#clients (similar to Clients.find :all, :conditions => "firm_id = #{id}") # * Firm#clients<< # * Firm#clients.delete @@ -647,52 +670,74 @@ module ActiveRecord # * Firm#clients.empty? (similar to firm.clients.size == 0) # * Firm#clients.size (similar to Client.count "firm_id = #{id}") # * Firm#clients.find (similar to Client.find(id, :conditions => "firm_id = #{id}")) + # * Firm#clients.exist?(:name => 'ACME') (similar to Client.exist?(:name => 'ACME', :firm_id => firm.id)) # * Firm#clients.build (similar to Client.new("firm_id" => id)) # * Firm#clients.create (similar to c = Client.new("firm_id" => id); c.save; c) # The declaration can also include an options hash to specialize the behavior of the association. # - # Options are: - # * :class_name - Specify the class name of the association. Use it only if that name can't be inferred + # === Supported options + # [:class_name] + # Specify the class name of the association. Use it only if that name can't be inferred # from the association name. So has_many :products will by default be linked to the Product class, but # if the real class name is SpecialProduct, you'll have to specify it with this option. - # * :conditions - Specify the conditions that the associated objects must meet in order to be included as a +WHERE+ + # [:conditions] + # Specify the conditions that the associated objects must meet in order to be included as a +WHERE+ # SQL fragment, such as price > 5 AND name LIKE 'B%'. Record creations from the association are scoped if a hash # is used. has_many :posts, :conditions => {:published => true} will create published posts with @blog.posts.create # or @blog.posts.build. - # * :order - Specify the order in which the associated objects are returned as an ORDER BY SQL fragment, + # [:order] + # Specify the order in which the associated objects are returned as an ORDER BY SQL fragment, # such as last_name, first_name DESC. - # * :foreign_key - Specify the foreign key used for the association. By default this is guessed to be the name + # [:foreign_key] + # Specify the foreign key used for the association. By default this is guessed to be the name # of this class in lower-case and "_id" suffixed. So a Person class that makes a +has_many+ association will use "person_id" # as the default :foreign_key. - # * :primary_key - Specify the method that returns the primary key used for the association. By default this is +id+. - # * :dependent - If set to :destroy all the associated objects are destroyed + # [:primary_key] + # Specify the method that returns the primary key used for the association. By default this is +id+. + # [:dependent] + # If set to :destroy all the associated objects are destroyed # alongside this object by calling their +destroy+ method. If set to :delete_all all associated # objects are deleted *without* calling their +destroy+ method. If set to :nullify all associated # objects' foreign keys are set to +NULL+ *without* calling their +save+ callbacks. *Warning:* This option is ignored when also using # the :through option. - # * :finder_sql - Specify a complete SQL statement to fetch the association. This is a good way to go for complex + # [:finder_sql] + # Specify a complete SQL statement to fetch the association. This is a good way to go for complex # associations that depend on multiple tables. Note: When this option is used, +find_in_collection+ is _not_ added. - # * :counter_sql - Specify a complete SQL statement to fetch the size of the association. If :finder_sql is + # [:counter_sql] + # Specify a complete SQL statement to fetch the size of the association. If :finder_sql is # specified but not :counter_sql, :counter_sql will be generated by replacing SELECT ... FROM with SELECT COUNT(*) FROM. - # * :extend - Specify a named module for extending the proxy. See "Association extensions". - # * :include - Specify second-order associations that should be eager loaded when the collection is loaded. - # * :group - An attribute name by which the result should be grouped. Uses the GROUP BY SQL-clause. - # * :limit - An integer determining the limit on the number of rows that should be returned. - # * :offset - An integer determining the offset from where the rows should be fetched. So at 5, it would skip the first 4 rows. - # * :select - By default, this is * as in SELECT * FROM, but can be changed if you, for example, want to do a join + # [:extend] + # Specify a named module for extending the proxy. See "Association extensions". + # [:include] + # Specify second-order associations that should be eager loaded when the collection is loaded. + # [:group] + # An attribute name by which the result should be grouped. Uses the GROUP BY SQL-clause. + # [:limit] + # An integer determining the limit on the number of rows that should be returned. + # [:offset] + # An integer determining the offset from where the rows should be fetched. So at 5, it would skip the first 4 rows. + # [:select] + # By default, this is * as in SELECT * FROM, but can be changed if you, for example, want to do a join # but not include the joined columns. Do not forget to include the primary and foreign keys, otherwise it will raise an error. - # * :as - Specifies a polymorphic interface (See belongs_to). - # * :through - Specifies a Join Model through which to perform the query. Options for :class_name and :foreign_key + # [:as] + # Specifies a polymorphic interface (See belongs_to). + # [:through] + # Specifies a Join Model through which to perform the query. Options for :class_name and :foreign_key # are ignored, as the association uses the source reflection. You can only use a :through query through a belongs_to # or has_many association on the join model. - # * :source - Specifies the source association name used by has_many :through queries. Only use it if the name cannot be + # [:source] + # Specifies the source association name used by has_many :through queries. Only use it if the name cannot be # inferred from the association. has_many :subscribers, :through => :subscriptions will look for either :subscribers or # :subscriber on Subscription, unless a :source is given. - # * :source_type - Specifies type of the source association used by has_many :through queries where the source + # [:source_type] + # Specifies type of the source association used by has_many :through queries where the source # association is a polymorphic +belongs_to+. - # * :uniq - If true, duplicates will be omitted from the collection. Useful in conjunction with :through. - # * :readonly - If true, all the associated objects are readonly through the association. - # * :validate - If false, don't validate the associated objects when saving the parent object. true by default. + # [:uniq] + # If true, duplicates will be omitted from the collection. Useful in conjunction with :through. + # [:readonly] + # If true, all the associated objects are readonly through the association. + # [:validate] + # If false, don't validate the associated objects when saving the parent object. true by default. # # Option examples: # has_many :comments, :order => "posted_on" -- cgit v1.2.3