Skip to content
This repository
Browse code

updating documentation to ensure line does not exceed 100 columns

  • Loading branch information...
commit b8d9d9ce0a72218fa0891485063d3fcb3e77cae8 1 parent b29c23a
Neeraj Singh authored August 02, 2010
216  activerecord/lib/active_record/base.rb
@@ -26,17 +26,19 @@
26 26
 module ActiveRecord #:nodoc:
27 27
   # = Active Record
28 28
   #
29  
-  # Active Record objects don't specify their attributes directly, but rather infer them from the table definition with
30  
-  # which they're linked. Adding, removing, and changing attributes and their type is done directly in the database. Any change
31  
-  # is instantly reflected in the Active Record objects. The mapping that binds a given Active Record class to a certain
  29
+  # Active Record objects don't specify their attributes directly, but rather infer them from 
  30
+  # the table definition with which they're linked. Adding, removing, and changing attributes 
  31
+  # and their type is done directly in the database. Any change is instantly reflected in the 
  32
+  # Active Record objects. The mapping that binds a given Active Record class to a certain
32 33
   # database table will happen automatically in most common cases, but can be overwritten for the uncommon ones.
33 34
   #
34 35
   # See the mapping rules in table_name and the full example in link:files/README.html for more insight.
35 36
   #
36 37
   # == Creation
37 38
   #
38  
-  # Active Records accept constructor parameters either in a hash or as a block. The hash method is especially useful when
39  
-  # you're receiving the data from somewhere else, like an HTTP request. It works like this:
  39
+  # Active Records accept constructor parameters either in a hash or as a block. The hash 
  40
+  # method is especially useful when you're receiving the data from somewhere else, like an 
  41
+  # HTTP request. It works like this:
40 42
   #
41 43
   #   user = User.new(:name => "David", :occupation => "Code Artist")
42 44
   #   user.name # => "David"
@@ -75,14 +77,17 @@ module ActiveRecord #:nodoc:
75 77
   #     end
76 78
   #   end
77 79
   #
78  
-  # The <tt>authenticate_unsafely</tt> method inserts the parameters directly into the query and is thus susceptible to SQL-injection
79  
-  # attacks if the <tt>user_name</tt> and +password+ parameters come directly from an HTTP request. The <tt>authenticate_safely</tt>  and
80  
-  # <tt>authenticate_safely_simply</tt> both will sanitize the <tt>user_name</tt> and +password+ before inserting them in the query,
81  
-  # which will ensure that an attacker can't escape the query and fake the login (or worse).
  80
+  # The <tt>authenticate_unsafely</tt> method inserts the parameters directly into the query 
  81
+  # and is thus susceptible to SQL-injection attacks if the <tt>user_name</tt> and +password+ 
  82
+  # parameters come directly from an HTTP request. The <tt>authenticate_safely</tt>  and
  83
+  # <tt>authenticate_safely_simply</tt> both will sanitize the <tt>user_name</tt> and +password+ 
  84
+  # before inserting them in the query, which will ensure that an attacker can't escape the 
  85
+  # query and fake the login (or worse).
82 86
   #
83  
-  # When using multiple parameters in the conditions, it can easily become hard to read exactly what the fourth or fifth
84  
-  # question mark is supposed to represent. In those cases, you can resort to named bind variables instead. That's done by replacing
85  
-  # the question marks with symbols and supplying a hash with values for the matching symbol keys:
  87
+  # When using multiple parameters in the conditions, it can easily become hard to read exactly 
  88
+  # what the fourth or fifth question mark is supposed to represent. In those cases, you can 
  89
+  # resort to named bind variables instead. That's done by replacing the question marks with 
  90
+  # symbols and supplying a hash with values for the matching symbol keys:
86 91
   #
87 92
   #   Company.where(
88 93
   #     "id = :id AND name = :name AND division = :division AND created_at > :accounting_date",
@@ -103,18 +108,19 @@ module ActiveRecord #:nodoc:
103 108
   #
104 109
   #   Student.where(:grade => [9,11,12])
105 110
   #
