From 7143d80147ea26c66dfa1dd4bb82f066d72f6570 Mon Sep 17 00:00:00 2001 From: Marcel Molina Date: Thu, 8 Nov 2007 03:37:16 +0000 Subject: [PATCH] Smattering of grammatical fixes to documentation. Closes #10083 [BobSilva] git-svn-id: http://svn-commit.rubyonrails.org/rails/trunk@8113 5ecf4fe2-1ee6-0310-87b1-e25e094e27de --- activerecord/CHANGELOG | 2 + .../lib/active_record/associations.rb | 29 +++++---- activerecord/lib/active_record/base.rb | 62 +++++++++++-------- .../lib/active_record/calculations.rb | 23 ++++--- activerecord/lib/active_record/callbacks.rb | 2 +- .../abstract/connection_specification.rb | 8 +-- .../abstract/database_statements.rb | 5 +- .../abstract/schema_definitions.rb | 4 +- .../abstract/schema_statements.rb | 6 +- .../connection_adapters/postgresql_adapter.rb | 16 ++--- .../connection_adapters/sqlite_adapter.rb | 2 +- activerecord/lib/active_record/fixtures.rb | 14 ++--- activerecord/lib/active_record/migration.rb | 12 ++-- activerecord/lib/active_record/reflection.rb | 4 +- .../serializers/xml_serializer.rb | 4 +- activerecord/lib/active_record/timestamp.rb | 4 +- .../lib/active_record/transactions.rb | 2 +- activerecord/lib/active_record/validations.rb | 6 +- 18 files changed, 109 insertions(+), 96 deletions(-) diff --git a/activerecord/CHANGELOG b/activerecord/CHANGELOG index 072ca352e67..c196e24ac77 100644 --- a/activerecord/CHANGELOG +++ b/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] diff --git a/activerecord/lib/active_record/associations.rb b/activerecord/lib/active_record/associations.rb index 1013c756438..f6ee5e1d07d 100755 --- a/activerecord/lib/active_record/associations.rb +++ b/activerecord/lib/active_record/associations.rb @@ -243,7 +243,7 @@ module ActiveRecord # # == 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 @@ module ActiveRecord # === 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 ActiveRecord # 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 by the objects identified by the primary keys in +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, - # or otherwise sets their foreign keys to NULL. + # 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. @@ -621,8 +621,6 @@ module ActiveRecord # SQL fragment, such as price > 5 AND name LIKE 'B%'. # * :order - specify the order in which the associated objects are returned as an ORDER BY SQL fragment, # such as last_name, first_name DESC - # * :group - specify the attribute by which the associated objects are returned as a GROUP BY SQL fragment, - # such as +category+ # * :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+. @@ -633,13 +631,13 @@ module ActiveRecord # * :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 - # specified but :counter_sql, :counter_sql will be generated by replacing SELECT ... FROM with SELECT COUNT(*) FROM. + # 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, + # * :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. # * :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 @@ -708,8 +706,8 @@ module ActiveRecord # if the real class name is +Person+, you'll have to specify it with this option. # * :conditions - specify the conditions that the associated object must meet in order to be included as a +WHERE+ # SQL fragment, such as rank = 5. - # * :order - 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 + # * :order - specify the order in which the associated objects are returned as an ORDER BY SQL fragment, + # such as last_name, first_name DESC # * :dependent - if set to :destroy, the associated object is destroyed when this object is. If set to # :delete, the associated object is deleted *without* calling its destroy method. If set to :nullify, the associated # object's foreign key is set to +NULL+. Also, association is assigned. @@ -721,7 +719,7 @@ module ActiveRecord # # 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 @@ module ActiveRecord # if the real class name is +Person+, you'll have to specify it with this option. # * :conditions - specify the conditions that the associated object must meet in order to be included as a +WHERE+ # SQL fragment, such as authorized = 1. - # * :order - 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 + # * :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 # 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+. - # * :counter_cache - caches the number of belonging objects on the associate class through use of +increment_counter+ + # * :counter_cache - 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 #{table_name}_count (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 @@ module ActiveRecord # the +has_and_belongs_to_many+ association will use +project_id+ as the default association +foreign_key+. # * :conditions - specify the conditions that the associated object must meet in order to be included as a +WHERE+ # SQL fragment, such as authorized = 1. - # * :order - specify the order in which the associated objects are returned as a ORDER BY SQL fragment, such as last_name, first_name DESC + # * :order - specify the order in which the associated objects are returned as an ORDER BY SQL fragment, + # such as last_name, first_name DESC # * :uniq - if set to +true+, duplicate associated objects will be ignored by accessors and query methods # * :finder_sql - overwrite the default generated SQL statement used to fetch the association with a manual statement # * :delete_sql - overwrite the default generated SQL statement used to remove links between the associated diff --git a/activerecord/lib/active_record/base.rb b/activerecord/lib/active_record/base.rb index a7d2b01f732..3e7fa13e975 100755 --- a/activerecord/lib/active_record/base.rb +++ b/activerecord/lib/active_record/base.rb @@ -40,7 +40,7 @@ module ActiveRecord #: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 @@ module ActiveRecord #:nodoc: # == 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 @@ module ActiveRecord #:nodoc: # end # # The authenticate_unsafely method inserts the parameters directly into the query and is thus susceptible to SQL-injection - # attacks if the user_name and +password+ parameters come directly from a HTTP request. The authenticate_safely and + # attacks if the user_name and +password+ parameters come directly from an HTTP request. The authenticate_safely and # authenticate_safely_simply both will sanitize the user_name 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 @@ module ActiveRecord #:nodoc: # # == 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 @@ module ActiveRecord #:nodoc: # # == 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 Base.inheritance_column). This means that an inheritance looking like this: # # class Company < ActiveRecord::Base; end @@ -251,7 +251,7 @@ module ActiveRecord #:nodoc: # # 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 @@ module ActiveRecord #:nodoc: # == Exceptions # # * +ActiveRecordError+ -- generic error class and superclass of all other errors raised by Active Record - # * +AdapterNotSpecified+ -- the configuration hash used in establish_connection didn't include a + # * +AdapterNotSpecified+ -- the configuration hash used in establish_connection didn't include an # :adapter key. - # * +AdapterNotFound+ -- the :adapter key used in establish_connection specified an non-existent adapter + # * +AdapterNotFound+ -- the :adapter key used in establish_connection 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 establish_connection 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 @@ module ActiveRecord #: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 @@ module ActiveRecord #:nodoc: # * 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: # # * :conditions: An SQL fragment like "administrator = 1" or [ "user_name = ?", username ]. See conditions in the intro. # * :order: An SQL fragment like "created_at DESC, name". @@ -384,9 +384,10 @@ module ActiveRecord #:nodoc: # 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. # * :include: Names associations that should be loaded alongside using LEFT OUTER JOINs. The symbols named refer # to already defined associations. See eager loading under Associations. - # * :select: By default, this is * as in SELECT * FROM, but can be changed if you for example want to do a join, but not + # * :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. # * :from: 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 @@ module ActiveRecord #:nodoc: # 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 @@ module ActiveRecord #:nodoc: # 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 @@ module ActiveRecord #:nodoc: 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 @@ module ActiveRecord #:nodoc: # # 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 @@ module ActiveRecord #:nodoc: # ==== 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 @@ module ActiveRecord #:nodoc: # 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 @@ module ActiveRecord #:nodoc: connection.quote(value,column) end - # Used to sanitize objects before they're used in an SELECT SQL-statement. Delegates to connection.quote. + # Used to sanitize objects before they're used in an SQL SELECT statement. Delegates to connection.quote. def sanitize(object) #:nodoc: connection.quote(object) end @@ -1266,7 +1274,7 @@ module ActiveRecord #:nodoc: # 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 @@ module ActiveRecord #:nodoc: # end # end # - # You can ignore any previous scopings by using with_exclusive_scope method. + # You can ignore any previous scopings by using the with_exclusive_scope method. # # class Article < ActiveRecord::Base # def self.find_with_exclusive_scope @@ -1889,7 +1897,7 @@ module ActiveRecord #:nodoc: # 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 @@ module ActiveRecord #:nodoc: 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 @@ module ActiveRecord #:nodoc: # 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) diff --git a/activerecord/lib/active_record/calculations.rb b/activerecord/lib/active_record/calculations.rb index 7f8af9421ed..df73cee2f38 100644 --- a/activerecord/lib/active_record/calculations.rb +++ b/activerecord/lib/active_record/calculations.rb @@ -15,14 +15,17 @@ module ActiveRecord # The third approach, count using options, accepts an option hash as the only parameter. The options are: # # * :conditions: An SQL fragment like "administrator = 1" or [ "user_name = ?", username ]. See conditions in the intro. - # * :joins: 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. + # * :joins: 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. # * :include: 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. # * :order: An SQL fragment like "created_at DESC, name" (really only used with GROUP BY calculations). # * :group: An attribute name by which the result should be grouped. Uses the GROUP BY SQL-clause. - # * :select: By default, this is * as in SELECT * FROM, but can be changed if you for example want to do a join, but not + # * :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. # * :distinct: Set this to true to make this a distinct calculation, such as SELECT COUNT(DISTINCT posts.id) ... # @@ -44,35 +47,35 @@ module ActiveRecord 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 @@ module ActiveRecord 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 diff --git a/activerecord/lib/active_record/callbacks.rb b/activerecord/lib/active_record/callbacks.rb index 631eb911fca..8d619e3fb35 100755 --- a/activerecord/lib/active_record/callbacks.rb +++ b/activerecord/lib/active_record/callbacks.rb @@ -161,7 +161,7 @@ module ActiveRecord # == before_validation* returning statements # # If the returning value of a +before_validation+ callback can be evaluated to +false+, the process will be aborted and Base#save will return +false+. - # If Base#save! is called it will raise a +RecordNotSave+ exception. + # If Base#save! is called it will raise a +RecordNotSaved+ exception. # Nothing will be appended to the errors object. # # == Cancelling callbacks diff --git a/activerecord/lib/active_record/connection_adapters/abstract/connection_specification.rb b/activerecord/lib/active_record/connection_adapters/abstract/connection_specification.rb index 801cb23362b..51b90d3c64e 100644 --- a/activerecord/lib/active_record/connection_adapters/abstract/connection_specification.rb +++ b/activerecord/lib/active_record/connection_adapters/abstract/connection_specification.rb @@ -243,7 +243,7 @@ module ActiveRecord 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 @@ module ActiveRecord 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] diff --git a/activerecord/lib/active_record/connection_adapters/abstract/database_statements.rb b/activerecord/lib/active_record/connection_adapters/abstract/database_statements.rb index 066baaba451..589acd39457 100644 --- a/activerecord/lib/active_record/connection_adapters/abstract/database_statements.rb +++ b/activerecord/lib/active_record/connection_adapters/abstract/database_statements.rb @@ -98,7 +98,7 @@ module ActiveRecord 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 @@ module ActiveRecord 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' diff --git a/activerecord/lib/active_record/connection_adapters/abstract/schema_definitions.rb b/activerecord/lib/active_record/connection_adapters/abstract/schema_definitions.rb index 6bd56fd3c8d..c6cdc776d6c 100644 --- a/activerecord/lib/active_record/connection_adapters/abstract/schema_definitions.rb +++ b/activerecord/lib/active_record/connection_adapters/abstract/schema_definitions.rb @@ -272,7 +272,7 @@ module ActiveRecord 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 @@ module ActiveRecord 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 * ', ' 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 d4fcded32af..8f981438df3 100644 --- a/activerecord/lib/active_record/connection_adapters/abstract/schema_statements.rb +++ b/activerecord/lib/active_record/connection_adapters/abstract/schema_statements.rb @@ -54,7 +54,7 @@ module ActiveRecord # [:temporary] # Make a temporary table. # [:force] - # 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 @@ module ActiveRecord # 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. # diff --git a/activerecord/lib/active_record/connection_adapters/postgresql_adapter.rb b/activerecord/lib/active_record/connection_adapters/postgresql_adapter.rb index bf8fed11115..64f314a7f6b 100644 --- a/activerecord/lib/active_record/connection_adapters/postgresql_adapter.rb +++ b/activerecord/lib/active_record/connection_adapters/postgresql_adapter.rb @@ -18,7 +18,7 @@ module ActiveRecord 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 ActiveRecord # * :password -- Defaults to nothing # * :database -- The name of the database. No default, must be provided. # * :schema_search_path -- 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. - # * :encoding -- An optional client encoding that is using in a SET client_encoding TO call on connection. - # * :min_messages -- An optional client min messages that is using in a SET client_min_messages TO call on connection. + # * :encoding -- An optional client encoding that is used in a SET client_encoding TO call on the connection. + # * :min_messages -- An optional client min messages that is used in a SET client_min_messages TO call on the connection. # * :allow_concurrency -- 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 @@ module ActiveRecord 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 @@ module ActiveRecord # 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 @@ module ActiveRecord 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 @@ module ActiveRecord 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 @@ module ActiveRecord # 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] diff --git a/activerecord/lib/active_record/connection_adapters/sqlite_adapter.rb b/activerecord/lib/active_record/connection_adapters/sqlite_adapter.rb index c171b0239e1..586594e0efb 100644 --- a/activerecord/lib/active_record/connection_adapters/sqlite_adapter.rb +++ b/activerecord/lib/active_record/connection_adapters/sqlite_adapter.rb @@ -34,7 +34,7 @@ module ActiveRecord # 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 diff --git a/activerecord/lib/active_record/fixtures.rb b/activerecord/lib/active_record/fixtures.rb index 41e389d4fe0..84e7c84d644 100755 --- a/activerecord/lib/active_record/fixtures.rb +++ b/activerecord/lib/active_record/fixtures.rb @@ -12,7 +12,7 @@ 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 @@ end # = 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 Test::Unit::TestCase.fixture_path=(path) (this is automatically configured for Rails, so you can just @@ -82,7 +82,7 @@ end # # = 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 Test::Unit::TestCase.fixture_path=(path) (this is automatically configured for Rails, so you can just # put your files in /test/fixtures// -- like /test/fixtures/web_sites/ for the WebSite @@ -106,7 +106,7 @@ end # = 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 @@ end # 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 @@ end # 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 @@ end # # 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 # diff --git a/activerecord/lib/active_record/migration.rb b/activerecord/lib/active_record/migration.rb index 2405eeb8732..ee50bbd44e7 100644 --- a/activerecord/lib/active_record/migration.rb +++ b/activerecord/lib/active_record/migration.rb @@ -32,9 +32,9 @@ module ActiveRecord # 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 @@ module ActiveRecord # * change_column(table_name, column_name, type, options): Changes the column to a different type using the same # parameters as add_column. # * remove_column(table_name, column_name): Removes the column named +column_name+ from the table called +table_name+. - # * add_index(table_name, column_names, options): Add a new index with the name of the column. Other options include + # * add_index(table_name, column_names, options): Adds a new index with the name of the column. Other options include # :name and :unique (e.g. { :name => "users_name_index", :unique => true }). - # * remove_index(table_name, index_name): Remove the index specified by +index_name+. + # * remove_index(table_name, index_name): Removes the index specified by +index_name+. # # == Irreversible transformations # @@ -94,9 +94,9 @@ module ActiveRecord # To generate a new migration, use script/generate migration MyNewMigration # where MyNewMigration is the name of your migration. The generator will # create a file nnn_my_new_migration.rb in the db/migrate/ - # directory, where nnn is the next largest migration number. + # directory where nnn is the next largest migration number. # You may then edit the self.up and self.down methods of - # n MyNewMigration. + # MyNewMigration. # # To run migrations against the currently configured database, use # rake db:migrate. This will update the database by running all of the diff --git a/activerecord/lib/active_record/reflection.rb b/activerecord/lib/active_record/reflection.rb index 3d76ffe7769..e7a0f9a8358 100644 --- a/activerecord/lib/active_record/reflection.rb +++ b/activerecord/lib/active_record/reflection.rb @@ -44,7 +44,7 @@ module ActiveRecord 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 @@ module ActiveRecord 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 diff --git a/activerecord/lib/active_record/serializers/xml_serializer.rb b/activerecord/lib/active_record/serializers/xml_serializer.rb index 16448bae77f..28e9b3ddc6f 100644 --- a/activerecord/lib/active_record/serializers/xml_serializer.rb +++ b/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 ActiveRecord #:nodoc: # # # - # 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 diff --git a/activerecord/lib/active_record/timestamp.rb b/activerecord/lib/active_record/timestamp.rb index c4bc55cb499..ee3e4265120 100644 --- a/activerecord/lib/active_record/timestamp.rb +++ b/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 # ActiveRecord::Base.record_timestamps = false diff --git a/activerecord/lib/active_record/transactions.rb b/activerecord/lib/active_record/transactions.rb index 0cffcef3135..61f5d819fca 100644 --- a/activerecord/lib/active_record/transactions.rb +++ b/activerecord/lib/active_record/transactions.rb @@ -75,7 +75,7 @@ module ActiveRecord # # 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 # diff --git a/activerecord/lib/active_record/validations.rb b/activerecord/lib/active_record/validations.rb index 35a1f8d0d48..24b29b1ec8a 100755 --- a/activerecord/lib/active_record/validations.rb +++ b/activerecord/lib/active_record/validations.rb @@ -15,7 +15,7 @@ module ActiveRecord 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 @@ module ActiveRecord :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 @@ module ActiveRecord 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