Improve documentation coverage and markup

Signed-off-by: Pratik Naik <pratiknaik@gmail.com>

15 files changed, 203 insertions, 197 deletions

diff --git a/activerecord/lib/active_record/associations/association_proxy.rb b/activerecord/lib/active_record/associations/association_proxy.rb
index df21124e92..c415ad2df3 100644
--- a/activerecord/lib/active_record/associations/association_proxy.rb
+++ b/activerecord/lib/active_record/associations/association_proxy.rb
@@ -179,6 +179,16 @@ module ActiveRecord
           end
         end
 
+        # Loads the target if needed and returns it.
+        #
+        # This method is abstract in the sense that it relies on +find_target+,
+        # which is expected to be provided by descendants.
+        #
+        # If the target is already loaded it is just returned. Thus, you can call
+        # +load_target+ unconditionally to get the target.
+        #
+        # ActiveRecord::RecordNotFound is rescued within the method, and it is
+        # not reraised. The proxy is reset and +nil+ is the return value.
         def load_target
           return nil unless defined?(@loaded)
 
diff --git a/activerecord/lib/active_record/base.rb b/activerecord/lib/active_record/base.rb
index 4f4ba83a47..ffefc3cef3 100755
--- a/activerecord/lib/active_record/base.rb
+++ b/activerecord/lib/active_record/base.rb
@@ -11,22 +11,18 @@ module ActiveRecord #:nodoc:
   class SubclassNotFound < ActiveRecordError #:nodoc:
   end
 
-  # Raised when object assigned to association is of incorrect type.
+  # Raised when an object assigned to an association has an incorrect type.
   #
-  # Example:
-  #
-  # class Ticket < ActiveRecord::Base
-  #   has_many :patches
-  # end
-  #
-  # class Patch < ActiveRecord::Base
-  #   belongs_to :ticket
-  # end
+  #   class Ticket < ActiveRecord::Base
+  #     has_many :patches
+  #   end
   #
-  # and somewhere in the code:
+  #   class Patch < ActiveRecord::Base
+  #     belongs_to :ticket
+  #   end
   #
-  # @ticket.patches << Comment.new(:content => "Please attach tests to your patch.")
-  # @ticket.save
+  #   # Comments are not patches, this assignment raises AssociationTypeMismatch.
+  #   @ticket.patches << Comment.new(:content => "Please attach tests to your patch.")
   class AssociationTypeMismatch < ActiveRecordError
   end
 
@@ -59,14 +55,14 @@ module ActiveRecord #:nodoc:
   class StatementInvalid < ActiveRecordError
   end
 
-  # Raised when number of bind variables in statement given to :condition key (for example, when using +find+ method)
+  # Raised when number of bind variables in statement given to <tt>:condition</tt> key (for example, when using +find+ method)
   # does not match number of expected variables.
   #
-  # Example:
+  # For example, in
   #
-  # Location.find :all, :conditions => ["lat = ? AND lng = ?", 53.7362]
+  #   Location.find :all, :conditions => ["lat = ? AND lng = ?", 53.7362]
   #
-  # in example above two placeholders are given but only one variable to fill them.
+  # two placeholders are given but only one variable to fill them.
   class PreparedStatementInvalid < ActiveRecordError
   end
 
@@ -97,8 +93,8 @@ module ActiveRecord #:nodoc:
   end
 
   # Raised when you've tried to access a column which wasn't
-  # loaded by your finder.  Typically this is because :select
-  # has been specified
+  # loaded by your finder.  Typically this is because <tt>:select</tt>
+  # has been specified.
   class MissingAttributeError < NoMethodError
   end
 
@@ -206,7 +202,7 @@ module ActiveRecord #:nodoc:
   #     # Uses an integer of seconds to hold the length of the song
   #
   #     def length=(minutes)
-  #       write_attribute(:length, minutes * 60)
+  #       write_attribute(:length, minutes.to_i * 60)
   #     end
   #
   #     def length
@@ -256,7 +252,7 @@ module ActiveRecord #:nodoc:
   #
   # It's even possible to use all the additional parameters to find. For example, the full interface for Payment.find_all_by_amount
   # is actually Payment.find_all_by_amount(amount, options). And the full interface to Person.find_by_user_name is
-  # actually Person.find_by_user_name(user_name, options). So you could call <tt>Payment.find_all_by_amount(50, :order => "created_on")</tt>.
+  # actually <tt>Person.find_by_user_name(user_name, options)</tt>. So you could call <tt>Payment.find_all_by_amount(50, :order => "created_on")</tt>.
   #
   # The same dynamic finder style can be used to create the object if it doesn't already exist. This dynamic finder is called with
   # <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:
@@ -457,9 +453,9 @@ module ActiveRecord #:nodoc:
       # * <tt>:limit</tt>: An integer determining the limit on the number of rows that should be returned.
       # * <tt>:offset</tt>: An integer determining the offset from where the rows should be fetched. So at 5, it would skip rows 0 through 4.
       # * <tt>:joins</tt>: Either an SQL fragment for additional joins like "LEFT JOIN comments ON comments.post_id = id" (rarely needed)
-      #   or named associations in the same form used for the :include option, which will perform an INNER JOIN on the associated table(s).
+      #   or named associations in the same form used for the <tt>:include</tt> option, which will perform an INNER JOIN on the associated table(s).
       #   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.
+      #   Pass <tt>:readonly => false</tt> to override.
       # * <tt>:include</tt>: Names associations that should be loaded alongside using LEFT OUTER JOINs. The symbols named refer
       #   to already defined associations. See eager loading under Associations.
       # * <tt>:select</tt>: By default, this is * as in SELECT * FROM, but can be changed if you, for example, want to do a join but not
@@ -468,7 +464,7 @@ module ActiveRecord #:nodoc:
       #   of a database view).
       # * <tt>:readonly</tt>: Mark the returned records read-only so they cannot be saved or updated.
       # * <tt>:lock</tt>: An SQL fragment like "FOR UPDATE" or "LOCK IN SHARE MODE".
-      #   :lock => true gives connection's default exclusive lock, usually "FOR UPDATE".
+      #   <tt>:lock => true</tt> gives connection's default exclusive lock, usually "FOR UPDATE".
       #
       # Examples for find by id:
       #   Person.find(1)       # returns the object for ID = 1
@@ -478,7 +474,7 @@ module ActiveRecord #:nodoc:
       #   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
-      # provide since database rows are unordered. Give an explicit :order
+      # provide since database rows are unordered. Give an explicit <tt>:order</tt>
       # to ensure the results are sorted.
       #
       # Examples for find first:
@@ -711,7 +707,7 @@ module ActiveRecord #:nodoc:
       # +updates+     A String of column and value pairs that will be set on any records that match conditions
       # +conditions+  An SQL fragment like "administrator = 1" or [ "user_name = ?", username ].
       #               See conditions in the intro for more info.
-      # +options+     Additional options are :limit and/or :order, see the examples for usage.
+      # +options+     Additional options are <tt>:limit</tt> and/or <tt>:order</tt>, see the examples for usage.
       #
       # ==== Examples
       #
@@ -1521,7 +1517,7 @@ module ActiveRecord #:nodoc:
           end
         end
 
-        # The optional scope argument is for the current :find scope.
+        # The optional scope argument is for the current <tt>:find</tt> scope.
         def add_limit!(sql, options, scope = :auto)
           scope = scope(:find) if :auto == scope
 
@@ -1533,15 +1529,15 @@ module ActiveRecord #:nodoc:
           connection.add_limit_offset!(sql, options)
         end
 