106  
-  # When joining tables, nested hashes or keys written in the form 'table_name.column_name' can be used to qualify the table name of a
107  
-  # particular condition. For instance:
  111
+  # When joining tables, nested hashes or keys written in the form 'table_name.column_name' 
  112
+  # can be used to qualify the table name of a particular condition. For instance:
108 113
   #
109 114
   #   Student.joins(:schools).where(:schools => { :type => 'public' })
110 115
   #   Student.joins(:schools).where('schools.type' => 'public' )
111 116
   #
112 117
   # == Overwriting default accessors
113 118
   #
114  
-  # All column values are automatically available through basic accessors on the Active Record object, but sometimes you
115  
-  # want to specialize this behavior. This can be done by overwriting the default accessors (using the same
116  
-  # name as the attribute) and calling <tt>read_attribute(attr_name)</tt> and <tt>write_attribute(attr_name, value)</tt> to actually change things.
117  
-  # Example:
  119
+  # All column values are automatically available through basic accessors on the Active Record 
  120
+  # object, but sometimes you want to specialize this behavior. This can be done by overwriting 
  121
+  # the default accessors (using the same name as the attribute) and calling 
  122
+  # <tt>read_attribute(attr_name)</tt> and <tt>write_attribute(attr_name, value)</tt> to actually 
  123
+  # change things.
118 124
   #
119 125
   #   class Song < ActiveRecord::Base
120 126
   #     # Uses an integer of seconds to hold the length of the song
@@ -128,8 +134,8 @@ module ActiveRecord #:nodoc:
128 134
   #     end
129 135
   #   end
130 136
   #
131  
-  # You can alternatively use <tt>self[:attribute]=(value)</tt> and <tt>self[:attribute]</tt> instead of <tt>write_attribute(:attribute, value)</tt> and
132  
-  # <tt>read_attribute(:attribute)</tt> as a shorter form.
  137
+  # You can alternatively use <tt>self[:attribute]=(value)</tt> and <tt>self[:attribute]</tt> 
  138
+  # instead of <tt>write_attribute(:attribute, value)</tt> and <tt>read_attribute(:attribute)</tt>.
133 139
   #
134 140
   # == Attribute query methods
135 141
   #
@@ -147,24 +153,29 @@ module ActiveRecord #:nodoc:
147 153
   #
148 154
   # == Accessing attributes before they have been typecasted
149 155
   #
150  
-  # Sometimes you want to be able to read the raw attribute data without having the column-determined typecast run its course first.
151  
-  # That can be done by using the <tt><attribute>_before_type_cast</tt> accessors that all attributes have. For example, if your Account model
152  
-  # has a <tt>balance</tt> attribute, you can call <tt>account.balance_before_type_cast</tt> or <tt>account.id_before_type_cast</tt>.
  156
+  # Sometimes you want to be able to read the raw attribute data without having the column-determined 
  157
+  # typecast run its course first. That can be done by using the <tt><attribute>_before_type_cast</tt> 
  158
+  # accessors that all attributes have. For example, if your Account model has a <tt>balance</tt> attribute, 
  159
+  # you can call <tt>account.balance_before_type_cast</tt> or <tt>account.id_before_type_cast</tt>.
153 160
   #
154  
-  # This is especially useful in validation situations where the user might supply a string for an integer field and you want to display
155  
-  # the original string back in an error message. Accessing the attribute normally would typecast the string to 0, which isn't what you
156  
-  # want.
  161
+  # This is especially useful in validation situations where the user might supply a string for an 
  162
+  # integer field and you want to display the original string back in an error message. Accessing the 
  163
+  # attribute normally would typecast the string to 0, which isn't what you want.
157 164
   #
158 165
   # == Dynamic attribute-based finders
159 166
   #
160  
-  # Dynamic attribute-based finders are a cleaner way of getting (and/or creating) objects by simple queries without turning to SQL. They work by
161  
-  # appending the name of an attribute to <tt>find_by_</tt>, <tt>find_last_by_</tt>, or <tt>find_all_by_</tt>, so you get finders like <tt>Person.find_by_user_name</tt>,
162  
-  # <tt>Person.find_all_by_last_name</tt>, and <tt>Payment.find_by_transaction_id</tt>. So instead of writing
  167
