Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Browse files

Smattering of grammatical fixes to documentation. Closes #10083 [BobS…

…ilva]

git-svn-id: http://svn-commit.rubyonrails.org/rails/trunk@8113 5ecf4fe2-1ee6-0310-87b1-e25e094e27de
  • Loading branch information...
commit 7143d80147ea26c66dfa1dd4bb82f066d72f6570 1 parent 709dc33
Marcel Molina authored
Showing with 109 additions and 96 deletions.
  1. +2 −0  activerecord/CHANGELOG
  2. +14 −15 activerecord/lib/active_record/associations.rb
  3. +35 −27 activerecord/lib/active_record/base.rb
  4. +13 −10 activerecord/lib/active_record/calculations.rb
  5. +1 −1  activerecord/lib/active_record/callbacks.rb
  6. +4 −4 activerecord/lib/active_record/connection_adapters/abstract/connection_specification.rb
  7. +3 −2 activerecord/lib/active_record/connection_adapters/abstract/database_statements.rb
  8. +2 −2 activerecord/lib/active_record/connection_adapters/abstract/schema_definitions.rb
  9. +3 −3 activerecord/lib/active_record/connection_adapters/abstract/schema_statements.rb
  10. +8 −8 activerecord/lib/active_record/connection_adapters/postgresql_adapter.rb
  11. +1 −1  activerecord/lib/active_record/connection_adapters/sqlite_adapter.rb
  12. +7 −7 activerecord/lib/active_record/fixtures.rb
  13. +6 −6 activerecord/lib/active_record/migration.rb
  14. +2 −2 activerecord/lib/active_record/reflection.rb
  15. +2 −2 activerecord/lib/active_record/serializers/xml_serializer.rb
  16. +2 −2 activerecord/lib/active_record/timestamp.rb
  17. +1 −1  activerecord/lib/active_record/transactions.rb
  18. +3 −3 activerecord/lib/active_record/validations.rb