-        # The optional scope argument is for the current :find scope.
-        # The :lock option has precedence over a scoped :lock.
+        # The optional scope argument is for the current <tt>:find</tt> scope.
+        # The <tt>:lock</tt> option has precedence over a scoped <tt>:lock</tt>.
         def add_lock!(sql, options, scope = :auto)
           scope = scope(:find) if :auto == scope
           options = options.reverse_merge(:lock => scope[:lock]) if scope
           connection.add_lock!(sql, options)
         end
 
-        # The optional scope argument is for the current :find scope.
+        # The optional scope argument is for the current <tt>:find</tt> scope.
         def add_joins!(sql, options, scope = :auto)
           scope = scope(:find) if :auto == scope
           [(scope && scope[:joins]), options[:joins]].each do |join|
@@ -1556,7 +1552,7 @@ module ActiveRecord #:nodoc:
         end
 
         # Adds a sanitized version of +conditions+ to the +sql+ string. Note that the passed-in +sql+ string is changed.
-        # The optional scope argument is for the current :find scope.
+        # The optional scope argument is for the current <tt>:find</tt> scope.
         def add_conditions!(sql, conditions, scope = :auto)
           scope = scope(:find) if :auto == scope
           conditions = [conditions]
@@ -1753,8 +1749,8 @@ module ActiveRecord #:nodoc:
 
       protected
         # Scope parameters to method calls within the block.  Takes a hash of method_name => parameters hash.
-        # method_name may be :find or :create. :find parameters may include the <tt>:conditions</tt>, <tt>:joins</tt>,
-        # <tt>:include</tt>, <tt>:offset</tt>, <tt>:limit</tt>, and <tt>:readonly</tt> options. :create parameters are an attributes hash.
+        # method_name may be <tt>:find</tt> or <tt>:create</tt>. <tt>:find</tt> parameters may include the <tt>:conditions</tt>, <tt>:joins</tt>,
+        # <tt>:include</tt>, <tt>:offset</tt>, <tt>:limit</tt>, and <tt>:readonly</tt> options. <tt>:create</tt> parameters are an attributes hash.
         #
         #   class Article < ActiveRecord::Base
         #     def self.create_with_scope
@@ -1767,7 +1763,7 @@ module ActiveRecord #:nodoc:
         #   end
         #
         # In nested scopings, all previous parameters are overwritten by the innermost rule, with the exception of
-        # :conditions and :include options in :find, which are merged.
+        # <tt>:conditions</tt> and <tt>:include</tt> options in <tt>:find</tt>, which are merged.
         #
         #   class Article < ActiveRecord::Base
         #     def self.find_with_scope
@@ -2217,9 +2213,9 @@ module ActiveRecord #:nodoc:
         record
       end
 
-      # Returns an instance of the specified klass with the attributes of the current record. This is mostly useful in relation to
+      # Returns an instance of the specified +klass+ with the attributes of the current record. This is mostly useful in relation to
       # single-table inheritance structures where you want a subclass to appear as the superclass. This can be used along with record
-      # identification in Action Pack to allow, say, Client < Company to do something like render :partial => @client.becomes(Company)
+      # identification in Action Pack to allow, say, <tt>Client < Company</tt> to do something like render <tt>:partial => @client.becomes(Company)</tt>
       # to render that instance using the companies/company partial instead of clients/client.
       #
       # Note: The new instance will share a link to the same attributes as the original class. So any change to the attributes in either
diff --git a/activerecord/lib/active_record/calculations.rb b/activerecord/lib/active_record/calculations.rb
index b5bf82ee11..3c5caefe3b 100644
--- a/activerecord/lib/active_record/calculations.rb
+++ b/activerecord/lib/active_record/calculations.rb
@@ -9,16 +9,16 @@ module ActiveRecord
       # Count operates using three different approaches.
       #
       # * Count all: By not passing any parameters to count, it will return a count of all the rows for the model.
-      # * Count using column : By passing a column name to count, it will return a count of all the rows for the model with supplied column present
+      # * Count using column: By passing a column name to count, it will return a count of all the rows for the model with supplied column present
       # * Count using options will find the row count matched by the options used.
       #
       # The third approach, count using options, accepts an option hash as the only parameter. The options are:
       #
       # * <tt>:conditions</tt>: An SQL fragment like "administrator = 1" or [ "user_name = ?", username ]. See conditions in the intro.
       # * <tt>:joins</tt>: Either an SQL fragment for additional joins like "LEFT JOIN comments ON comments.post_id = id" (rarely needed)
-      #   or named associations in the same form used for the :include option, which will perform an INNER JOIN on the associated table(s).
+      #   or named associations in the same form used for the <tt>:include</tt> option, which will perform an INNER JOIN on the associated table(s).
       #   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.
+      #   Pass <tt>:readonly => false</tt> to override.
       # * <tt>:include</tt>: Named associations that should be loaded alongside using LEFT OUTER JOINs. The symbols named refer
       #   to already defined associations. When using named associations, count returns the number of DISTINCT items for the model you're counting.
       #   See eager loading under Associations.
@@ -41,7 +41,7 @@ module ActiveRecord
       #   Person.count('id', :conditions => "age > 26") # Performs a COUNT(id)
       #   Person.count(:all, :conditions => "age > 26") # Performs a COUNT(*) (:all is an alias for '*')
       #
-      # Note: Person.count(:all) will not work because it will use :all as the condition.  Use Person.count instead.
+      # Note: <tt>Person.count(:all)</tt> will not work because it will use <tt>:all</tt> as the condition.  Use Person.count instead.
       def count(*args)
         calculate(:count, *construct_count_options_from_args(*args))
       end
@@ -75,11 +75,11 @@ module ActiveRecord
       end
 
       # 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.
+      # Options such as <tt>:conditions</tt>, <tt>:order</tt>, <tt>:group</tt>, <tt>:having</tt>, and <tt>:joins</tt> can be passed to customize the query.
       #
       # There are two basic forms of output:
       #   * Single aggregate value: The single value is type cast to Fixnum for COUNT, Float for AVG, and the given column's type for everything else.
-      #   * Grouped values: This returns an ordered hash of the values and groups them by the :group option.  It takes either a column name, or the name
+      #   * Grouped values: This returns an ordered hash of the values and groups them by the <tt>:group</tt> option.  It takes either a column name, or the name
       #     of a belongs_to association.
       #
       #       values = Person.maximum(:age, :group => 'last_name')
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 d950181566..34627dfaf9 100644
--- a/activerecord/lib/active_record/connection_adapters/abstract/connection_specification.rb
+++ b/activerecord/lib/active_record/connection_adapters/abstract/connection_specification.rb
@@ -175,7 +175,7 @@ module ActiveRecord
     end
 
     # Establishes the connection to the database. Accepts a hash as input where
-    # the :adapter key must be specified with the name of a database adapter (in lower-case)
+    # the <tt>:adapter</tt> key must be specified with the name of a database adapter (in lower-case)
     # example for regular databases (MySQL, Postgresql, etc):
     #
     #   ActiveRecord::Base.establish_connection(
@@ -194,6 +194,7 @@ module ActiveRecord
     #   )
     #
     # Also accepts keys as strings (for parsing from yaml for example):
+    #
     #   ActiveRecord::Base.establish_connection(
     #     "adapter" => "sqlite",
     #     "database"  => "path/to/dbfile"
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 d30f9b4d32..7cf64f4ef8 100644
--- a/activerecord/lib/active_record/connection_adapters/abstract/schema_definitions.rb
+++ b/activerecord/lib/active_record/connection_adapters/abstract/schema_definitions.rb
@@ -398,8 +398,8 @@ module ActiveRecord
       # TableDefinition#timestamps that'll add created_at and updated_at as datetimes.
       #
       # TableDefinition#references will add an appropriately-named _id column, plus a corresponding _type