+  # Dynamic attribute-based finders are a cleaner way of getting (and/or creating) objects 
  168
+  # by simple queries without turning to SQL. They work by appending the name of an attribute 
  169
+  # to <tt>find_by_</tt>, <tt>find_last_by_</tt>, or <tt>find_all_by_</tt>, so you get finders 
  170
+  # like <tt>Person.find_by_user_name</tt>, <tt>Person.find_all_by_last_name</tt>, and 
  171
+  # <tt>Payment.find_by_transaction_id</tt>. So instead of writing 
163 172
   # <tt>Person.where(:user_name => user_name).first</tt>, you just do <tt>Person.find_by_user_name(user_name)</tt>.
164  
-  # And instead of writing <tt>Person.where(:last_name => last_name).all</tt>, you just do <tt>Person.find_all_by_last_name(last_name)</tt>.
  173
+  # And instead of writing <tt>Person.where(:last_name => last_name).all</tt>, you just do 
  174
+  # <tt>Person.find_all_by_last_name(last_name)</tt>.
165 175
   #
166  
-  # It's also possible to use multiple attributes in the same find by separating them with "_and_", so you get finders like
167  
-  # <tt>Person.find_by_user_name_and_password</tt> or even <tt>Payment.find_by_purchaser_and_state_and_country</tt>. So instead of writing
  176
+  # It's also possible to use multiple attributes in the same find by separating them with "_and_", 
  177
+  # so you get finders like <tt>Person.find_by_user_name_and_password</tt> or even 
  178
+  # <tt>Payment.find_by_purchaser_and_state_and_country</tt>. So instead of writing
168 179
   # <tt>Person.where(:user_name => user_name, :password => password).first</tt>, you just do
169 180
   # <tt>Person.find_by_user_name_and_password(user_name, password)</tt>.
170 181
   #
@@ -173,8 +184,10 @@ module ActiveRecord #:nodoc:
173 184
   #   Payment.order("created_on").find_all_by_amount(50)
174 185
   #   Payment.pending.find_last_by_amount(100)
175 186
   #
176  
-  # The same dynamic finder style can be used to create the object if it doesn't already exist. This dynamic finder is called with
177  
-  # <tt>find_or_create_by_</tt> and will return the object if it already exists and otherwise creates it, then returns it. Protected attributes won't be set unless they are given in a block. For example:
  187
+  # The same dynamic finder style can be used to create the object if it doesn't already exist. 
  188
+  # This dynamic finder is called with <tt>find_or_create_by_</tt> and will return the object if 
  189
+  # it already exists and otherwise creates it, then returns it. Protected attributes won't be set 
  190
+  # unless they are given in a block. For example:
178 191
   #
179 192
   #   # No 'Summer' tag exists
180 193
   #   Tag.find_or_create_by_name("Summer") # equal to Tag.create(:name => "Summer")
@@ -185,23 +198,27 @@ module ActiveRecord #:nodoc:
185 198
   #   # Now 'Bob' exist and is an 'admin'
186 199
   #   User.find_or_create_by_name('Bob', :age => 40) { |u| u.admin = true }
187 200
   #
188  
-  # Use the <tt>find_or_initialize_by_</tt> finder if you want to return a new record without saving it first. Protected attributes won't be set unless they are given in a block. For example:
  201
+  # Use the <tt>find_or_initialize_by_</tt> finder if you want to return a new record without 
  202
+  # saving it first. Protected attributes won't be set unless they are given in a block.
189 203
   #
190 204
   #   # No 'Winter' tag exists
191 205
   #   winter = Tag.find_or_initialize_by_name("Winter")
192 206
   #   winter.new_record? # true
193 207
   #
194 208
   # To find by a subset of the attributes to be used for instantiating a new object, pass a hash instead of
195  
-  # a list of parameters. For example:
  209
+  # a list of parameters.
196 210
   #
197 211
   #   Tag.find_or_create_by_name(:name => "rails", :creator => current_user)
198 212
   #
199  
-  # That will either find an existing tag named "rails", or create a new one while setting the user that created it.
  213