View
2  activerecord/CHANGELOG
@@ -1,5 +1,7 @@
*SVN*
+* Smattering of grammatical fixes to documentation. Closes #10083 [BobSilva]
+
* Enhance explanation with more examples for attr_accessible macro. Closes #8095 [fearoffish, Marcel Molina]
* Update association/method mapping table to refected latest collection methods for has_many :through. Closes #8772 [lifofifo]
View
29 activerecord/lib/active_record/associations.rb
@@ -243,7 +243,7 @@ def clear_association_cache #:nodoc:
#
# == Unsaved objects and associations
#
- # You can manipulate objects and associations before they are saved to the database, but there is some special behaviour you should be
+ # You can manipulate objects and associations before they are saved to the database, but there is some special behavior you should be
# aware of, mostly involving the saving of associated objects.
#
# === One-to-one associations
@@ -267,7 +267,7 @@ def clear_association_cache #:nodoc:
# === Association callbacks
#
# Similiar to the normal callbacks that hook into the lifecycle of an Active Record object, you can also define callbacks that get
- # trigged when you add an object to or remove an object from an association collection. Example:
+ # triggered when you add an object to or remove an object from an association collection. Example:
#
# class Project
# has_and_belongs_to_many :developers, :after_add => :evaluate_velocity
@@ -584,10 +584,10 @@ module ClassMethods
# This will also destroy the objects if they're declared as +belongs_to+ and dependent on this model.
# * <tt>collection=objects</tt> - replaces the collections content by deleting and adding objects as appropriate.
# * <tt>collection_singular_ids</tt> - returns an array of the associated objects' ids
- # * <tt>collection_singular_ids=ids</tt> - replace the collection by the objects identified by the primary keys in +ids+
+ # * <tt>collection_singular_ids=ids</tt> - replace the collection with the objects identified by the primary keys in +ids+
# * <tt>collection.clear</tt> - removes every object from the collection. This destroys the associated objects if they
# are associated with <tt>:dependent => :destroy</tt>, deletes them directly from the database if <tt>:dependent => :delete_all</tt>,
- # or otherwise sets their foreign keys to NULL.
+ # otherwise sets their foreign keys to NULL.
# * <tt>collection.empty?</tt> - returns +true+ if there are no associated objects.
# * <tt>collection.size</tt> - returns the number of associated objects.
# * <tt>collection.find</tt> - finds an associated object according to the same rules as Base.find.
@@ -621,8 +621,6 @@ module ClassMethods
# SQL fragment, such as <tt>price > 5 AND name LIKE 'B%'</tt>.
# * <tt>:order</tt> - specify the order in which the associated objects are returned as an <tt>ORDER BY</tt> SQL fragment,
# such as <tt>last_name, first_name DESC</tt>
- # * <tt>:group</tt> - specify the attribute by which the associated objects are returned as a <tt>GROUP BY</tt> SQL fragment,
- # such as +category+
# * <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_many+ association will use +person_id+
# as the default +foreign_key+.
@@ -633,13 +631,13 @@ module ClassMethods
# * <tt>:finder_sql</tt> - 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.
# * <tt>:counter_sql</tt> - specify a complete SQL statement to fetch the size of the association. If <tt>:finder_sql</tt> is
- # specified but <tt>:counter_sql</tt>, <tt>:counter_sql</tt> will be generated by replacing <tt>SELECT ... FROM</tt> with <tt>SELECT COUNT(*) FROM</tt>.
+ # specified but not <tt>:counter_sql</tt>, <tt>:counter_sql</tt> will be generated by replacing <tt>SELECT ... FROM</tt> with <tt>SELECT COUNT(*) FROM</tt>.
# * <tt>:extend</tt> - specify a named module for extending the proxy. See "Association extensions".
# * <tt>:include</tt> - specify second-order associations that should be eager loaded when the collection is loaded.
# * <tt>:group</tt>: An attribute name by which the result should be grouped. Uses the <tt>GROUP BY</tt> SQL-clause.
# * <tt>:limit</tt>: An integer determining the limit on the number of rows that should be returned.
# * <tt>:offset</tt>: An integer determining the offset from where the rows should be fetched. So at 5, it would skip the first 4 rows.
- # * <tt>:select</tt>: By default, this is <tt>*</tt> as in <tt>SELECT * FROM</tt>, but can be changed if you for example want to do a join,
+ # * <tt>:select</tt>: By default, this is <tt>*</tt> as in <tt>SELECT * FROM</tt>, but can be changed if you, for example, want to do a join
# but not include the joined columns.
# * <tt>:as</tt>: Specifies a polymorphic interface (See <tt>#belongs_to</tt>).
# * <tt>:through</tt>: Specifies a Join Model through which to perform the query. Options for <tt>:class_name</tt> and <tt>:foreign_key</tt>
@@ -708,8 +706,8 @@ def has_many(association_id, options = {}, &extension)
# if the real class name is +Person+, you'll have to specify it with this option.
# * <tt>:conditions</tt> - specify the conditions that the associated object must meet in order to be included as a +WHERE+
# SQL fragment, such as <tt>rank = 5</tt>.
- # * <tt>:order</tt> - specify the order from which the associated object will be picked at the top. Specified as
- # an <tt>ORDER BY</tt> SQL fragment, such as <tt>last_name, first_name DESC</tt>
+ # * <tt>:order</tt> - specify the order in which the associated objects are returned as an <tt>ORDER BY</tt> SQL fragment,
+ # such as <tt>last_name, first_name DESC</tt>
# * <tt>:dependent</tt> - if set to <tt>:destroy</tt>, the associated object is destroyed when this object is. If set to
# <tt>:delete</tt>, the associated object is deleted *without* calling its destroy method. If set to <tt>:nullify</tt>, the associated
# object's foreign key is set to +NULL+. Also, association is assigned.
@@ -721,7 +719,7 @@ def has_many(association_id, options = {}, &extension)
#
# Option examples:
# has_one :credit_card, :dependent => :destroy # destroys the associated credit card
- # has_one :credit_card, :dependent => :nullify # updates the associated records foreign key value to null rather than destroying it
+ # has_one :credit_card, :dependent => :nullify # updates the associated records foreign key value to NULL rather than destroying it
# has_one :last_comment, :class_name => "Comment", :order => "posted_on"
# has_one :project_manager, :class_name => "Person", :conditions => "role = 'project_manager'"
# has_one :attachment, :as => :attachable
@@ -771,12 +769,12 @@ def has_one(association_id, options = {})
# if the real class name is +Person+, you'll have to specify it with this option.
# * <tt>:conditions</tt> - specify the conditions that the associated object must meet in order to be included as a +WHERE+
# SQL fragment, such as <tt>authorized = 1</tt>.
- # * <tt>:order</tt> - specify the order from which the associated object will be picked at the top. Specified as
- # an <tt>ORDER BY</tt> SQL fragment, such as <tt>last_name, first_name DESC</tt>
+ # * <tt>:order</tt> - specify the order in which the associated objects are returned as an <tt>ORDER BY</tt> SQL fragment,
+ # such as <tt>last_name, first_name DESC</tt>
# * <tt>:foreign_key</tt> - specify the 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 a +Person+ class that makes a +belongs_to+ association to a
# +Boss+ class will use +boss_id+ as the default +foreign_key+.
- # * <tt>:counter_cache</tt> - caches the number of belonging objects on the associate class through use of +increment_counter+
+ # * <tt>:counter_cache</tt> - caches the number of belonging objects on the associate class through the use of +increment_counter+
# and +decrement_counter+. The counter cache is incremented when an object of this class is created and decremented when it's
# destroyed. This requires that a column named <tt>#{table_name}_count</tt> (such as +comments_count+ for a belonging +Comment+ class)
# is used on the associate class (such as a +Post+ class). You can also specify a custom counter cache column by providing
@@ -924,7 +922,8 @@ def belongs_to(association_id, options = {})
# 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 <tt>authorized = 1</tt>.
- # * <tt>:order</tt> - specify the order in which the associated objects are returned as a <tt>ORDER BY</tt> SQL fragment, such as <tt>last_name, first_name DESC</tt>
+ # * <tt>:order</tt> - specify the order in which the associated objects are returned as an <tt>ORDER BY</tt> SQL fragment,
+ # such as <tt>last_name, first_name DESC</tt>
# * <tt>:uniq</tt> - if set to +true+, duplicate associated objects will be ignored by accessors and query methods
# * <tt>:finder_sql</tt> - overwrite the default generated SQL statement used to fetch the association with a manual statement
# * <tt>:delete_sql</tt> - overwrite the default generated SQL statement used to remove links between the associated
View
62 activerecord/lib/active_record/base.rb
@@ -40,7 +40,7 @@ class ProtectedAttributeAssignmentError < ActiveRecordError #:nodoc:
class DangerousAttributeError < ActiveRecordError #:nodoc:
end
- # Raised when you've tried to access a column, which wasn't
+ # Raised when you've tried to access a column which wasn't
# loaded by your finder. Typically this is because :select
# has been specified
class MissingAttributeError < NoMethodError
@@ -72,7 +72,7 @@ def initialize(errors)
# == Creation
#
# Active Records accept constructor parameters either in a hash or as a block. The hash method is especially useful when
- # you're receiving the data from somewhere else, like a HTTP request. It works like this:
+ # you're receiving the data from somewhere else, like an HTTP request. It works like this:
#
# user = User.new(:name => "David", :occupation => "Code Artist")
# user.name # => "David"
@@ -112,7 +112,7 @@ def initialize(errors)
# end
#
# The <tt>authenticate_unsafely</tt> method inserts the parameters directly into the query and is thus susceptible to SQL-injection
- # attacks if the <tt>user_name</tt> and +password+ parameters come directly from a HTTP request. The <tt>authenticate_safely</tt> and
+ # attacks if the <tt>user_name</tt> and +password+ parameters come directly from an HTTP request. The <tt>authenticate_safely</tt> and
# <tt>authenticate_safely_simply</tt> both will sanitize the <tt>user_name</tt> and +password+ before inserting them in the query,
# which will ensure that an attacker can't escape the query and fake the login (or worse).
#
@@ -137,9 +137,9 @@ def initialize(errors)
#
# == Overwriting default accessors
#
- # All column values are automatically available through basic accessors on the Active Record object, but some times you
- # want to specialize this behavior. This can be done by either by overwriting the default accessors (using the same
- # name as the attribute) calling read_attribute(attr_name) and write_attribute(attr_name, value) to actually change things.
+ # All column values are automatically available through basic accessors on the Active Record object, but sometimes you
+ # want to specialize this behavior. This can be done by overwriting the default accessors (using the same
+ # name as the attribute) and calling read_attribute(attr_name) and write_attribute(attr_name, value) to actually change things.
# Example:
#
# class Song < ActiveRecord::Base
@@ -230,7 +230,7 @@ def initialize(errors)
#
# == Single table inheritance
#
- # Active Record allows inheritance by storing the name of the class in a column that by default is called "type" (can be changed
+ # Active Record allows inheritance by storing the name of the class in a column that by default is named "type" (can be changed
# by overwriting <tt>Base.inheritance_column</tt>). This means that an inheritance looking like this:
#
# class Company < ActiveRecord::Base; end
@@ -251,7 +251,7 @@ def initialize(errors)
#
# Connections are usually created through ActiveRecord::Base.establish_connection and retrieved by ActiveRecord::Base.connection.
# All classes inheriting from ActiveRecord::Base will use this connection. But you can also set a class-specific connection.
- # For example, if Course is a ActiveRecord::Base, but resides in a different database you can just say Course.establish_connection
+ # For example, if Course is an ActiveRecord::Base, but resides in a different database, you can just say Course.establish_connection
# and Course *and all its subclasses* will use this connection instead.
#
# This feature is implemented by keeping a connection pool in ActiveRecord::Base that is a Hash indexed by the class. If a connection is
@@ -260,12 +260,12 @@ def initialize(errors)
# == Exceptions
#
# * +ActiveRecordError+ -- generic error class and superclass of all other errors raised by Active Record
- # * +AdapterNotSpecified+ -- the configuration hash used in <tt>establish_connection</tt> didn't include a
+ # * +AdapterNotSpecified+ -- the configuration hash used in <tt>establish_connection</tt> didn't include an
# <tt>:adapter</tt> key.
- # * +AdapterNotFound+ -- the <tt>:adapter</tt> key used in <tt>establish_connection</tt> specified an non-existent adapter
+ # * +AdapterNotFound+ -- the <tt>:adapter</tt> key used in <tt>establish_connection</tt> specified a non-existent adapter
# (or a bad spelling of an existing one).
# * +AssociationTypeMismatch+ -- the object assigned to the association wasn't of the type specified in the association definition.
- # * +SerializationTypeMismatch+ -- the object serialized wasn't of the class specified as the second parameter.
+ # * +SerializationTypeMismatch+ -- the serialized object wasn't of the class specified as the second parameter.
# * +ConnectionNotEstablished+ -- no connection has been established. Use <tt>establish_connection</tt> before querying.
# * +RecordNotFound+ -- no record responded to the find* method.
# Either the row with the given ID doesn't exist or the row didn't meet the additional restrictions.
@@ -360,7 +360,7 @@ def self.reset_subclasses #:nodoc:
@@schema_format = :ruby
# Determines whether to raise an exception on mass-assignment to protected
- # attribute. Defaults to true.
+ # attributes. Defaults to true.
cattr_accessor :whiny_protected_attributes, :instance_writer => false
@@whiny_protected_attributes = true
@@ -370,10 +370,10 @@ class << self # Class methods
# * Find by id: This can either be a specific id (1), a list of ids (1, 5, 6), or an array of ids ([5, 6, 10]).
# If no record can be found for all of the listed ids, then RecordNotFound will be raised.
# * Find first: This will return the first record matched by the options used. These options can either be specific
- # conditions or merely an order. If no record can matched, nil is returned.
+ # conditions or merely an order. If no record can be matched, nil is returned.
# * Find all: This will return all the records matched by the options used. If no records are found, an empty array is returned.
#
- # All approaches accept an option hash as their last parameter. The options are:
+ # All approaches accept an options hash as their last parameter. The options are:
#
# * <tt>:conditions</tt>: An SQL fragment like "administrator = 1" or [ "user_name = ?", username ]. See conditions in the intro.
# * <tt>:order</tt>: An SQL fragment like "created_at DESC, name".
@@ -384,9 +384,10 @@ class << self # Class methods
# Accepts named associations in the form of :include, which will perform an INNER JOIN on the associated table(s).
# The records will be returned read-only since they will have attributes that do not correspond to the table's columns.
# Pass :readonly => false to override.
+ # See adding joins for associations under Associations.
# * <tt>:include</tt>: Names associations that should be loaded alongside using LEFT OUTER JOINs. The symbols named refer
# to already defined associations. See eager loading under Associations.
- # * <tt>:select</tt>: By default, this is * as in SELECT * FROM, but can be changed if you for example want to do a join, but not
+ # * <tt>:select</tt>: 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.
# * <tt>:from</tt>: By default, this is the table name of the class, but can be changed to an alternate table name (or even the name
# of a database view).
@@ -398,7 +399,7 @@ class << self # Class methods
# Person.find(1) # returns the object for ID = 1
# Person.find(1, 2, 6) # returns an array for objects with IDs in (1, 2, 6)
# Person.find([7, 17]) # returns an array for objects with IDs in (7, 17)
- # Person.find([1]) # returns an array for objects the object with ID = 1
+ # Person.find([1]) # returns an array for the object with ID = 1
# Person.find(1, :conditions => "administrator = 1", :order => "created_on DESC")
#
# Note that returned records may not be in the same order as the ids you
@@ -429,6 +430,13 @@ class << self # Class methods
# end
def find(*args)
options = args.extract_options!
+ # Note: we extract any :joins option with a non-string value from the options, and turn it into
+ # an internal option :ar_joins. This allows code called from here to find the ar_joins, and
+ # it bypasses marking the result as read_only.
+ # A normal string join marks the result as read-only because it contains attributes from joined tables
+ # which are not in the base table and therefore prevent the result from being saved.
+ # In the case of an ar_join, the JoinDependency created to instantiate the results eliminates these
+ # bogus attributes. See JoinDependency#instantiate, and JoinBase#instantiate in associations.rb.
validate_find_options(options)
set_readonly_option!(options)
@@ -521,14 +529,14 @@ def update_all(updates, conditions = nil, options = {})
connection.update(sql, "#{name} Update")
end
- # Destroys the objects for all the records that match the +condition+ by instantiating each object and calling
+ # Destroys the objects for all the records that match the +conditions+ by instantiating each object and calling
# the destroy method. Example:
# Person.destroy_all "last_login < '2004-04-04'"
def destroy_all(conditions = nil)
find(:all, :conditions => conditions).each { |object| object.destroy }
end
- # Deletes all the records that match the +condition+ without instantiating the objects first (and hence not
+ # Deletes all the records that match the +conditions+ without instantiating the objects first (and hence not
# calling the destroy method). Example:
# Post.delete_all "person_id = 5 AND (category = 'Something' OR category = 'Else')"
def delete_all(conditions = nil)
@@ -576,7 +584,7 @@ def update_counters(id, counters)
#
# This is used for caching aggregate values, so that they don't need to be computed every time.
# For example, a DiscussionBoard may cache post_count and comment_count otherwise every time the board is
- # shown it would have to run a SQL query to find how many posts and comments there are.
+ # shown it would have to run an SQL query to find how many posts and comments there are.
#
# ==== Options
#
@@ -687,7 +695,7 @@ def readonly_attributes
# ==== Options
#
# +attr_name+ The field name that should be serialized
- # +class_name+ Optional, class name that the object should be equal to
+ # +class_name+ Optional, class name that the object type should be equal to
#
# ==== Example
# # Serialize a preferences attribute
@@ -707,7 +715,7 @@ def serialized_attributes
# Guesses the table name (in forced lower-case) based on the name of the class in the inheritance hierarchy descending
# directly from ActiveRecord. So if the hierarchy looks like: Reply < Message < ActiveRecord, then Message is used
# to guess the table name from even when called on Reply. The rules used to do the guess are handled by the Inflector class
- # in Active Support, which knows almost all common English inflections (report a bug if your inflection isn't covered).
+ # in Active Support, which knows almost all common English inflections. You can add new inflections in config/initializers/inflections.rb.
#
# Nested classes are given table names prefixed by the singular form of
# the parent's table name. Example:
@@ -964,7 +972,7 @@ def quote_value(value, column = nil) #:nodoc:
connection.quote(value,column)
end
- # Used to sanitize objects before they're used in an SELECT SQL-statement. Delegates to <tt>connection.quote</tt>.
+ # Used to sanitize objects before they're used in an SQL SELECT statement. Delegates to <tt>connection.quote</tt>.
def sanitize(object) #:nodoc:
connection.quote(object)
end
@@ -1266,7 +1274,7 @@ def undecorated_table_name(class_name = base_class.name)
# Enables dynamic finders like find_by_user_name(user_name) and find_by_user_name_and_password(user_name, password) that are turned into
# find(:first, :conditions => ["user_name = ?", user_name]) and find(:first, :conditions => ["user_name = ? AND password = ?", user_name, password])
- # respectively. Also works for find(:all), but using find_all_by_amount(50) that are turned into find(:all, :conditions => ["amount = ?", 50]).
+ # respectively. Also works for find(:all) by using find_all_by_amount(50) that is turned into find(:all, :conditions => ["amount = ?", 50]).
#
# It's even possible to use all the additional parameters to find. For example, the full interface for find_all_by_amount
# is actually find_all_by_amount(amount, options).
@@ -1435,7 +1443,7 @@ def define_attr_method(name, value=nil, &block)
# end
# end
#
- # You can ignore any previous scopings by using <tt>with_exclusive_scope</tt> method.
+ # You can ignore any previous scopings by using the <tt>with_exclusive_scope</tt> method.
#
# class Article < ActiveRecord::Base
# def self.find_with_exclusive_scope
@@ -1889,7 +1897,7 @@ def []=(attr_name, value)
# Allows you to set all the attributes at once by passing in a hash with keys
# matching the attribute names (which again matches the column names). Sensitive attributes can be protected
# from this form of mass-assignment by using the +attr_protected+ macro. Or you can alternatively
- # specify which attributes *can* be accessed in with the +attr_accessible+ macro. Then all the
+ # specify which attributes *can* be accessed with the +attr_accessible+ macro. Then all the
# attributes not included in that won't be allowed to be mass-assigned.
def attributes=(new_attributes, guard_protected_attributes = true)
return if new_attributes.nil?
@@ -2120,7 +2128,7 @@ def attributes_protected_by_default
default
end
- # Returns copy of the attributes hash where all the values have been safely quoted for use in
+ # Returns a copy of the attributes hash where all the values have been safely quoted for use in
# an SQL statement.
def attributes_with_quotes(include_primary_key = true, include_readonly_attributes = true)
quoted = attributes.inject({}) do |quoted, (name, value)|
@@ -2159,7 +2167,7 @@ def attributes_from_column_definition
# So having the pairs written_on(1) = "2004", written_on(2) = "6", written_on(3) = "24", will instantiate
# written_on (a date type) with Date.new("2004", "6", "24"). You can also specify a typecast character in the
# parentheses to have the parameters typecasted before they're used in the constructor. Use i for Fixnum, f for Float,
- # s for String, and a for Array. If all the values for a given attribute is empty, the attribute will be set to nil.
+ # s for String, and a for Array. If all the values for a given attribute are empty, the attribute will be set to nil.
def assign_multiparameter_attributes(pairs)
execute_callstack_for_multiparameter_attributes(
extract_callstack_for_multiparameter_attributes(pairs)
View
23 activerecord/lib/active_record/calculations.rb
@@ -15,14 +15,17 @@ module ClassMethods
# The third approach, count using options, accepts an option hash as the only parameter. The options are:
#
# * <tt>:conditions</tt>: An SQL fragment like "administrator = 1" or [ "user_name = ?", username ]. See conditions in the intro.
- # * <tt>:joins</tt>: An SQL fragment for additional joins like "LEFT JOIN comments ON comments.post_id = id". (Rarely needed).
- # The records will be returned read-only since they will have attributes that do not correspond to the table's columns.
+ # * <tt>:joins</tt>: Either an SQL fragment for additional joins like "LEFT JOIN comments ON comments.post_id = id". (Rarely needed).
+ # or names associations in the same form used for the :include option.
+ # If the value is a string, then the records will be returned read-only since they will have attributes that do not correspond to the table's columns.
+ # Pass :readonly => false to override.
+ # See adding joins for associations under Associations.
# * <tt>:include</tt>: Named associations that should be loaded alongside using LEFT OUTER JOINs. The symbols named refer
- # to already defined associations. When using named associations count returns the number DISTINCT items for the model you're counting.
+ # to already defined associations. When using named associations, count returns the number of DISTINCT items for the model you're counting.
# See eager loading under Associations.
# * <tt>:order</tt>: An SQL fragment like "created_at DESC, name" (really only used with GROUP BY calculations).
# * <tt>:group</tt>: An attribute name by which the result should be grouped. Uses the GROUP BY SQL-clause.
- # * <tt>:select</tt>: By default, this is * as in SELECT * FROM, but can be changed if you for example want to do a join, but not
+ # * <tt>:select</tt>: 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.
# * <tt>:distinct</tt>: Set this to true to make this a distinct calculation, such as SELECT COUNT(DISTINCT posts.id) ...
#
@@ -44,35 +47,35 @@ def count(*args)
calculate(:count, *construct_count_options_from_args(*args))
end
- # Calculates average value on a given column. The value is returned as a float. See #calculate for examples with options.
+ # Calculates the average value on a given column. The value is returned as a float. See #calculate for examples with options.
#
# Person.average('age')
def average(column_name, options = {})
calculate(:avg, column_name, options)
end
- # Calculates the minimum value on a given column. The value is returned with the same data type of the column.. See #calculate for examples with options.
+ # Calculates the minimum value on a given column. The value is returned with the same data type of the column. See #calculate for examples with options.
#
# Person.minimum('age')
def minimum(column_name, options = {})
calculate(:min, column_name, options)
end
- # Calculates the maximum value on a given column. The value is returned with the same data type of the column.. See #calculate for examples with options.
+ # Calculates the maximum value on a given column. The value is returned with the same data type of the column. See #calculate for examples with options.
#
# Person.maximum('age')
def maximum(column_name, options = {})
calculate(:max, column_name, options)
end
- # Calculates the sum value on a given column. The value is returned with the same data type of the column.. See #calculate for examples with options.
+ # Calculates the sum of values on a given column. The value is returned with the same data type of the column. See #calculate for examples with options.
#
# Person.sum('age')
def sum(column_name, options = {})
calculate(:sum, column_name, options)
end
- # This calculates aggregate values in the given column: Methods for count, sum, average, minimum, and maximum have been added as shortcuts.
+ # This calculates aggregate values in the given column. Methods for count, sum, average, minimum, and maximum have been added as shortcuts.
# Options such as :conditions, :order, :group, :having, and :joins can be passed to customize the query.
#
# There are two basic forms of output:
@@ -237,7 +240,7 @@ def validate_calculation_options(operation, options = {})
end
# Converts a given key to the value that the database adapter returns as
- # as a usable column name.
+ # a usable column name.
# users.id #=> users_id
# sum(id) #=> sum_id
# count(distinct users.id) #=> count_distinct_users_id
View
2  activerecord/lib/active_record/callbacks.rb
@@ -161,7 +161,7 @@ module ActiveRecord
# == <tt>before_validation*</tt> returning statements
#
# If the returning value of a +before_validation+ callback can be evaluated to +false+, the process will be aborted and <tt>Base#save</tt> will return +false+.
- # If <tt>Base#save!</tt> is called it will raise a +RecordNotSave+ exception.
+ # If <tt>Base#save!</tt> is called it will raise a +RecordNotSaved+ exception.
# Nothing will be appended to the errors object.
#
# == Cancelling callbacks
View
8 activerecord/lib/active_record/connection_adapters/abstract/connection_specification.rb
@@ -243,7 +243,7 @@ def self.establish_connection(spec = nil)
end
# Locate the connection of the nearest super class. This can be an
- # active or defined connections: if it is the latter, it will be
+ # active or defined connection: if it is the latter, it will be
# opened and set as the active connection for the class it was defined
# for (not necessarily the current class).
def self.retrieve_connection #:nodoc:
@@ -264,15 +264,15 @@ def self.retrieve_connection #:nodoc:
conn or raise ConnectionNotEstablished
end
- # Returns true if a connection that's accessible to this class have already been opened.
+ # Returns true if a connection that's accessible to this class has already been opened.
def self.connected?
active_connections[active_connection_name] ? true : false
end
# Remove the connection for this class. This will close the active
# connection and the defined connection (if they exist). The result
- # can be used as argument for establish_connection, for easy
- # re-establishing of the connection.
+ # can be used as an argument for establish_connection, for easily
+ # re-establishing the connection.
def self.remove_connection(klass=self)
spec = @@defined_connections[klass.name]
konn = active_connections[klass.name]
View
5 activerecord/lib/active_record/connection_adapters/abstract/database_statements.rb
@@ -98,7 +98,7 @@ def add_limit!(sql, options)
add_limit_offset!(sql, options) if options
end
- # Appends +LIMIT+ and +OFFSET+ options to a SQL statement.
+ # Appends +LIMIT+ and +OFFSET+ options to an SQL statement.
# This method *modifies* the +sql+ parameter.
# ===== Examples
# add_limit_offset!('SELECT * FROM suppliers', {:limit => 10, :offset => 50})
@@ -113,7 +113,8 @@ def add_limit_offset!(sql, options)
end
end
- # Appends a locking clause to a SQL statement. *Modifies the +sql+ parameter*.
+ # Appends a locking clause to an SQL statement.
+ # This method *modifies* the +sql+ parameter.
# # SELECT * FROM suppliers FOR UPDATE
# add_lock! 'SELECT * FROM suppliers', :lock => true
# add_lock! 'SELECT * FROM suppliers', :lock => ' FOR UPDATE'
View
4 activerecord/lib/active_record/connection_adapters/abstract/schema_definitions.rb
@@ -272,7 +272,7 @@ def add_column_options!(sql, options)
end
# Represents a SQL table in an abstract way.
- # Columns are stored as ColumnDefinition in the #columns attribute.
+ # Columns are stored as a ColumnDefinition in the #columns attribute.
class TableDefinition
attr_accessor :columns
@@ -451,7 +451,7 @@ def references(*args)
alias :belongs_to :references
# Returns a String whose contents are the column definitions
- # concatenated together. This string can then be pre and appended to
+ # concatenated together. This string can then be prepended and appended to
# to generate the final SQL to create the table.
def to_sql
@columns * ', '
View
6 activerecord/lib/active_record/connection_adapters/abstract/schema_statements.rb
@@ -54,7 +54,7 @@ def columns(table_name, name = nil) end
# [<tt>:temporary</tt>]
# Make a temporary table.
# [<tt>:force</tt>]
- # Set to true or false to drop the table before creating it.
+ # Set to true to drop the table before creating it.
# Defaults to false.
#
# ===== Examples
@@ -160,13 +160,13 @@ def rename_column(table_name, column_name, new_column_name)
# Adds a new index to the table. +column_name+ can be a single Symbol, or
# an Array of Symbols.
#
- # The index will be named after the table and the first column names,
+ # The index will be named after the table and the first column name,
# 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 colum +:first+. Using just the first name for this index
+ # 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.
#
View
16 activerecord/lib/active_record/connection_adapters/postgresql_adapter.rb
@@ -18,7 +18,7 @@ def self.postgresql_connection(config) # :nodoc:
raise ArgumentError, "No database specified. Missing argument: database."
end
- # The postgres drivers don't allow to create an unconnected PGconn object,
+ # The postgres drivers don't allow the creation of an unconnected PGconn object,
# so just pass a nil connection object for the time being.
ConnectionAdapters::PostgreSQLAdapter.new(nil, logger, [host, port, nil, nil, database, username, password], config)
end
@@ -217,8 +217,8 @@ module ConnectionAdapters
# * <tt>:password</tt> -- Defaults to nothing
# * <tt>:database</tt> -- The name of the database. No default, must be provided.
# * <tt>:schema_search_path</tt> -- An optional schema search path for the connection given as a string of comma-separated schema names. This is backward-compatible with the :schema_order option.
- # * <tt>:encoding</tt> -- An optional client encoding that is using in a SET client_encoding TO <encoding> call on connection.
- # * <tt>:min_messages</tt> -- An optional client min messages that is using in a SET client_min_messages TO <min_messages> call on connection.
+ # * <tt>:encoding</tt> -- An optional client encoding that is used in a SET client_encoding TO <encoding> call on the connection.
+ # * <tt>:min_messages</tt> -- An optional client min messages that is used in a SET client_min_messages TO <min_messages> call on the connection.
# * <tt>:allow_concurrency</tt> -- If true, use async query methods so Ruby threads don't deadlock; otherwise, use blocking query methods.
class PostgreSQLAdapter < AbstractAdapter
# Returns 'PostgreSQL' as adapter name for identification purposes.
@@ -398,7 +398,7 @@ def query(sql, name = nil) #:nodoc:
end
end
- # Executes a SQL statement, returning a PGresult object on success
+ # Executes an SQL statement, returning a PGresult object on success
# or raising a PGError exception otherwise.
def execute(sql, name = nil)
log(sql, name) do
@@ -478,7 +478,7 @@ def indexes(table_name, name = nil)
# Returns the list of all column definitions for a table.
def columns(table_name, name = nil)
- # Limit, precision, and scale are all handled by superclass.
+ # Limit, precision, and scale are all handled by the superclass.
column_definitions(table_name).collect do |name, type, default, notnull|
PostgreSQLColumn.new(name, default, type, notnull == 'f')
end
@@ -669,7 +669,7 @@ def distinct(columns, order_by) #:nodoc:
sql << order_columns * ', '
end
- # Returns a ORDER BY clause for the passed order option.
+ # Returns an ORDER BY clause for the passed order option.
#
# PostgreSQL does not allow arbitrary ordering when using DISTINCT ON, so we work around this
# by wrapping the sql as a sub-select and ordering in that query.
@@ -761,7 +761,7 @@ def last_insert_id(table, sequence_name) #:nodoc:
end
# Executes a SELECT query and returns the results, performing any data type
- # conversions that require to be performed here instead of in PostgreSQLColumn.
+ # conversions that are required to be performed here instead of in PostgreSQLColumn.
def select(sql, name = nil)
fields, rows = select_raw(sql, name)
result = []
@@ -791,7 +791,7 @@ def select_raw(sql, name = nil)
# fields that call value_before_type_cast.
if res.type(cell_index) == MONEY_COLUMN_TYPE_OID
# Because money output is formatted according to the locale, there are two
- # cases to consider (note the decimal seperators):
+ # cases to consider (note the decimal separators):
# (1) $12,345,678.12
# (2) $12.345.678,12
case column = row[cell_index]
View
2  activerecord/lib/active_record/connection_adapters/sqlite_adapter.rb
@@ -34,7 +34,7 @@ def parse_sqlite_config!(config)
# Allow database path relative to RAILS_ROOT, but only if
# the database path is not the special path that tells
- # Sqlite build a database only in memory.
+ # Sqlite to build a database only in memory.
if Object.const_defined?(:RAILS_ROOT) && ':memory:' != config[:database]
config[:database] = File.expand_path(config[:database], RAILS_ROOT)
end
View
14 activerecord/lib/active_record/fixtures.rb
@@ -12,7 +12,7 @@ def values; map { |k, v| v } end
class FixtureClassNotFound < ActiveRecord::ActiveRecordError #:nodoc:
end
-# Fixtures are a way of organizing data that you want to test against; in short, sample data. They come in 3 flavours:
+# Fixtures are a way of organizing data that you want to test against; in short, sample data. They come in 3 flavors:
#
# 1. YAML fixtures
# 2. CSV fixtures
@@ -21,7 +21,7 @@ class FixtureClassNotFound < ActiveRecord::ActiveRecordError #:nodoc:
# = YAML fixtures
#
# This type of fixture is in YAML format and the preferred default. YAML is a file format which describes data structures
-# in a non-verbose, humanly-readable format. It ships with Ruby 1.8.1+.
+# in a non-verbose, human-readable format. It ships with Ruby 1.8.1+.
#
# Unlike single-file fixtures, YAML fixtures are stored in a single file per model, which are placed in the directory appointed
# by <tt>Test::Unit::TestCase.fixture_path=(path)</tt> (this is automatically configured for Rails, so you can just
@@ -82,7 +82,7 @@ class FixtureClassNotFound < ActiveRecord::ActiveRecordError #:nodoc:
#
# = Single-file fixtures
#
-# This type of fixtures was the original format for Active Record that has since been deprecated in favor of the YAML and CSV formats.
+# This type of fixture was the original format for Active Record that has since been deprecated in favor of the YAML and CSV formats.
# Fixtures for this format are created by placing text files in a sub-directory (with the name of the model) to the directory
# appointed by <tt>Test::Unit::TestCase.fixture_path=(path)</tt> (this is automatically configured for Rails, so you can just
# put your files in <your-rails-app>/test/fixtures/<your-model-name>/ -- like <your-rails-app>/test/fixtures/web_sites/ for the WebSite
@@ -106,7 +106,7 @@ class FixtureClassNotFound < ActiveRecord::ActiveRecordError #:nodoc:
# = Using Fixtures
#
# Since fixtures are a testing construct, we use them in our unit and functional tests. There are two ways to use the
-# fixtures, but first let's take a look at a sample unit test found:
+# fixtures, but first let's take a look at a sample unit test:
#
# require 'web_site'
#
@@ -124,7 +124,7 @@ class FixtureClassNotFound < ActiveRecord::ActiveRecordError #:nodoc:
# fixtures :web_sites # add more by separating the symbols with commas
# ...
#
-# By adding a "fixtures" method to the test case and passing it a list of symbols (only one is shown here tho), we trigger
+# By adding a "fixtures" method to the test case and passing it a list of symbols (only one is shown here though), we trigger
# the testing environment to automatically load the appropriate fixtures into the database before each test.
# To ensure consistent data, the environment deletes the fixtures before running the load.
#
@@ -212,7 +212,7 @@ class FixtureClassNotFound < ActiveRecord::ActiveRecordError #:nodoc:
# When *not* to use transactional fixtures:
# 1. You're testing whether a transaction works correctly. Nested transactions don't commit until all parent transactions commit,
# particularly, the fixtures transaction which is begun in setup and rolled back in teardown. Thus, you won't be able to verify
-# the results of your transaction until Active Record supports nested transactions or savepoints (in progress.)
+# the results of your transaction until Active Record supports nested transactions or savepoints (in progress).
# 2. Your database does not support transactions. Every Active Record database supports transactions except MySQL MyISAM.
# Use InnoDB, MaxDB, or NDB instead.
#
@@ -260,7 +260,7 @@ class FixtureClassNotFound < ActiveRecord::ActiveRecordError #:nodoc:
#
# Specifying foreign keys in fixtures can be very fragile, not to
# mention difficult to read. Since ActiveRecord can figure out the ID of
-# and fixture from its label, you can specify FK's by label instead of ID.
+# any fixture from its label, you can specify FK's by label instead of ID.
#
# === belongs_to
#
View
12 activerecord/lib/active_record/migration.rb
@@ -32,9 +32,9 @@ def initialize(name)
# end
# end
#
- # This migration will add a boolean flag to the accounts table and remove it again, if you're backing out of the migration.
+ # 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,
+ # 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:
@@ -78,9 +78,9 @@ def initialize(name)
# * <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>: Add a new index with the name of the column. Other options include
+ # * <tt>add_index(table_name, column_names, options)</tt>: Adds a new index with the name of the column. Other options include
# :name and :unique (e.g. { :name => "users_name_index", :unique => true }).
- # * <tt>remove_index(table_name, index_name)</tt>: Remove the index specified by +index_name+.
+ # * <tt>remove_index(table_name, index_name)</tt>: Removes the index specified by +index_name+.
#
# == Irreversible transformations
#
@@ -94,9 +94,9 @@ def initialize(name)
# To generate a new migration, use <tt>script/generate migration MyNewMigration</tt>
# where MyNewMigration is the name of your migration. The generator will
# create a file <tt>nnn_my_new_migration.rb</tt> in the <tt>db/migrate/</tt>
- # directory, where <tt>nnn</tt> is the next largest migration number.
+ # directory where <tt>nnn</tt> is the next largest migration number.
# You may then edit the <tt>self.up</tt> and <tt>self.down</tt> methods of
- # n MyNewMigration.
+ # MyNewMigration.
#
# To run migrations against the currently configured database, use
# <tt>rake db:migrate</tt>. This will update the database by running all of the
View
4 activerecord/lib/active_record/reflection.rb
@@ -44,7 +44,7 @@ def reflect_on_aggregation(aggregation)
reflections[aggregation].is_a?(AggregateReflection) ? reflections[aggregation] : nil
end
- # Returns an array of AssociationReflection objects for all the aggregations in the class. If you only want to reflect on a
+ # 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 (:has_many, :has_one, :belongs_to) for that as the first parameter.
# Example:
#
@@ -56,7 +56,7 @@ def reflect_on_all_associations(macro = nil)
macro ? association_reflections.select { |reflection| reflection.macro == macro } : association_reflections
end
- # Returns the AssociationReflection object for the named +aggregation+ (use the symbol). Example:
+ # Returns the AssociationReflection object for the named +association+ (use the symbol). Example:
#
# Account.reflect_on_association(:owner) # returns the owner AssociationReflection
# Invoice.reflect_on_association(:line_items).macro # returns :has_many
View
4 activerecord/lib/active_record/serializers/xml_serializer.rb
@@ -1,7 +1,7 @@
module ActiveRecord #:nodoc:
module Serialization
# Builds an XML document to represent the model. Some configuration is
- # available through +options+, however more complicated cases should use
+ # available through +options+, however more complicated cases should
# override ActiveRecord's to_xml.
#
# By default the generated XML document will include the processing
@@ -107,7 +107,7 @@ module Serialization
# </creator>
# </firm>
#
- # You may override the to_xml method in your ActiveRecord::Base
+ # You can override the to_xml method in your ActiveRecord::Base
# subclasses if you need to. The general form of doing this is
#
# class IHaveMyOwnXML < ActiveRecord::Base
View
4 activerecord/lib/active_record/timestamp.rb
@@ -1,6 +1,6 @@
module ActiveRecord
- # Active Record automatically timestamps create and update if the table has fields
- # created_at/created_on or updated_at/updated_on.
+ # Active Record automatically timestamps create and update operations if the table has fields
+ # named created_at/created_on or updated_at/updated_on.
#
# Timestamping can be turned off by setting
# <tt>ActiveRecord::Base.record_timestamps = false</tt>
View
2  activerecord/lib/active_record/transactions.rb
@@ -75,7 +75,7 @@ def self.included(base)
#
# Both Base#save and Base#destroy come wrapped in a transaction that ensures that whatever you do in validations or callbacks
# will happen under the protected cover of a transaction. So you can use validations to check for values that the transaction
- # depend on or you can raise exceptions in the callbacks to rollback.
+ # depends on or you can raise exceptions in the callbacks to rollback.
#
# == Exception handling
#
View
6 activerecord/lib/active_record/validations.rb
@@ -15,7 +15,7 @@ def initialize(record)
end
# Active Record validation is reported to and from this object, which is used by Base#save to
- # determine whether the object in a valid state to be saved. See usage example in Validations.
+ # determine whether the object is in a valid state to be saved. See usage example in Validations.
class Errors
include Enumerable
@@ -45,7 +45,7 @@ def initialize(base) # :nodoc:
:even => "must be even"
}
- # Holds a hash with all the default error messages, such that they can be replaced by your own copy or localizations.
+ # Holds a hash with all the default error messages that can be replaced by your own copy or localizations.
cattr_accessor :default_error_messages
@@ -118,7 +118,7 @@ def on(attribute)
alias :[] :on
- # Returns errors assigned to base object through add_to_base according to the normal rules of on(attribute).
+ # Returns errors assigned to the base object through add_to_base according to the normal rules of on(attribute).
def on_base
on(:base)
end
Please sign in to comment.
Something went wrong with that request. Please try again.