Permalink
Browse files

Fix docs (closes #2491)

git-svn-id: http://svn-commit.rubyonrails.org/rails/trunk@2744 5ecf4fe2-1ee6-0310-87b1-e25e094e27de
  • Loading branch information...
dhh committed Oct 26, 2005
1 parent 475bd74 commit a8eea0b04b2989bd054d7c852d636f1cc5494957
@@ -6,7 +6,7 @@ def self.append_features(base)
base.extend(ClassMethods)
end
- # This act provides the capabilities for sorting and reordering a number of objects in list.
+ # This act provides the capabilities for sorting and reordering a number of objects in a list.
# The class that has this specified needs to have a "position" column defined as an integer on
# the mapped database table.
#
@@ -7,17 +7,17 @@ def self.append_features(base)
end
# This acts provides Nested Set functionality. Nested Set is similiar to Tree, but with
- # the added feature that you can select the children and all of it's descendants with
+ # the added feature that you can select the children and all of their descendents with
# a single query. A good use case for this is a threaded post system, where you want
# to display every reply to a comment without multiple selects.
#
# A google search for "Nested Set" should point you in the direction to explain the
- # data base theory. I figured a bunch of this from
+ # database theory. I figured out a bunch of this from
# http://threebit.net/tutorials/nestedset/tutorial1.html
#
- # Instead of picturing a leaf node structure with child pointing back to their parent,
+ # Instead of picturing a leaf node structure with children pointing back to their parent,
# the best way to imagine how this works is to think of the parent entity surrounding all
- # of it's children, and it's parent surrounding it, etc. Assuming that they are lined up
+ # of its children, and its parent surrounding it, etc. Assuming that they are lined up
# horizontally, we store the left and right boundries in the database.
#
# Imagine:
@@ -42,7 +42,7 @@ def self.append_features(base)
# | |___________________________| |___________________________| |
# |___________________________________________________________________|
#
- # The numbers represent the left and right boundries. The table them might
+ # The numbers represent the left and right boundries. The table then might
# look like this:
# ID | PARENT | LEFT | RIGHT | DATA
# 1 | 0 | 1 | 14 | root
@@ -63,10 +63,10 @@ def self.append_features(base)
# There are instance methods for all of these.
#
# The structure is good if you need to group things together; the downside is that
- # keeping data integrity is a pain, and both adding and removing and entry
+ # keeping data integrity is a pain, and both adding and removing an entry
# require a full table write.
#
- # This sets up a before_destroy trigger to prune the tree correctly if one of it's
+ # This sets up a before_destroy trigger to prune the tree correctly if one of its
# elements gets deleted.
#
module ClassMethods
@@ -134,10 +134,10 @@ def unknown?
end
- # Added a child to this object in the tree. If this object hasn't been initialized,
+ # Adds a child to this object in the tree. If this object hasn't been initialized,
# it gets set up as a root node. Otherwise, this method will update all of the
- # other elements in the tree and shift them to the right. Keeping everything
- # balanaced.
+ # other elements in the tree and shift them to the right, keeping everything
+ # balanced.
def add_child( child )
self.reload
child.reload
@@ -179,17 +179,17 @@ def children_count
return (self[right_col_name] - self[left_col_name] - 1)/2
end
- # Returns a set of itself and all of it's nested children
+ # Returns a set of itself and all of its nested children
def full_set
self.class.find(:all, :conditions => "#{scope_condition} AND (#{left_col_name} BETWEEN #{self[left_col_name]} and #{self[right_col_name]})" )
end
- # Returns a set of all of it's children and nested children
+ # Returns a set of all of its children and nested children
def all_children
self.class.find(:all, :conditions => "#{scope_condition} AND (#{left_col_name} > #{self[left_col_name]}) and (#{right_col_name} < #{self[right_col_name]})" )
end
- # Returns a set of only this entries immediate children
+ # Returns a set of only this entry's immediate children
def direct_children
self.class.find(:all, :conditions => "#{scope_condition} and #{parent_column} = #{self.id}")
end
@@ -6,8 +6,8 @@ def self.append_features(base)
base.extend(ClassMethods)
end
- # Specify this act if you want to model a tree structure by providing a parent association and an children
- # association. This act assumes that requires that you have a foreign key column, which by default is called parent_id.
+ # Specify this act if you want to model a tree structure by providing a parent association and a children
+ # association. This act requires that you have a foreign key column, which by default is called parent_id.
#
# class Category < ActiveRecord::Base
# acts_as_tree :order => "name"
@@ -30,13 +30,14 @@ def self.append_features(base)
#
# In addition to the parent and children associations, the following instance methods are added to the class
# after specifying the act:
- # * siblings: Return all the children of the parent excluding the current node ([ subchild2 ] when called from subchild1)
- # * ancestors: Returns all the ancestors of the current node ([child1, root] when called from subchild2)
- # * root: Returns the root of the current node (root when called from subchild2)
+ # * siblings : Returns all the children of the parent, excluding the current node ([ subchild2 ] when called from subchild1)
+ # * self_and_siblings : Returns all the children of the parent, including the current node ([ subchild1, subchild2 ] when called from subchild1)
+ # * ancestors : Returns all the ancestors of the current node ([child1, root] when called from subchild2)
+ # * root : Returns the root of the current node (root when called from subchild2)
module ClassMethods
# Configuration options are:
#
- # * <tt>foreign_key</tt> - specifies the column name to use for track of the tree (default: parent_id)
+ # * <tt>foreign_key</tt> - specifies the column name to use for tracking of the tree (default: parent_id)
# * <tt>order</tt> - makes it possible to sort the children according to this SQL snippet.
# * <tt>counter_cache</tt> - keeps a count in a children_count column if set to true (default: false).
def acts_as_tree(options = {})
@@ -7,8 +7,8 @@ def self.append_features(base)
# Active Record implements aggregation through a macro-like class method called +composed_of+ for representing attributes
# as value objects. It expresses relationships like "Account [is] composed of Money [among other things]" or "Person [is]
- # composed of [an] address". Each call to the macro adds a description on how the value objects are created from the
- # attributes of the entity object (when the entity is initialized either as a new object or from finding an existing)
+ # composed of [an] address". Each call to the macro adds a description of how the value objects are created from the
+ # attributes of the entity object (when the entity is initialized either as a new object or from finding an existing object)
# and how it can be turned back into attributes (when the entity is saved to the database). Example:
#
# class Customer < ActiveRecord::Base
@@ -88,8 +88,8 @@ def self.append_features(base)
# == Writing value objects
#
# Value objects are immutable and interchangeable objects that represent a given value, such as a Money object representing
- # $5. Two Money objects both representing $5 should be equal (through methods such == and <=> from Comparable if ranking makes
- # sense). This is unlike a entity objects where equality is determined by identity. An entity class such as Customer can
+ # $5. Two Money objects both representing $5 should be equal (through methods such as == and <=> from Comparable if ranking
+ # makes sense). This is unlike entity objects where equality is determined by identity. An entity class such as Customer can
# easily have two different objects that both have an address on Hyancintvej. Entity identity is determined by object or
# relational unique identifiers (such as primary keys). Normal ActiveRecord::Base classes are entity objects.
#
@@ -22,7 +22,7 @@ def clear_association_cache #:nodoc:
# Associations are a set of macro-like class methods for tying objects together through foreign keys. They express relationships like
# "Project has one Project Manager" or "Project belongs to a Portfolio". Each macro adds a number of methods to the class which are
- # specialized according to the collection or association symbol and the options hash. It works much the same was as Ruby's own attr*
+ # specialized according to the collection or association symbol and the options hash. It works much the same way as Ruby's own attr*
# methods. Example:
#
# class Project < ActiveRecord::Base
@@ -80,7 +80,7 @@ def clear_association_cache #:nodoc:
#
# === One-to-one associations
#
- # * Assigning an object to a has_one association automatically saves that object, and the object being replaced (if there is one), in
+ # * Assigning an object to a has_one association automatically saves that object and the object being replaced (if there is one), in
# order to update their primary keys - except if the parent object is unsaved (new_record? == true).
# * If either of these saves fail (due to one of the objects being invalid) the assignment statement returns false and the assignment
# is cancelled.
@@ -164,8 +164,8 @@ def clear_association_cache #:nodoc:
#
# That'll add another join along the lines of: LEFT OUTER JOIN comments ON comments.post_id = posts.id. And we'll be down to 1 query.
# But that shouldn't fool you to think that you can pull out huge amounts of data with no performance penalty just because you've reduced
- # the number of queries. The database still needs to send all the data to Active Record and it still needs to be processed. So its no
- # catch-all for performance problems, but its a great way to cut down on the number of queries in a situation as the one described above.
+ # the number of queries. The database still needs to send all the data to Active Record and it still needs to be processed. So it's no
+ # catch-all for performance problems, but it's a great way to cut down on the number of queries in a situation as the one described above.
#
# Please note that limited eager loading with has_many and has_and_belongs_to_many associations is not compatible with describing conditions
# on these eager tables. This will work:
@@ -240,10 +240,10 @@ module ClassMethods
# * <tt>collection.find</tt> - finds an associated object according to the same rules as Base.find.
# * <tt>collection.build(attributes = {})</tt> - returns a new object of the collection type that has been instantiated
# with +attributes+ and linked to this object through a foreign key but has not yet been saved. *Note:* This only works if an
- # associated object already exists, not if its nil!
+ # associated object already exists, not if it's nil!
# * <tt>collection.create(attributes = {})</tt> - returns a new object of the collection type that has been instantiated
# with +attributes+ and 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 its nil!
+ # *Note:* This only works if an associated object already exists, not if it's nil!
#
# Example: A Firm class declares <tt>has_many :clients</tt>, which will add:
# * <tt>Firm#clients</tt> (similar to <tt>Clients.find :all, :conditions => "firm_id = #{id}"</tt>)
@@ -271,15 +271,15 @@ module ClassMethods
# 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.
# * <tt>:dependent</tt> - if set to :destroy (or true) all the associated objects are destroyed
- # alongside this object. Also accepts :nullify which will set the associated objects foriegn key
+ # alongside this object. Also accepts :nullify which will set the associated object's foreign key
# field to NULL.
# May not be set if :exclusively_dependent is also set.
# * <tt>:exclusively_dependent</tt> - if set to true all the associated object are deleted in one SQL statement without having their
# before_destroy callback run. This should only be used on associations that depend solely on this class and don't need to do any
# clean-up in before_destroy. The upside is that it's much faster, especially if there's a counter_cache involved.
# May not be set if :dependent is also set.
# * <tt>:finder_sql</tt> - specify a complete SQL statement to fetch the association. This is a good way to go for complex
- # associations that depends on multiple tables. Note: When this option is used, +find_in_collection+ is _not_ added.
+ # associations that depend on multiple tables. Note: When this option is used, +find_in_collection+ is _not_ added.
# * <tt>:counter_sql</tt> - specify a complete SQL statement to fetch the size of the association. If +:finder_sql+ is
# specified but +:counter_sql+, +:counter_sql+ will be generated by replacing SELECT ... FROM with SELECT COUNT(*) FROM.
#
@@ -369,7 +369,7 @@ def has_many(association_id, options = {})
# sql fragment, such as "rank = 5".
# * <tt>:order</tt> - specify the order from which the associated object will be picked at the top. Specified as
# an "ORDER BY" sql fragment, such as "last_name, first_name DESC"
- # * <tt>:dependent</tt> - if set to :destroy (or true) all the associated object is destroyed when this object is. Also
+ # * <tt>:dependent</tt> - if set to :destroy (or true) all the associated objects are destroyed when this object is. Also,
# association is assigned.
# * <tt>:foreign_key</tt> - 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_one association will use "person_id"
@@ -558,8 +558,8 @@ def belongs_to(association_id, options = {})
# of this class in lower-case and "_id" suffixed. So a +Person+ class that makes a has_and_belongs_to_many association
# will use "person_id" as the default foreign_key.
# * <tt>:association_foreign_key</tt> - specify the association foreign key used for the association. By default this is
- # guessed to be the name of the associated class in lower-case and "_id" suffixed. So the associated class is +Project+
- # that makes a has_and_belongs_to_many association will use "project_id" as the default association foreign_key.
+ # guessed to be the name of the associated class in lower-case and "_id" suffixed. So if the associated class is +Project+,
+ # the has_and_belongs_to_many association will use "project_id" as the default association foreign_key.
# * <tt>:conditions</tt> - specify the conditions that the associated object must meet in order to be included as a "WHERE"
# sql fragment, such as "authorized = 1".
# * <tt>:order</tt> - specify the order in which the associated objects are returned as a "ORDER BY" sql fragment, such as "last_name, first_name DESC"
@@ -86,7 +86,7 @@ module ActiveRecord
#
# There are four types of callbacks accepted by the callback macros: Method references (symbol), callback objects,
# inline methods (using a proc), and inline eval methods (using a string). Method references and callback objects are the
- # recommended approaches, inline methods using a proc is some times appropriate (such as for creating mix-ins), and inline
+ # recommended approaches, inline methods using a proc are sometimes appropriate (such as for creating mix-ins), and inline
# eval methods are deprecated.
#
# The method reference callbacks work by specifying a protected or private method available in the object, like this:
@@ -153,7 +153,7 @@ module ActiveRecord
#
# == The after_find and after_initialize exceptions
#
- # Because after_find and after_initialize is called for each object instantiated found by a finder, such as Base.find(:all), we've had
+ # Because after_find and after_initialize are called for each object found and instantiated by a finder, such as Base.find(:all), we've had
# to implement a simple performance constraint (50% more speed on a simple test case). Unlike all the other callbacks, after_find and
# after_initialize will only be run if an explicit implementation is defined (<tt>def after_find</tt>). In that case, all of the
# callback types will be called.
@@ -263,10 +263,10 @@ def create_with_callbacks #:nodoc:
result
end
- # Is called _before_ Base.save on existing objects that has a record.
+ # Is called _before_ Base.save on existing objects that have a record.
def before_update() end
- # Is called _after_ Base.save on existing objects that has a record.
+ # Is called _after_ Base.save on existing objects that have a record.
def after_update() end
def update_with_callbacks #:nodoc:
@@ -291,11 +291,11 @@ def before_validation_on_create() end
def after_validation_on_create() end
# Is called _before_ Validations.validate (which is part of the Base.save call) on
- # existing objects that has a record.
+ # existing objects that have a record.
def before_validation_on_update() end
# Is called _after_ Validations.validate (which is part of the Base.save call) on
- # existing objects that has a record.
+ # existing objects that have a record.
def after_validation_on_update() end
def valid_with_callbacks #:nodoc:
Oops, something went wrong.

0 comments on commit a8eea0b

Please sign in to comment.