+  # That will either find an existing tag named "rails", or create a new one while setting the 
  214
+  # user that created it.
200 215
   #
201 216
   # == Saving arrays, hashes, and other non-mappable objects in text columns
202 217
   #
203  
-  # Active Record can serialize any object in text columns using YAML. To do so, you must specify this with a call to the class method +serialize+.
204  
-  # This makes it possible to store arrays, hashes, and other non-mappable objects without doing any additional work. Example:
  218
+  # Active Record can serialize any object in text columns using YAML. To do so, you must 
  219
+  # specify this with a call to the class method +serialize+.
  220
+  # This makes it possible to store arrays, hashes, and other non-mappable objects without doing 
  221
+  # any additional work. 
205 222
   #
206 223
   #   class User < ActiveRecord::Base
207 224
   #     serialize :preferences
@@ -210,8 +227,8 @@ module ActiveRecord #:nodoc:
210 227
   #   user = User.create(:preferences => { "background" => "black", "display" => large })
211 228
   #   User.find(user.id).preferences # => { "background" => "black", "display" => large }
212 229
   #
213  
-  # You can also specify a class option as the second parameter that'll raise an exception if a serialized object is retrieved as a
214  
-  # descendant of a class not in the hierarchy. Example:
  230
+  # You can also specify a class option as the second parameter that'll raise an exception 
  231
+  # if a serialized object is retrieved as a descendant of a class not in the hierarchy.
215 232
   #
216 233
   #   class User < ActiveRecord::Base
217 234
   #     serialize :preferences, Hash
@@ -222,52 +239,63 @@ module ActiveRecord #:nodoc:
222 239
   #
223 240
   # == Single table inheritance
224 241
   #
225  
-  # Active Record allows inheritance by storing the name of the class in a column that by default is named "type" (can be changed
226  
-  # by overwriting <tt>Base.inheritance_column</tt>). This means that an inheritance looking like this:
  242
+  # Active Record allows inheritance by storing the name of the class in a column that by 
  243
+  # default is named "type" (can be changed by overwriting <tt>Base.inheritance_column</tt>). 
  244
+  # This means that an inheritance looking like this:
227 245
   #
228 246
   #   class Company < ActiveRecord::Base; end
229 247
   #   class Firm < Company; end
230 248
   #   class Client < Company; end
231 249
   #   class PriorityClient < Client; end
232 250
   #
233  
-  # When you do <tt>Firm.create(:name => "37signals")</tt>, this record will be saved in the companies table with type = "Firm". You can then
234  
-  # fetch this row again using <tt>Company.where(:name => '37signals').first</tt> and it will return a Firm object.
  251
+  # When you do <tt>Firm.create(:name => "37signals")</tt>, this record will be saved in 
  252
+  # the companies table with type = "Firm". You can then fetch this row again using 
  253
+  # <tt>Company.where(:name => '37signals').first</tt> and it will return a Firm object.
235 254
   #
236  
-  # If you don't have a type column defined in your table, single-table inheritance won't be triggered. In that case, it'll work just
237  
-  # like normal subclasses with no special magic for differentiating between them or reloading the right type with find.
  255
+  # If you don't have a type column defined in your table, single-table inheritance won't 
  256
+  # be triggered. In that case, it'll work just like normal subclasses with no special magic 
  257
+  # for differentiating between them or reloading the right type with find.
238 258
   #
239 259
   # Note, all the attributes for all the cases are kept in the same table. Read more:
240 260
   # http://www.martinfowler.com/eaaCatalog/singleTableInheritance.html
241 261
   #
242 262
   # == Connection to multiple databases in different models
243 263
   #
244  
-  # Connections are usually created through ActiveRecord::Base.establish_connection and retrieved by ActiveRecord::Base.connection.
245  
-  # All classes inheriting from ActiveRecord::Base will use this connection. But you can also set a class-specific connection.
246  
-  # For example, if Course is an ActiveRecord::Base, but resides in a different database, you can just say <tt>Course.establish_connection</tt>
  264
+  # Connections are usually created through ActiveRecord::Base.establish_connection and retrieved 
  265