-      # column if the :polymorphic option is supplied. If :polymorphic is a hash of options, these will be
-      # used when creating the _type column. So what can be written like this:
+      # column if the <tt>:polymorphic</tt> option is supplied. If <tt>:polymorphic</tt> is a hash of options, these will be
+      # used when creating the <tt>_type</tt> column. So what can be written like this:
       #
       #   create_table :taggings do |t|
       #     t.integer :tag_id, :tagger_id, :taggable_id
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 86216b6083..64a7e9fabe 100644
--- a/activerecord/lib/active_record/connection_adapters/abstract/schema_statements.rb
+++ b/activerecord/lib/active_record/connection_adapters/abstract/schema_statements.rb
@@ -45,7 +45,7 @@ module ActiveRecord
       # The +options+ hash can include the following keys:
       # [<tt>:id</tt>]
       #   Whether to automatically add a primary key column. Defaults to true.
-      #   Join tables for has_and_belongs_to_many should set :id => false.
+      #   Join tables for +has_and_belongs_to_many+ should set <tt>:id => false</tt>.
       # [<tt>:primary_key</tt>]
       #   The name of the primary key, if one is to be added automatically.
       #   Defaults to +id+.
diff --git a/activerecord/lib/active_record/connection_adapters/mysql_adapter.rb b/activerecord/lib/active_record/connection_adapters/mysql_adapter.rb
index 0bee34cdf1..e742d60c5f 100755
--- a/activerecord/lib/active_record/connection_adapters/mysql_adapter.rb
+++ b/activerecord/lib/active_record/connection_adapters/mysql_adapter.rb
@@ -365,7 +365,7 @@ module ActiveRecord
         create_database(name)
       end
 
-      # Create a new MySQL database with optional :charset and :collation.
+      # Create a new MySQL database with optional <tt>:charset</tt> and <tt>:collation</tt>.
       # Charset defaults to utf8.
       #
       # Example:
diff --git a/activerecord/lib/active_record/connection_adapters/postgresql_adapter.rb b/activerecord/lib/active_record/connection_adapters/postgresql_adapter.rb
index 54b50fabd8..e3f7969cdf 100644
--- a/activerecord/lib/active_record/connection_adapters/postgresql_adapter.rb
+++ b/activerecord/lib/active_record/connection_adapters/postgresql_adapter.rb
@@ -233,7 +233,7 @@ module ActiveRecord
     # * <tt>:username</tt> -- Defaults to nothing
     # * <tt>:password</tt> -- Defaults to nothing
     # * <tt>:database</tt> -- The name of the database. No default, must be provided.
-    # * <tt>:schema_search_path</tt> -- An optional schema search path for the connection given as a string of comma-separated schema names.  This is backward-compatible with the :schema_order option.
+    # * <tt>:schema_search_path</tt> -- An optional schema search path for the connection given as a string of comma-separated schema names.  This is backward-compatible with the <tt>:schema_order</tt> option.
     # * <tt>:encoding</tt> -- An optional client encoding that is used in a SET client_encoding TO <encoding> call on the connection.
     # * <tt>:min_messages</tt> -- An optional client min messages that is used in a SET client_min_messages TO <min_messages> call on the connection.
     # * <tt>:allow_concurrency</tt> -- If true, use async query methods so Ruby threads don't deadlock; otherwise, use blocking query methods.
@@ -479,9 +479,9 @@ module ActiveRecord
         create_database(name)
       end
 
-      # Create a new PostgreSQL database.  Options include :owner, :template,
-      # :encoding, :tablespace, and :connection_limit (note that MySQL uses
-      # :charset while PostgreSQL uses :encoding).
+      # Create a new PostgreSQL database.  Options include <tt>:owner</tt>, <tt>:template</tt>,
+      # <tt>:encoding</tt>, <tt>:tablespace</tt>, and <tt>:connection_limit</tt> (note that MySQL uses
+      # <tt>:charset</tt> while PostgreSQL uses <tt>:encoding</tt>).
       #
       # Example:
       #   create_database config[:database], config
diff --git a/activerecord/lib/active_record/locking/pessimistic.rb b/activerecord/lib/active_record/locking/pessimistic.rb
index caad760742..320659596f 100644
--- a/activerecord/lib/active_record/locking/pessimistic.rb
+++ b/activerecord/lib/active_record/locking/pessimistic.rb
@@ -25,12 +25,12 @@ module ActiveRecord
     # Locking::Pessimistic provides support for row-level locking using
     # SELECT ... FOR UPDATE and other lock types.
     #
-    # Pass :lock => true to ActiveRecord::Base.find to obtain an exclusive
+    # Pass <tt>:lock => true</tt> to ActiveRecord::Base.find to obtain an exclusive
     # lock on the selected rows:
     #   # select * from accounts where id=1 for update
     #   Account.find(1, :lock => true)
     #
-    # Pass :lock => 'some locking clause' to give a database-specific locking clause
+    # Pass <tt>:lock => 'some locking clause'</tt> to give a database-specific locking clause
     # of your own such as 'LOCK IN SHARE MODE' or 'FOR UPDATE NOWAIT'.
     #
     # Example:
diff --git a/activerecord/lib/active_record/migration.rb b/activerecord/lib/active_record/migration.rb
index 1d63bb2f84..af4fb6e83c 100644
--- a/activerecord/lib/active_record/migration.rb
+++ b/activerecord/lib/active_record/migration.rb
@@ -76,16 +76,16 @@ module ActiveRecord
   # * <tt>rename_table(old_name, new_name)</tt>: Renames the table called +old_name+ to +new_name+.
   # * <tt>add_column(table_name, column_name, type, options)</tt>: Adds a new column to the table called +table_name+
   #   named +column_name+ specified to be one of the following types:
-  #   :string, :text, :integer, :float, :decimal, :datetime, :timestamp, :time,
-  #   :date, :binary, :boolean. A default value can be specified by passing an
-  #   +options+ hash like { :default => 11 }. Other options include :limit and :null (e.g. { :limit => 50, :null => false })
+  #   <tt>:string</tt>, <tt>:text</tt>, <tt>:integer</tt>, <tt>:float</tt>, <tt>:decimal</tt>, <tt>:datetime</tt>, <tt>:timestamp</tt>, <tt>:time</tt>,
+  #   <tt>:date</tt>, <tt>:binary</tt>, <tt>:boolean</tt>. A default value can be specified by passing an
+  #   +options+ hash like <tt>{ :default => 11 }</tt>. Other options include <tt>:limit</tt> and <tt>:null</tt> (e.g. <tt>{ :limit => 50, :null => false }</tt>)
   #   -- see ActiveRecord::ConnectionAdapters::TableDefinition#column for details.
   # * <tt>rename_column(table_name, column_name, new_column_name)</tt>: Renames a column but keeps the type and content.
   # * <tt>change_column(table_name, column_name, type, options)</tt>:  Changes the column to a different type using the same
   #   parameters as add_column.
   # * <tt>remove_column(table_name, column_name)</tt>: Removes the column named +column_name+ from the table called +table_name+.
   # * <tt>add_index(table_name, column_names, options)</tt>: Adds a new index with the name of the column. Other options include
-  #   :name and :unique (e.g. { :name => "users_name_index", :unique => true }).
+  #   <tt>:name</tt> and <tt>:unique</tt> (e.g. <tt>{ :name => "users_name_index", :unique => true }</tt>).
   # * <tt>remove_index(table_name, index_name)</tt>: Removes the index specified by +index_name+.
   #
   # == Irreversible transformations
