Add documentation for freeze and readonly related methods. Closes #8878 [pelargir, jeremymcanally]

git-svn-id: http://svn-commit.rubyonrails.org/rails/trunk@8286 5ecf4fe2-1ee6-0310-87b1-e25e094e27de

activerecord/CHANGELOG

@@ -1,5 +1,7 @@
 *SVN*
 
+* Add documentation for freeze and readonly related methods. Closes #8878 [pelargir, jeremymcanally]
+
 * Document the timestamps schema definition method. Closes #9000 [mikong]
 
 * Give examples for what tables should be called for models inside a module namespace. Closes #10288 [scott_willson]

activerecord/lib/active_record/base.rb

@@ -2026,25 +2026,28 @@ def hash
         id.hash
       end
 
-      # Just freeze the attributes hash, such that associations are still accessible even on destroyed records.
+      # Freeze the attributes hash such that associations are still accessible, even on destroyed records.
       def freeze
         @attributes.freeze; self
       end
 
+      # Returns +true+ if the attributes hash has been frozen.
       def frozen?
         @attributes.frozen?
       end
 
-      # Records loaded through joins with piggy-back attributes will be marked as read only as they cannot be saved and return true to this query.
+      # Returns +true+ if the record is read only. Records loaded through joins with piggy-back
+      # attributes will be marked as read only since they cannot be saved.
       def readonly?
         @readonly == true
       end
 
-      def readonly! #:nodoc:
+      # Marks this record as read only.
+      def readonly!
         @readonly = true
       end
 
-      # Nice pretty inspect.
+      # Returns the contents of the record as a nicely formatted string.
       def inspect
         attributes_as_nice_string = self.class.column_names.collect { |name|
           if has_attribute?(name) || new_record?