+  # by ActiveRecord::Base.connection. All classes inheriting from ActiveRecord::Base will use this 
  266
+  # connection. But you can also set a class-specific connection. For example, if Course is an 
  267
+  # ActiveRecord::Base, but resides in a different database, you can just say <tt>Course.establish_connection</tt>
247 268
   # and Course and all of its subclasses will use this connection instead.
248 269
   #
249  
-  # This feature is implemented by keeping a connection pool in ActiveRecord::Base that is a Hash indexed by the class. If a connection is
250  
-  # requested, the retrieve_connection method will go up the class-hierarchy until a connection is found in the connection pool.
  270
+  # This feature is implemented by keeping a connection pool in ActiveRecord::Base that is 
  271
+  # a Hash indexed by the class. If a connection is requested, the retrieve_connection method 
  272
+  # will go up the class-hierarchy until a connection is found in the connection pool.
251 273
   #
252 274
   # == Exceptions
253 275
   #
254 276
   # * ActiveRecordError - Generic error class and superclass of all other errors raised by Active Record.
255 277
   # * AdapterNotSpecified - The configuration hash used in <tt>establish_connection</tt> didn't include an
256 278
   #   <tt>:adapter</tt> key.
257  
-  # * AdapterNotFound - The <tt>:adapter</tt> key used in <tt>establish_connection</tt> specified a non-existent adapter
  279
+  # * AdapterNotFound - The <tt>:adapter</tt> key used in <tt>establish_connection</tt> specified a 
  280
+  #   non-existent adapter
258 281
   #   (or a bad spelling of an existing one).
259  
-  # * AssociationTypeMismatch - The object assigned to the association wasn't of the type specified in the association definition.
  282
+  # * AssociationTypeMismatch - The object assigned to the association wasn't of the type 
  283
+  #   specified in the association definition.
260 284
   # * SerializationTypeMismatch - The serialized object wasn't of the class specified as the second parameter.
261  
-  # * ConnectionNotEstablished+ - No connection has been established. Use <tt>establish_connection</tt> before querying.
  285
+  # * ConnectionNotEstablished+ - No connection has been established. Use <tt>establish_connection</tt> 
  286
+  #   before querying.
262 287
   # * RecordNotFound - No record responded to the +find+ method. Either the row with the given ID doesn't exist
263 288
   #   or the row didn't meet the additional restrictions. Some +find+ calls do not raise this exception to signal
264 289
   #   nothing was found, please check its documentation for further details.
265 290
   # * StatementInvalid - The database server rejected the SQL statement. The precise error is added in the message.
266 291
   # * MultiparameterAssignmentErrors - Collection of errors that occurred during a mass assignment using the
267  
-  #   <tt>attributes=</tt> method. The +errors+ property of this exception contains an array of AttributeAssignmentError
  292
+  #   <tt>attributes=</tt> method. The +errors+ property of this exception contains an array of 
  293
+  #   AttributeAssignmentError
268 294
   #   objects that should be inspected to determine which attributes triggered the errors.
269  
-  # * AttributeAssignmentError - An error occurred while doing a mass assignment through the <tt>attributes=</tt> method.
270  
-  #   You can inspect the +attribute+ property of the exception object to determine which attribute triggered the error.
  295
+  # * AttributeAssignmentError - An error occurred while doing a mass assignment through the 
  296
+  #   <tt>attributes=</tt> method.
  297
+  #   You can inspect the +attribute+ property of the exception object to determine which attribute 
  298
+  #   triggered the error.
271 299
   #
272 300
   # *Note*: The attributes listed are class-level attributes (accessible from both the class and instance level).
273 301
   # So it's possible to assign a logger to the class through <tt>Base.logger=</tt> which will then be used by all
@@ -275,8 +303,9 @@ module ActiveRecord #:nodoc:
275 303
   class Base
276 304
     ##
277 305
     # :singleton-method:
278  
-    # Accepts a logger conforming to the interface of Log4r or the default Ruby 1.8+ Logger class, which is then passed
279  
-    # on to any new database connections made and which can be retrieved on both a class and instance level by calling +logger+.
  306