diff --git a/activerecord/lib/active_record/reflection.rb b/activerecord/lib/active_record/reflection.rb
index 3f11133e8c..61005af83f 100644
--- a/activerecord/lib/active_record/reflection.rb
+++ b/activerecord/lib/active_record/reflection.rb
@@ -45,7 +45,7 @@ module ActiveRecord
       end
 
       # 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. 
+      # certain association type, pass in the symbol (<tt>:has_many</tt>, <tt>:has_one</tt>, <tt>:belongs_to</tt>) for that as the first parameter.
       # Example:
       #
       #   Account.reflect_on_all_associations             # returns an array of all associations
@@ -90,13 +90,12 @@ module ActiveRecord
 
       # Returns the hash of options used for the macro.  For example, it would return <tt>{ :class_name => "Money" }</tt> for
       # <tt>composed_of :balance, :class_name => 'Money'</tt> or +{}+ for <tt>has_many :clients</tt>.
-
       def options
         @options
       end
 
-      # Returns the class for the macro.  For example, <tt>composed_of :balance, :class_name => 'Money'</tt> returns the +Money+
-      # class and <tt>has_many :clients</tt> returns the +Client+ class.
+      # Returns the class for the macro.  For example, <tt>composed_of :balance, :class_name => 'Money'</tt> returns the Money
+      # class and <tt>has_many :clients</tt> returns the Client class.
       def klass
         @klass ||= class_name.constantize
       end
@@ -158,16 +157,16 @@ module ActiveRecord
         @through_reflection ||= options[:through] ? active_record.reflect_on_association(options[:through]) : false
       end
 
-      # Gets an array of possible :through source reflection names
+      # Gets an array of possible <tt>:through</tt> source reflection names:
       #
-      #   [singularized, pluralized]
+      #   [:singularized, :pluralized]
       #
       def source_reflection_names
         @source_reflection_names ||= (options[:source] ? [options[:source]] : [name.to_s.singularize, name]).collect { |n| n.to_sym }
       end
 
-      # Gets the source of the through reflection.  It checks both a singularized and pluralized form for :belongs_to or :has_many.
-      # (The :tags association on Tagging below)
+      # Gets the source of the through reflection.  It checks both a singularized and pluralized form for <tt>:belongs_to</tt> or <tt>:has_many</tt>.
+      # (The <tt>:tags</tt> association on Tagging below.)
       # 
       #   class Post
       #     has_many :tags, :through => :taggings
diff --git a/activerecord/lib/active_record/serialization.rb b/activerecord/lib/active_record/serialization.rb
index 2c8210a299..332cda1e16 100644
--- a/activerecord/lib/active_record/serialization.rb
+++ b/activerecord/lib/active_record/serialization.rb
@@ -8,11 +8,11 @@ module ActiveRecord #:nodoc:
       end
 
       # To replicate the behavior in ActiveRecord#attributes,
-      # :except takes precedence over :only.  If :only is not set
+      # <tt>:except</tt> takes precedence over <tt>:only</tt>.  If <tt>:only</tt> is not set
       # for a N level model but is set for the N+1 level models,
-      # then because :except is set to a default value, the second
-      # level model can have both :except and :only set.  So if
-      # :only is set, always delete :except.
+      # then because <tt>:except</tt> is set to a default value, the second
+      # level model can have both <tt>:except</tt> and <tt>:only</tt> set.  So if
+      # <tt>:only</tt> is set, always delete <tt>:except</tt>.
       def serializable_attribute_names
         attribute_names = @record.attribute_names
 
@@ -38,7 +38,7 @@ module ActiveRecord #:nodoc:
         serializable_attribute_names + serializable_method_names
       end
 
-      # Add associations specified via the :includes option.
+      # Add associations specified via the <tt>:includes</tt> option.
       # Expects a block that takes as arguments:
       #   +association+ - name of the association
       #   +records+     - the association record(s) to be serialized
diff --git a/activerecord/lib/active_record/serializers/json_serializer.rb b/activerecord/lib/active_record/serializers/json_serializer.rb
index d024adba39..419b45d475 100644
--- a/activerecord/lib/active_record/serializers/json_serializer.rb
+++ b/activerecord/lib/active_record/serializers/json_serializer.rb
@@ -16,8 +16,8 @@ module ActiveRecord #:nodoc:
     #   # => {"id": 1, "name": "Konata Izumi", "age": 16,
     #         "created_at": "2006/08/01", "awesome": true}
     #
-    # The :only and :except options can be used to limit the attributes
-    # included, and work similar to the #attributes method. For example:
+    # The <tt>:only</tt> and <tt>:except</tt> options can be used to limit the attributes
+    # included, and work similar to the +attributes+ method. For example:
     #
     #   konata.to_json(:only => [ :id, :name ])
     #   # => {"id": 1, "name": "Konata Izumi"}
@@ -25,14 +25,14 @@ module ActiveRecord #:nodoc:
     #   konata.to_json(:except => [ :id, :created_at, :age ])
     #   # => {"name": "Konata Izumi", "awesome": true}
     #
-    # To include any methods on the model, use :methods.
+    # To include any methods on the model, use <tt>:methods</tt>.
     #
     #   konata.to_json(:methods => :permalink)
     #   # => {"id": 1, "name": "Konata Izumi", "age": 16,
     #         "created_at": "2006/08/01", "awesome": true,
     #         "permalink": "1-konata-izumi"}
     #
-    # To include associations, use :include.
+    # To include associations, use <tt>:include</tt>.
     #
     #   konata.to_json(:include => :posts)
     #   # => {"id": 1, "name": "Konata Izumi", "age": 16,
diff --git a/activerecord/lib/active_record/serializers/xml_serializer.rb b/activerecord/lib/active_record/serializers/xml_serializer.rb
index fbd15e06dc..2d0887ecf0 100644
--- a/activerecord/lib/active_record/serializers/xml_serializer.rb
+++ b/activerecord/lib/active_record/serializers/xml_serializer.rb
@@ -2,7 +2,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
-    # override ActiveRecord's to_xml method.
+    # override ActiveRecord::Base#to_xml.
     #
     # By default the generated XML document will include the processing
     # instruction and all the object's attributes. For example:
@@ -22,12 +22,12 @@ module ActiveRecord #:nodoc:
     #     <last-read type="date">2004-04-15</last-read>
     #   </topic>
     #
-    # This behavior can be controlled with :only, :except,
-    # :skip_instruct, :skip_types and :dasherize. The :only and
-    # :except options are the same as for the #attributes method.
-    # The default is to dasherize all column names, to disable this,
-    # set :dasherize to false. To not have the column type included
-    # in the XML output, set :skip_types to true.
+    # This behavior can be controlled with <tt>:only</tt>, <tt>:except</tt>,
+    # <tt>:skip_instruct</tt>, <tt>:skip_types</tt> and <tt>:dasherize</tt>.
+    # The <tt>:only</tt> and <tt>:except</tt> options are the same as for the
+    # +attributes+ method. The default is to dasherize all column names, but you
+    # can disable this setting <tt>:dasherize</tt> to +false+. To not have the
+    # column type included in the XML output set <tt>:skip_types</tt> to +true+.
     #
     # For instance:
     #
@@ -43,7 +43,7 @@ module ActiveRecord #:nodoc:
     #     <last-read type="date">2004-04-15</last-read>
     #   </topic>
     #
-    # To include first level associations use :include
+    # To include first level associations use <tt>:include</tt>:
     #
     #   firm.to_xml :include => [ :account, :clients ]
     #
@@ -98,7 +98,7 @@ module ActiveRecord #:nodoc:
     #     </account>
     #   </firm>
     #
