Skip to content
This repository
Browse code

minor details revised in attribute_methods.rb docs

  • Loading branch information...
commit 654e77597ba1e5b64a2be2e5e21cd542aafcfbb0 1 parent cbd5db8
Xavier Noria authored
42  activerecord/lib/active_record/attribute_methods.rb
@@ -16,16 +16,20 @@ def self.included(base)
16 16
 
17 17
     # Declare and check for suffixed attribute methods.
18 18
     module ClassMethods
19  
-      # Declare a method available for all attributes with the given suffix.
20  
-      # Uses method_missing and respond_to? to rewrite the method
  19
+      # Declares a method available for all attributes with the given suffix.
  20
+      # Uses +method_missing+ and <tt>respond_to?</tt> to rewrite the method
  21
+      #
21 22
       #   #{attr}#{suffix}(*args, &block)
  23
+      #
22 24
       # to
  25
+      #
23 26
       #   attribute#{suffix}(#{attr}, *args, &block)
24 27
       #
25  
-      # An attribute#{suffix} instance method must exist and accept at least
26  
-      # the attr argument.
  28
+      # An <tt>attribute#{suffix}</tt> instance method must exist and accept at least
  29
+      # the +attr+ argument.
27 30
       #
28 31
       # For example:
  32
+      #
29 33
       #   class Person < ActiveRecord::Base
30 34
       #     attribute_method_suffix '_changed?'
31 35
       #
@@ -60,8 +64,8 @@ def generated_methods?
60 64
         !generated_methods.empty?
61 65
       end
62 66
       
63  
-      # generates all the attribute related methods for columns in the database
64  
-      # accessors, mutators and query methods
  67
+      # Generates all the attribute related methods for columns in the database
  68
+      # accessors, mutators and query methods.
65 69
       def define_attribute_methods
66 70
         return if generated_methods?
67 71
         columns_hash.each do |name, column|
@@ -89,8 +93,9 @@ def define_attribute_methods
89 93
         end
90 94
       end
91 95
 
92  
-      # Check to see if the method is defined in the model or any of its subclasses that also derive from ActiveRecord.
93  
-      # Raise DangerousAttributeError if the method is defined by ActiveRecord though.
  96
+      # Checks whether the method is defined in the model or any of its subclasses
  97
+      # that also derive from ActiveRecord. Raises DangerousAttributeError if the
  98
+      # method is defined by Active Record though.
94 99
       def instance_method_already_implemented?(method_name)
95 100
         method_name = method_name.to_s
96 101
         return true if method_name =~ /^id(=$|\?$|$)/
@@ -104,19 +109,19 @@ def instance_method_already_implemented?(method_name)
104 109
 
105 110
       # +cache_attributes+ allows you to declare which converted attribute values should
106 111
       # be cached. Usually caching only pays off for attributes with expensive conversion
107  
-      # methods, like time related columns (e.g. created_at, updated_at).
  112
+      # methods, like time related columns (e.g. +created_at+, +updated_at+).
108 113
       def cache_attributes(*attribute_names)
109 114
         attribute_names.each {|attr| cached_attributes << attr.to_s}
110 115
       end
111 116
 
112  
-      # returns the attributes which are cached.
113  
-      # By default time related columns with datatype <tt>:datetime, :timestamp, :time, :date</tt> are cached
  117
+      # Returns the attributes which are cached. By default time related columns
  118
+      # with datatype <tt>:datetime, :timestamp, :time, :date</tt> are cached.
114 119
       def cached_attributes
115 120
         @cached_attributes ||=
116 121
           columns.select{|c| attribute_types_cached_by_default.include?(c.type)}.map(&:name).to_set
117 122
       end
118 123
 
119  
-      # returns true if the provided attribute is being cached
  124
+      # Returns +true+ if the provided attribute is being cached.
120 125
       def cache_attribute?(attr_name)
121 126
         cached_attributes.include?(attr_name)
122 127
       end
@@ -212,14 +217,14 @@ def evaluate_attribute_method(attr_name, method_definition, method_name=attr_nam
212 217
     end #  ClassMethods
213 218
 
214 219
 
215  
-    # Allows access to the object attributes, which are held in the @attributes hash, as though they
  220
+    # Allows access to the object attributes, which are held in the <tt>@attributes</tt> hash, as though they
216 221
     # were first-class methods. So a Person class with a name attribute can use Person#name and
217 222
     # Person#name= and never directly use the attributes hash -- except for multiple assigns with
218 223
     # ActiveRecord#attributes=. A Milestone class can also ask Milestone#completed? to test that
219  
-    # the completed attribute is not nil or 0.
  224
+    # the completed attribute is not +nil+ or 0.
220 225
     #
221 226
     # It's also possible to instantiate related objects, so a Client class belonging to the clients
222  
-    # table with a master_id foreign key can instantiate master through Client#master.
  227
+    # table with a +master_id+ foreign key can instantiate master through Client#master.
223 228
     def method_missing(method_id, *args, &block)
224 229
       method_name = method_id.to_s
225 230
 
@@ -290,7 +295,7 @@ def unserialize_attribute(attr_name)
290 295
   
291 296
 
292 297
     # Updates the attribute identified by <tt>attr_name</tt> with the specified +value+. Empty strings for fixnum and float
293  
-    # columns are turned into nil.
  298
+    # columns are turned into +nil+.
294 299
     def write_attribute(attr_name, value)
295 300
       attr_name = attr_name.to_s
296 301
       @attributes_cache.delete(attr_name)
@@ -321,8 +326,9 @@ def query_attribute(attr_name)
321 326
       end
322 327
     end
323 328
     
324  
-    # A Person object with a name attribute can ask person.respond_to?("name"), person.respond_to?("name="), and
325  
-    # person.respond_to?("name?") which will all return true.
  329
+    # A Person object with a name attribute can ask <tt>person.respond_to?("name")</tt>,
  330
+    # <tt>person.respond_to?("name=")</tt>, and <tt>person.respond_to?("name?")</tt>
  331
+    # which will all return +true+.
326 332
     alias :respond_to_without_attributes? :respond_to?
327 333
     def respond_to?(method, include_priv = false)
328 334
       method_name = method.to_s

0 notes on commit 654e775

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