+    # Accepts a logger conforming to the interface of Log4r or the default Ruby 1.8+ Logger class, 
  307
+    # which is then passed on to any new database connections made and which can be retrieved on both 
  308
+    # a class and instance level by calling +logger+.
280 309
     cattr_accessor :logger, :instance_writer => false
281 310
 
282 311
     class << self
@@ -323,21 +352,24 @@ def subclasses
323 352
 
324 353
     ##
325 354
     # :singleton-method:
326  
-    # Accessor for the prefix type that will be prepended to every primary key column name. The options are :table_name and
327  
-    # :table_name_with_underscore. If the first is specified, the Product class will look for "productid" instead of "id" as
328  
-    # the primary column. If the latter is specified, the Product class will look for "product_id" instead of "id". Remember
  355
+    # Accessor for the prefix type that will be prepended to every primary key column name. 
  356
+    # The options are :table_name and :table_name_with_underscore. If the first is specified, 
  357
+    # the Product class will look for "productid" instead of "id" as the primary column. If the 
  358
+    # latter is specified, the Product class will look for "product_id" instead of "id". Remember
329 359
     # that this is a global setting for all Active Records.
330 360
     cattr_accessor :primary_key_prefix_type, :instance_writer => false
331 361
     @@primary_key_prefix_type = nil
332 362
 
333 363
     ##
334 364
     # :singleton-method:
335  
-    # Accessor for the name of the prefix string to prepend to every table name. So if set to "basecamp_", all
336  
-    # table names will be named like "basecamp_projects", "basecamp_people", etc. This is a convenient way of creating a namespace
337  
-    # for tables in a shared database. By default, the prefix is the empty string.
  365
+    # Accessor for the name of the prefix string to prepend to every table name. So if set 
  366
+    # to "basecamp_", all table names will be named like "basecamp_projects", "basecamp_people", 
  367
+    # etc. This is a convenient way of creating a namespace for tables in a shared database. 
  368
+    # By default, the prefix is the empty string.
338 369
     #
339  
-    # If you are organising your models within modules you can add a prefix to the models within a namespace by defining
340  
-    # a singleton method in the parent module called table_name_prefix which returns your chosen prefix.
  370
+    # If you are organising your models within modules you can add a prefix to the models within 
  371
+    # a namespace by defining a singleton method in the parent module called table_name_prefix which 
  372
+    # returns your chosen prefix.
341 373
     class_attribute :table_name_prefix, :instance_writer => false
342 374
     self.table_name_prefix = ""
343 375
 
@@ -358,8 +390,8 @@ def subclasses
358 390
 
359 391
     ##
360 392
     # :singleton-method:
361  
-    # Determines whether to use Time.local (using :local) or Time.utc (using :utc) when pulling dates and times from the database.
362  
-    # This is set to :local by default.
  393
+    # Determines whether to use Time.local (using :local) or Time.utc (using :utc) when pulling 
  394
+    # dates and times from the database. This is set to :local by default.
363 395
     cattr_accessor :default_timezone, :instance_writer => false
364 396
     @@default_timezone = :local
365 397
 
@@ -505,15 +537,18 @@ def serialize(attr_name, class_name = Object)
505 537
         serialized_attributes[attr_name.to_s] = class_name
506 538
       end
507 539
 
508  
-      # Returns a hash of all the attributes that have been specified for serialization as keys and their class restriction as values.
  540
+      # Returns a hash of all the attributes that have been specified for serialization as 
  541
+      # keys and their class restriction as values.
509 542
       def serialized_attributes
510 543
         read_inheritable_attribute(:attr_serialized) or write_inheritable_attribute(:attr_serialized, {})
511 544
       end
512 545
 
513  
-      # Guesses the table name (in forced lower-case) based on the name of the class in the inheritance hierarchy descending
514  
-      # directly from ActiveRecord::Base. So if the hierarchy looks like: Reply < Message < ActiveRecord::Base, then Message is used
515  
-      # to guess the table name even when called on Reply. The rules used to do the guess are handled by the Inflector class
516  
-      # in Active Support, which knows almost all common English inflections. You can add new inflections in config/initializers/inflections.rb.
  546