-    # To include any methods on the object(s) being called use :methods
+    # To include any methods on the model being called use <tt>:methods</tt>:
     #
     #   firm.to_xml :methods => [ :calculated_earnings, :real_earnings ]
     #
@@ -108,9 +108,8 @@ module ActiveRecord #:nodoc:
     #     <real-earnings>5</real-earnings>
     #   </firm>
     #
-    # To call any Procs on the object(s) use :procs. The Procs
-    # are passed a modified version of the options hash that was
-    # given to #to_xml.
+    # To call any additional Procs use <tt>:procs</tt>. The Procs are passed a
+    # modified version of the options hash that was given to +to_xml+:
     #
     #   proc = Proc.new { |options| options[:builder].tag!('abc', 'def') }
     #   firm.to_xml :procs => [ proc ]
@@ -120,7 +119,7 @@ module ActiveRecord #:nodoc:
     #     <abc>def</abc>
     #   </firm>
     #
-    # Alternatively, you can yield the builder object as part of the to_xml call:
+    # Alternatively, you can yield the builder object as part of the +to_xml+ call:
     #
     #   firm.to_xml do |xml|
     #     xml.creator do
@@ -137,8 +136,9 @@ module ActiveRecord #:nodoc:
     #     </creator>
     #   </firm>
     #
-    # You can override the to_xml method in your ActiveRecord::Base
-    # subclasses if you need to. The general form of doing this is:
+    # As noted above, you may override +to_xml+ in your ActiveRecord::Base
+    # subclasses to have complete control about what's generated. The general
+    # form of doing this is:
     #
     #   class IHaveMyOwnXML < ActiveRecord::Base
     #     def to_xml(options = {})
diff --git a/activerecord/lib/active_record/validations.rb b/activerecord/lib/active_record/validations.rb
index 5ca51c014c..50db32725d 100755
--- a/activerecord/lib/active_record/validations.rb
+++ b/activerecord/lib/active_record/validations.rb
@@ -201,7 +201,7 @@ module ActiveRecord
     alias_method :count, :size
     alias_method :length, :size
 
-    # Return an XML representation of this error object.
+    # Returns an XML representation of this error object.
     #
     #   class Company < ActiveRecord::Base
     #     validates_presence_of :name, :address, :email
@@ -266,7 +266,7 @@ module ActiveRecord
   #   person.attributes = { "last_name" => "Heinemeier", "phone_number" => "555-555" }
   #   person.save # => true (and person is now saved in the database)
   #
-  # An +Errors+ object is automatically created for every Active Record.
+  # An Errors object is automatically created for every Active Record.
   #
   # Please do have a look at ActiveRecord::Validations::ClassMethods for a higher level of validations.
   module Validations
@@ -286,7 +286,7 @@ module ActiveRecord
 
     # All of the following validations are defined in the class scope of the model that you're interested in validating.
     # They offer a more declarative way of specifying when the model is valid and when it is not. It is recommended to use