+      # Guesses the table name (in forced lower-case) based on the name of the class in the 
  547
+      # inheritance hierarchy descending directly from ActiveRecord::Base. So if the hierarchy 
  548
+      # looks like: Reply < Message < ActiveRecord::Base, then Message is used
  549
+      # to guess the table name even when called on Reply. The rules used to do the guess 
  550
+      # are handled by the Inflector class in Active Support, which knows almost all common 
  551
+      # English inflections. You can add new inflections in config/initializers/inflections.rb.
517 552
       #
518 553
       # Nested classes are given table names prefixed by the singular form of
519 554
       # the parent's table name. Enclosing modules are not considered.
@@ -923,15 +958,18 @@ def compute_table_name
923 958
           end
924 959
         end
925 960
 
926  
-        # Enables dynamic finders like <tt>find_by_user_name(user_name)</tt> and <tt>find_by_user_name_and_password(user_name, password)</tt>
927  
-        # that are turned into <tt>where(:user_name => user_name).first</tt> and <tt>where(:user_name => user_name, :password => :password).first</tt>
928  
-        # respectively. Also works for <tt>all</tt> by using <tt>find_all_by_amount(50)</tt> that is turned into <tt>where(:amount => 50).all</tt>.
  961
+        # Enables dynamic finders like <tt>find_by_user_name(user_name)</tt> and 
  962
+        # <tt>find_by_user_name_and_password(user_name, password)</tt> that are turned into 
  963
+        # <tt>where(:user_name => user_name).first</tt> and 
  964
+        # <tt>where(:user_name => user_name, :password => :password).first</tt>
  965
+        # respectively. Also works for <tt>all</tt> by using <tt>find_all_by_amount(50)</tt> 
  966
+        # that is turned into <tt>where(:amount => 50).all</tt>.
929 967
         #
930  
-        # It's even possible to use all the additional parameters to +find+. For example, the full interface for +find_all_by_amount+
931  
-        # is actually <tt>find_all_by_amount(amount, options)</tt>.
  968
+        # It's even possible to use all the additional parameters to +find+. For example, the 
  969
+        # full interface for +find_all_by_amount+ is actually <tt>find_all_by_amount(amount, options)</tt>.
932 970
         #
933  
-        # Each dynamic finder, scope or initializer/creator is also defined in the class after it is first invoked, so that future
934  
-        # attempts to use it do not run through method_missing.
  971
+        # Each dynamic finder, scope or initializer/creator is also defined in the class after it 
  972
+        # is first invoked, so that future attempts to use it do not run through method_missing.
935 973
         def method_missing(method_id, *arguments, &block)
936 974
           if match = DynamicFinderMatch.match(method_id)
937 975
             attribute_names = match.attribute_names
@@ -1607,10 +1645,11 @@ def clone_attribute_value(reader_method, attribute_name)
1607 1645
 
1608 1646
     private
1609 1647
 
1610  
-      # Sets the attribute used for single table inheritance to this class name if this is not the ActiveRecord::Base descendant.
1611  
-      # Considering the hierarchy Reply < Message < ActiveRecord::Base, this makes it possible to do Reply.new without having to
1612  
-      # set <tt>Reply[Reply.inheritance_column] = "Reply"</tt> yourself. No such attribute would be set for objects of the
1613  
-      # Message class in that example.
  1648
+      # Sets the attribute used for single table inheritance to this class name if this is not the 
  1649
+      # ActiveRecord::Base descendant.
  1650
+      # Considering the hierarchy Reply < Message < ActiveRecord::Base, this makes it possible to 
  1651
+      # do Reply.new without having to set <tt>Reply[Reply.inheritance_column] = "Reply"</tt> yourself. 
  1652
+      # No such attribute would be set for objects of the Message class in that example.
1614 1653
       def ensure_proper_type
1615 1654
         unless self.class.descends_from_active_record?
1616 1655
           write_attribute(self.class.inheritance_column, self.class.sti_name)
@@ -1659,8 +1698,9 @@ def interpolate_sql(sql, record = nil)
1659 1698
       # by calling new on the column type or aggregation type (through composed_of) object with these parameters.
1660 1699
       # So having the pairs written_on(1) = "2004", written_on(2) = "6", written_on(3) = "24", will instantiate
1661 1700
       # written_on (a date type) with Date.new("2004", "6", "24"). You can also specify a typecast character in the
1662  
-      # parentheses to have the parameters typecasted before they're used in the constructor. Use i for Fixnum, f for Float,
1663  
-      # s for String, and a for Array. If all the values for a given attribute are empty, the attribute will be set to nil.
  1701
+      # parentheses to have the parameters typecasted before they're used in the constructor. Use i for Fixnum, 
  1702
+      # f for Float, s for String, and a for Array. If all the values for a given attribute are empty, the 
  1703
+      # attribute will be set to nil.
1664 1704
       def assign_multiparameter_attributes(pairs)
1665 1705
         execute_callstack_for_multiparameter_attributes(
1666 1706
           extract_callstack_for_multiparameter_attributes(pairs)
14  activerecord/lib/active_record/relation.rb
@@ -67,7 +67,8 @@ def to_a
67 67
       preload +=  @includes_values unless eager_loading?
68 68
       preload.each {|associations| @klass.send(:preload_associations, @records, associations) }
69 69
 
70  
-      # @readonly_value is true only if set explicitly. @implicit_readonly is true if there are JOINS and no explicit SELECT.
  70
+      # @readonly_value is true only if set explicitly. @implicit_readonly is true if there 
  71
+      # are JOINS and no explicit SELECT.
71 72
       readonly = @readonly_value.nil? ? @implicit_readonly : @readonly_value
72 73
       @records.each { |record| record.readonly! } if readonly
73 74
 
@@ -130,7 +131,8 @@ def scoping
130 131
     # ==== Parameters
131 132
     #
132 133
     # * +updates+ - A string, array, or hash representing the SET part of an SQL statement.
133  
-    # * +conditions+ - A string, array, or hash representing the WHERE part of an SQL statement. See conditions in the intro.
  134
+    # * +conditions+ - A string, array, or hash representing the WHERE part of an SQL statement. 
  135
+    #   See conditions in the intro.
134 136
     # * +options+ - Additional options are <tt>:limit</tt> and <tt>:order</tt>, see the examples for usage.
135 137
     #
136 138
     # ==== Examples
@@ -144,7 +146,7 @@ def scoping
144 146
     #   # Update all avatars migrated more than a week ago
145 147
     #   Avatar.update_all ['migrated_at = ?', Time.now.utc], ['migrated_at > ?', 1.week.ago]
146 148
     #
147  
-    #   # Update all books that match our conditions, but limit it to 5 ordered by date
  149
+    #   # Update all books that match conditions, but limit it to 5 ordered by date
148 150
     #   Book.update_all "author = 'David'", "title LIKE '%Rails%'", :order => 'created_at', :limit => 5
149 151
     def update_all(updates, conditions = nil, options = {})
150 152
       if conditions || options.present?
@@ -165,14 +167,14 @@ def update_all(updates, conditions = nil, options = {})
165 167
     # ==== Parameters
166 168
     #
167 169
     # * +id+ - This should be the id or an array of ids to be updated.
168  
-    # * +attributes+ - This should be a hash of attributes to be set on the object, or an array of hashes.
  170
+    # * +attributes+ - This should be a hash of attributes or an array of hashes.
169 171
     #
170 172
     # ==== Examples
171 173
     #
172  
-    #   # Updating one record:
  174
+    #   # Updates one record
173 175
     #   Person.update(15, :user_name => 'Samuel', :group => 'expert')
174 176
     #
175  
-    #   # Updating multiple records:
  177
+    #   # Updates multiple records
176 178
     #   people = { 1 => { "first_name" => "David" }, 2 => { "first_name" => "Jeremy" } }
177 179
     #   Person.update(people.keys, people.values)
178 180
     def update(id, attributes)

0 notes on commit b8d9d9c

Please sign in to comment.
Something went wrong with that request. Please try again.