-    # these over the low-level calls to validate and validate_on_create when possible.
+    # these over the low-level calls to +validate+ and +validate_on_create+ when possible.
     module ClassMethods
       DEFAULT_VALIDATION_OPTIONS = {
         :on => :save,
@@ -337,14 +337,14 @@ module ActiveRecord
       #   end
       #
       # Options:
-      # * <tt>on</tt> - Specifies when this validation is active (default is :save, other options :create, :update)
-      # * <tt>allow_nil</tt> - Skip validation if attribute is nil.
-      # * <tt>allow_blank</tt> - Skip validation if attribute is blank.
-      # * <tt>if</tt> - Specifies a method, proc or string to call to determine if the validation should
-      #   occur (e.g. :if => :allow_validation, or :if => Proc.new { |user| user.signup_step > 2 }).  The
+      # * <tt>:on</tt> - Specifies when this validation is active (default is <tt>:save</tt>, other options <tt>:create</tt>, <tt>:update</tt>).
+      # * <tt>:allow_nil</tt> - Skip validation if attribute is +nil+.
+      # * <tt>:allow_blank</tt> - Skip validation if attribute is blank.
+      # * <tt>:if</tt> - Specifies a method, proc or string to call to determine if the validation should
+      #   occur (e.g. <tt>:if => :allow_validation</tt>, or <tt>:if => Proc.new { |user| user.signup_step > 2 }</tt>).  The
       #   method, proc or string should return or evaluate to a true or false value.
-      # * <tt>unless</tt> - Specifies a method, proc or string to call to determine if the validation should
-      #   not occur (e.g. :unless => :skip_validation, or :unless => Proc.new { |user| user.signup_step <= 2 }).  The
+      # * <tt>:unless</tt> - Specifies a method, proc or string to call to determine if the validation should
+      #   not occur (e.g. <tt>:unless => :skip_validation</tt>, or <tt>:unless => Proc.new { |user| user.signup_step <= 2 }</tt>).  The
       #   method, proc or string should return or evaluate to a true or false value.
       def validates_each(*attrs)
         options = attrs.extract_options!.symbolize_keys
@@ -374,19 +374,19 @@ module ActiveRecord
       #
       # The added +password_confirmation+ attribute is virtual; it exists only as an in-memory attribute for validating the password.
       # To achieve this, the validation adds accessors to the model for the confirmation attribute. NOTE: This check is performed
-      # only if +password_confirmation+ is not nil, and by default only on save. To require confirmation, make sure to add a presence
+      # only if +password_confirmation+ is not +nil+, and by default only on save. To require confirmation, make sure to add a presence
       # check for the confirmation attribute:
       #
       #   validates_presence_of :password_confirmation, :if => :password_changed?
       #
       # Configuration options:
-      # * <tt>message</tt> - A custom error message (default is: "doesn't match confirmation")
-      # * <tt>on</tt> - Specifies when this validation is active (default is :save, other options :create, :update)
-      # * <tt>if</tt> - Specifies a method, proc or string to call to determine if the validation should
-      #   occur (e.g. :if => :allow_validation, or :if => Proc.new { |user| user.signup_step > 2 }).  The
+      # * <tt>:message</tt> - A custom error message (default is: "doesn't match confirmation").
+      # * <tt>:on</tt> - Specifies when this validation is active (default is <tt>:save</tt>, other options <tt>:create</tt>, <tt>:update</tt>).
+      # * <tt>:if</tt> - Specifies a method, proc or string to call to determine if the validation should
+      #   occur (e.g. <tt>:if => :allow_validation</tt>, or <tt>:if => Proc.new { |user| user.signup_step > 2 }</tt>).  The
       #   method, proc or string should return or evaluate to a true or false value.
-      # * <tt>unless</tt> - Specifies a method, proc or string to call to determine if the validation should
-      #   not occur (e.g. :unless => :skip_validation, or :unless => Proc.new { |user| user.signup_step <= 2 }).  The
+      # * <tt>:unless</tt> - Specifies a method, proc or string to call to determine if the validation should
+      #   not occur (e.g. <tt>:unless => :skip_validation</tt>, or <tt>:unless => Proc.new { |user| user.signup_step <= 2 }</tt>).  The
       #   method, proc or string should return or evaluate to a true or false value.
       def validates_confirmation_of(*attr_names)
         configuration = { :message => ActiveRecord::Errors.default_error_messages[:confirmation], :on => :save }
@@ -406,21 +406,21 @@ module ActiveRecord
       #     validates_acceptance_of :eula, :message => "must be abided"
       #   end
       #
-      # If the database column does not exist, the terms_of_service attribute is entirely virtual. This check is
-      # performed only if terms_of_service is not nil and by default on save.
+      # If the database column does not exist, the +terms_of_service+ attribute is entirely virtual. This check is
+      # performed only if +terms_of_service+ is not +nil+ and by default on save.
       #
       # Configuration options:
-      # * <tt>message</tt> - A custom error message (default is: "must be accepted")
-      # * <tt>on</tt> - Specifies when this validation is active (default is :save, other options :create, :update)
-      # * <tt>allow_nil</tt> - Skip validation if attribute is nil. (default is true)
-      # * <tt>accept</tt> - Specifies value that is considered accepted.  The default value is a string "1", which
-      #   makes it easy to relate to an HTML checkbox. This should be set to 'true' if you are validating a database
-      #   column, since the attribute is typecast from "1" to <tt>true</tt> before validation.
-      # * <tt>if</tt> - Specifies a method, proc or string to call to determine if the validation should
-      #   occur (e.g. :if => :allow_validation, or :if => Proc.new { |user| user.signup_step > 2 }).  The
+      # * <tt>:message</tt> - A custom error message (default is: "must be accepted").
+      # * <tt>:on</tt> - Specifies when this validation is active (default is <tt>:save</tt>, other options <tt>:create</tt>, <tt>:update</tt>).
+      # * <tt>:allow_nil</tt> - Skip validation if attribute is +nil+ (default is true).
+      # * <tt>:accept</tt> - Specifies value that is considered accepted.  The default value is a string "1", which
+      #   makes it easy to relate to an HTML checkbox. This should be set to +true+ if you are validating a database
+      #   column, since the attribute is typecast from "1" to +true+ before validation.
+      # * <tt>:if</tt> - Specifies a method, proc or string to call to determine if the validation should
+      #   occur (e.g. <tt>:if => :allow_validation</tt>, or <tt>:if => Proc.new { |user| user.signup_step > 2 }</tt>).  The
       #   method, proc or string should return or evaluate to a true or false value.
-      # * <tt>unless</tt> - Specifies a method, proc or string to call to determine if the validation should
-      #   not occur (e.g. :unless => :skip_validation, or :unless => Proc.new { |user| user.signup_step <= 2 }).  The
+      # * <tt>:unless</tt> - Specifies a method, proc or string to call to determine if the validation should
+      #   not occur (e.g. <tt>:unless => :skip_validation</tt>, or <tt>:unless => Proc.new { |user| user.signup_step <= 2 }</tt>).  The
       #   method, proc or string should return or evaluate to a true or false value.
       def validates_acceptance_of(*attr_names)
         configuration = { :message => ActiveRecord::Errors.default_error_messages[:accepted], :on => :save, :allow_nil => true, :accept => "1" }
@@ -452,8 +452,8 @@ module ActiveRecord
       # This is due to the way Object#blank? handles boolean values. false.blank? # => true
       #
       # Configuration options:
-      # * <tt>message</tt> - A custom error message (default is: "can't be blank")
-      # * <tt>on</tt> - Specifies when this validation is active (default is :save, other options :create, :update)
+      # * <tt>message</tt> - A custom error message (default is: "can't be blank").
+      # * <tt>on</tt> - Specifies when this validation is active (default is <tt>:save</tt>, other options <tt>:create</tt>, <tt>:update</tt>).
       # * <tt>if</tt> - Specifies a method, proc or string to call to determine if the validation should
       #   occur (e.g. :if => :allow_validation, or :if => Proc.new { |user| user.signup_step > 2 }).  The
       #   method, proc or string should return or evaluate to a true or false value.
@@ -485,24 +485,24 @@ module ActiveRecord
       #   end
       #
       # Configuration options:
-      # * <tt>minimum</tt> - The minimum size of the attribute
-      # * <tt>maximum</tt> - The maximum size of the attribute
-      # * <tt>is</tt> - The exact size of the attribute
-      # * <tt>within</tt> - A range specifying the minimum and maximum size of the attribute
-      # * <tt>in</tt> - A synonym(or alias) for :within
-      # * <tt>allow_nil</tt> - Attribute may be nil; skip validation.
-      # * <tt>allow_blank</tt> - Attribute may be blank; skip validation.
-      #
-      # * <tt>too_long</tt> - The error message if the attribute goes over the maximum (default is: "is too long (maximum is %d characters)")
-      # * <tt>too_short</tt> - The error message if the attribute goes under the minimum (default is: "is too short (min is %d characters)")
-      # * <tt>wrong_length</tt> - The error message if using the :is method and the attribute is the wrong size (default is: "is the wrong length (should be %d characters)")
-      # * <tt>message</tt> - The error message to use for a :minimum, :maximum, or :is violation.  An alias of the appropriate too_long/too_short/wrong_length message
-      # * <tt>on</tt> - Specifies when this validation is active (default is :save, other options :create, :update)
-      # * <tt>if</tt> - Specifies a method, proc or string to call to determine if the validation should
-      #   occur (e.g. :if => :allow_validation, or :if => Proc.new { |user| user.signup_step > 2 }).  The
+      # * <tt>:minimum</tt> - The minimum size of the attribute.
+      # * <tt>:maximum</tt> - The maximum size of the attribute.
+      # * <tt>:is</tt> - The exact size of the attribute.
+      # * <tt>:within</tt> - A range specifying the minimum and maximum size of the attribute.
+      # * <tt>:in</tt> - A synonym(or alias) for <tt>:within</tt>.
+      # * <tt>:allow_nil</tt> - Attribute may be +nil+; skip validation.
+      # * <tt>:allow_blank</tt> - Attribute may be blank; skip validation.
+      #
+      # * <tt>:too_long</tt> - The error message if the attribute goes over the maximum (default is: "is too long (maximum is %d characters)").
+      # * <tt>:too_short</tt> - The error message if the attribute goes under the minimum (default is: "is too short (min is %d characters)").
+      # * <tt>:wrong_length</tt> - The error message if using the <tt>:is</tt> method and the attribute is the wrong size (default is: "is the wrong length (should be %d characters)").
+      # * <tt>:message</tt> - The error message to use for a <tt>:minimum</tt>, <tt>:maximum</tt>, or <tt>:is</tt> violation.  An alias of the appropriate <tt>too_long</tt>/<tt>too_short</tt>/<tt>wrong_length</tt> message.
+      # * <tt>:on</tt> - Specifies when this validation is active (default is <tt>:save</tt>, other options <tt>:create</tt>, <tt>:update</tt>).
+      # * <tt>:if</tt> - Specifies a method, proc or string to call to determine if the validation should
+      #   occur (e.g. <tt>:if => :allow_validation</tt>, or <tt>:if => Proc.new { |user| user.signup_step > 2 }</tt>).  The
       #   method, proc or string should return or evaluate to a true or false value.
-      # * <tt>unless</tt> - Specifies a method, proc or string to call to determine if the validation should
-      #   not occur (e.g. :unless => :skip_validation, or :unless => Proc.new { |user| user.signup_step <= 2 }).  The
+      # * <tt>:unless</tt> - Specifies a method, proc or string to call to determine if the validation should
+      #   not occur (e.g. <tt>:unless => :skip_validation</tt>, or <tt>:unless => Proc.new { |user| user.signup_step <= 2 }</tt>).  The
       #   method, proc or string should return or evaluate to a true or false value.
       def validates_length_of(*attrs)
         # Merge given options with defaults.
@@ -584,16 +584,16 @@ module ActiveRecord
       # unique index on the field. See +add_index+ for more information.
       #
       # Configuration options:
-      # * <tt>message</tt> - Specifies a custom error message (default is: "has already been taken")
-      # * <tt>scope</tt> - One or more columns by which to limit the scope of the uniqueness constraint.
-      # * <tt>case_sensitive</tt> - Looks for an exact match.  Ignored by non-text columns (true by default).
-      # * <tt>allow_nil</tt> - If set to true, skips this validation if the attribute is null (default is: false)
-      # * <tt>allow_blank</tt> - If set to true, skips this validation if the attribute is blank (default is: false)
-      # * <tt>if</tt> - Specifies a method, proc or string to call to determine if the validation should
-      #   occur (e.g. :if => :allow_validation, or :if => Proc.new { |user| user.signup_step > 2 }).  The
+      # * <tt>:message</tt> - Specifies a custom error message (default is: "has already been taken").
+      # * <tt>:scope</tt> - One or more columns by which to limit the scope of the uniqueness constraint.
+      # * <tt>:case_sensitive</tt> - Looks for an exact match.  Ignored by non-text columns (+false+ by default).
+      # * <tt>:allow_nil</tt> - If set to true, skips this validation if the attribute is +nil+ (default is +false+).
+      # * <tt>:allow_blank</tt> - If set to true, skips this validation if the attribute is blank (default is +false+).
+      # * <tt>:if</tt> - Specifies a method, proc or string to call to determine if the validation should
+      #   occur (e.g. <tt>:if => :allow_validation</tt>, or <tt>:if => Proc.new { |user| user.signup_step > 2 }</tt>).  The
       #   method, proc or string should return or evaluate to a true or false value.
-      # * <tt>unless</tt> - Specifies a method, proc or string to call to determine if the validation should
-      #   not occur (e.g. :unless => :skip_validation, or :unless => Proc.new { |user| user.signup_step <= 2 }).  The
+      # * <tt>:unless</tt> - Specifies a method, proc or string to call to determine if the validation should
+      #   not occur (e.g. <tt>:unless => :skip_validation</tt>, or <tt>:unless => Proc.new { |user| user.signup_step <= 2 }</tt>).  The
       #   method, proc or string should return or evaluate to a true or false value.
       def validates_uniqueness_of(*attr_names)
         configuration = { :message => ActiveRecord::Errors.default_error_messages[:taken], :case_sensitive => true }
@@ -669,21 +669,21 @@ module ActiveRecord
       #     validates_format_of :email, :with => /\A([^@\s]+)@((?:[-a-z0-9]+\.)+[a-z]{2,})\Z/i, :on => :create
       #   end
       #
-      # Note: use \A and \Z to match the start and end of the string, ^ and $ match the start/end of a line.
+      # Note: use <tt>\A</tt> and <tt>\Z</tt> to match the start and end of the string, <tt>^</tt> and <tt>$</tt> match the start/end of a line.
       #
       # A regular expression must be provided or else an exception will be raised.
       #
       # Configuration options:
-      # * <tt>message</tt> - A custom error message (default is: "is invalid")
-      # * <tt>allow_nil</tt> - If set to true, skips this validation if the attribute is null (default is: false)
-      # * <tt>allow_blank</tt> - If set to true, skips this validation if the attribute is blank (default is: false)
-      # * <tt>with</tt> - The regular expression used to validate the format with (note: must be supplied!)
-      # * <tt>on</tt> Specifies when this validation is active (default is :save, other options :create, :update)
-      # * <tt>if</tt> - Specifies a method, proc or string to call to determine if the validation should
-      #   occur (e.g. :if => :allow_validation, or :if => Proc.new { |user| user.signup_step > 2 }).  The
+      # * <tt>:message</tt> - A custom error message (default is: "is invalid").
+      # * <tt>:allow_nil</tt> - If set to true, skips this validation if the attribute is +nil+ (default is +false+).
+      # * <tt>:allow_blank</tt> - If set to true, skips this validation if the attribute is blank (default is +false+).
+      # * <tt>:with</tt> - The regular expression used to validate the format with (note: must be supplied!).
+      # * <tt>:on</tt> Specifies when this validation is active (default is <tt>:save</tt>, other options <tt>:create</tt>, <tt>:update</tt>).
+      # * <tt>:if</tt> - Specifies a method, proc or string to call to determine if the validation should
+      #   occur (e.g. <tt>:if => :allow_validation</tt>, or <tt>:if => Proc.new { |user| user.signup_step > 2 }</tt>).  The
       #   method, proc or string should return or evaluate to a true or false value.
-      # * <tt>unless</tt> - Specifies a method, proc or string to call to determine if the validation should
-      #   not occur (e.g. :unless => :skip_validation, or :unless => Proc.new { |user| user.signup_step <= 2 }).  The
+      # * <tt>:unless</tt> - Specifies a method, proc or string to call to determine if the validation should
+      #   not occur (e.g. <tt>:unless => :skip_validation</tt>, or <tt>:unless => Proc.new { |user| user.signup_step <= 2 }</tt>).  The
       #   method, proc or string should return or evaluate to a true or false value.
       def validates_format_of(*attr_names)
         configuration = { :message => ActiveRecord::Errors.default_error_messages[:invalid], :on => :save, :with => nil }
@@ -705,15 +705,15 @@ module ActiveRecord
       #   end
       #
       # Configuration options:
-      # * <tt>in</tt> - An enumerable object of available items
-      # * <tt>message</tt> - Specifies a custom error message (default is: "is not included in the list")
-      # * <tt>allow_nil</tt> - If set to true, skips this validation if the attribute is null (default is: false)
-      # * <tt>allow_blank</tt> - If set to true, skips this validation if the attribute is blank (default is: false)
-      # * <tt>if</tt> - Specifies a method, proc or string to call to determine if the validation should
-      #   occur (e.g. :if => :allow_validation, or :if => Proc.new { |user| user.signup_step > 2 }).  The
+      # * <tt>:in</tt> - An enumerable object of available items.
+      # * <tt>:message</tt> - Specifies a custom error message (default is: "is not included in the list").
+      # * <tt>:allow_nil</tt> - If set to true, skips this validation if the attribute is +nil+ (default is +false+).
+      # * <tt>:allow_blank</tt> - If set to true, skips this validation if the attribute is blank (default is +false+).
+      # * <tt>:if</tt> - Specifies a method, proc or string to call to determine if the validation should
+      #   occur (e.g. <tt>:if => :allow_validation</tt>, or <tt>:if => Proc.new { |user| user.signup_step > 2 }</tt>).  The
       #   method, proc or string should return or evaluate to a true or false value.
-      # * <tt>unless</tt> - Specifies a method, proc or string to call to determine if the validation should
-      #   not occur (e.g. :unless => :skip_validation, or :unless => Proc.new { |user| user.signup_step <= 2 }).  The
+      # * <tt>:unless</tt> - Specifies a method, proc or string to call to determine if the validation should
+      #   not occur (e.g. <tt>:unless => :skip_validation</tt>, or <tt>:unless => Proc.new { |user| user.signup_step <= 2 }</tt>).  The
       #   method, proc or string should return or evaluate to a true or false value.
       def validates_inclusion_of(*attr_names)
         configuration = { :message => ActiveRecord::Errors.default_error_messages[:inclusion], :on => :save }
@@ -737,15 +737,15 @@ module ActiveRecord
       #   end
       #
       # Configuration options:
-      # * <tt>in</tt> - An enumerable object of items that the value shouldn't be part of
-      # * <tt>message</tt> - Specifies a custom error message (default is: "is reserved")
-      # * <tt>allow_nil</tt> - If set to true, skips this validation if the attribute is null (default is: false)
-      # * <tt>allow_blank</tt> - If set to true, skips this validation if the attribute is blank (default is: false)
-      # * <tt>if</tt> - Specifies a method, proc or string to call to determine if the validation should
-      #   occur (e.g. :if => :allow_validation, or :if => Proc.new { |user| user.signup_step > 2 }).  The
+      # * <tt>:in</tt> - An enumerable object of items that the value shouldn't be part of.
+      # * <tt>:message</tt> - Specifies a custom error message (default is: "is reserved").
+      # * <tt>:allow_nil</tt> - If set to true, skips this validation if the attribute is +nil+ (default is +false+).
+      # * <tt>:allow_blank</tt> - If set to true, skips this validation if the attribute is blank (default is +false+).
+      # * <tt>:if</tt> - Specifies a method, proc or string to call to determine if the validation should
+      #   occur (e.g. <tt>:if => :allow_validation</tt>, or <tt>:if => Proc.new { |user| user.signup_step > 2 }</tt>).  The
       #   method, proc or string should return or evaluate to a true or false value.
-      # * <tt>unless</tt> - Specifies a method, proc or string to call to determine if the validation should
-      #   not occur (e.g. :unless => :skip_validation, or :unless => Proc.new { |user| user.signup_step <= 2 }).  The
+      # * <tt>:unless</tt> - Specifies a method, proc or string to call to determine if the validation should
+      #   not occur (e.g. <tt>:unless => :skip_validation</tt>, or <tt>:unless => Proc.new { |user| user.signup_step <= 2 }</tt>).  The
       #   method, proc or string should return or evaluate to a true or false value.
       def validates_exclusion_of(*attr_names)
         configuration = { :message => ActiveRecord::Errors.default_error_messages[:exclusion], :on => :save }
@@ -777,19 +777,19 @@ module ActiveRecord
       #     validates_associated :book
       #   end
       #
-      # ...this would specify a circular dependency and cause infinite recursion.
+      # this would specify a circular dependency and cause infinite recursion.
       #
       # NOTE: This validation will not fail if the association hasn't been assigned. If you want to ensure that the association
-      # is both present and guaranteed to be valid, you also need to use validates_presence_of.
+      # is both present and guaranteed to be valid, you also need to use +validates_presence_of+.
       #
       # Configuration options:
-      # * <tt>message</tt> - A custom error message (default is: "is invalid")
-      # * <tt>on</tt> Specifies when this validation is active (default is :save, other options :create, :update)
-      # * <tt>if</tt> - Specifies a method, proc or string to call to determine if the validation should
-      #   occur (e.g. :if => :allow_validation, or :if => Proc.new { |user| user.signup_step > 2 }).  The
+      # * <tt>:message</tt> - A custom error message (default is: "is invalid")
+      # * <tt>:on</tt> Specifies when this validation is active (default is <tt>:save</tt>, other options <tt>:create</tt>, <tt>:update</tt>)
+      # * <tt>:if</tt> - Specifies a method, proc or string to call to determine if the validation should
+      #   occur (e.g. <tt>:if => :allow_validation</tt>, or <tt>:if => Proc.new { |user| user.signup_step > 2 }</tt>).  The
       #   method, proc or string should return or evaluate to a true or false value.
-      # * <tt>unless</tt> - Specifies a method, proc or string to call to determine if the validation should
-      #   not occur (e.g. :unless => :skip_validation, or :unless => Proc.new { |user| user.signup_step <= 2 }).  The
+      # * <tt>:unless</tt> - Specifies a method, proc or string to call to determine if the validation should
+      #   not occur (e.g. <tt>:unless => :skip_validation</tt>, or <tt>:unless => Proc.new { |user| user.signup_step <= 2 }</tt>).  The
       #   method, proc or string should return or evaluate to a true or false value.
       def validates_associated(*attr_names)
         configuration = { :message => ActiveRecord::Errors.default_error_messages[:invalid], :on => :save }
@@ -810,22 +810,22 @@ module ActiveRecord
       #   end
       #
       # Configuration options:
-      # * <tt>message</tt> - A custom error message (default is: "is not a number")
-      # * <tt>on</tt> Specifies when this validation is active (default is :save, other options :create, :update)
-      # * <tt>only_integer</tt> Specifies whether the value has to be an integer, e.g. an integral value (default is false)
-      # * <tt>allow_nil</tt> Skip validation if attribute is nil (default is false). Notice that for fixnum and float columns empty strings are converted to nil
-      # * <tt>greater_than</tt> Specifies the value must be greater than the supplied value
-      # * <tt>greater_than_or_equal_to</tt> Specifies the value must be greater than or equal the supplied value
-      # * <tt>equal_to</tt> Specifies the value must be equal to the supplied value
-      # * <tt>less_than</tt> Specifies the value must be less than the supplied value
-      # * <tt>less_than_or_equal_to</tt> Specifies the value must be less than or equal the supplied value
-      # * <tt>odd</tt> Specifies the value must be an odd number
-      # * <tt>even</tt> Specifies the value must be an even number
-      # * <tt>if</tt> - Specifies a method, proc or string to call to determine if the validation should
-      #   occur (e.g. :if => :allow_validation, or :if => Proc.new { |user| user.signup_step > 2 }).  The
+      # * <tt>:message</tt> - A custom error message (default is: "is not a number").
+      # * <tt>:on</tt> - Specifies when this validation is active (default is <tt>:save</tt>, other options <tt>:create</tt>, <tt>:update</tt>).
+      # * <tt>:only_integer</tt> - Specifies whether the value has to be an integer, e.g. an integral value (default is +false+).
+      # * <tt>:allow_nil</tt> - Skip validation if attribute is +nil+ (default is +false+). Notice that for fixnum and float columns empty strings are converted to +nil+.
+      # * <tt>:greater_than</tt> - Specifies the value must be greater than the supplied value.
+      # * <tt>:greater_than_or_equal_to</tt> - Specifies the value must be greater than or equal the supplied value.
+      # * <tt>:equal_to</tt> - Specifies the value must be equal to the supplied value.
+      # * <tt>:less_than</tt> - Specifies the value must be less than the supplied value.
+      # * <tt>:less_than_or_equal_to</tt> - Specifies the value must be less than or equal the supplied value.
+      # * <tt>:odd</tt> - Specifies the value must be an odd number.
+      # * <tt>:even</tt> - Specifies the value must be an even number.
+      # * <tt>:if</tt> - Specifies a method, proc or string to call to determine if the validation should
+      #   occur (e.g. <tt>:if => :allow_validation</tt>, or <tt>:if => Proc.new { |user| user.signup_step > 2 }</tt>).  The
       #   method, proc or string should return or evaluate to a true or false value.
-      # * <tt>unless</tt> - Specifies a method, proc or string to call to determine if the validation should
-      #   not occur (e.g. :unless => :skip_validation, or :unless => Proc.new { |user| user.signup_step <= 2 }).  The
+      # * <tt>:unless</tt> - Specifies a method, proc or string to call to determine if the validation should
+      #   not occur (e.g. <tt>:unless => :skip_validation</tt>, or <tt>:unless => Proc.new { |user| user.signup_step <= 2 }</tt>).  The
       #   method, proc or string should return or evaluate to a true or false value.
       def validates_numericality_of(*attr_names)
         configuration = { :on => :save, :only_integer => false, :allow_nil => false }
@@ -922,7 +922,7 @@ module ActiveRecord
       save(false)
     end
 
-    # Runs validate and validate_on_create or validate_on_update and returns true if no errors were added otherwise false.
+    # Runs +validate+ and +validate_on_create+ or +validate_on_update+ and returns true if no errors were added otherwise false.
     def valid?
       errors.clear
 
@@ -946,7 +946,7 @@ module ActiveRecord
     end
 
     protected
-      # Overwrite this method for validation checks on all saves and use Errors.add(field, msg) for invalid attributes.
+      # Overwrite this method for validation checks on all saves and use <tt>Errors.add(field, msg)</tt> for invalid attributes.
       def validate #:doc:
       end