Ticket #7808: active_record_improved_docs_on_base.diff

activerecord/lib/active_record/base.rb

@@ -51 +51 @@
-    end
-  end
-
-
-
-
-
+
+
-  #
-
+
+
+
+
+
+
+
+
-  #
-
+
+
+
+
+
+
-  #
-
-
+
+
+
+
-  #
-  #   user = User.new(:name => "David", :occupation => "Code Artist")
-  #   user.name # => "David"
-  #
-You can also use block initialization
+If we pretend for our example that we have the following database schema for our Product
-  #
-
-
-
-
+
+
+
+
+
+
+
+
-  #
-
+
+
+
+
+
+
+
-  #
-
-
-
+
-  #
-
+
+
+
+
+
+
+
+
+
-  #
-
-
-
-
+
+
+
+
+
+
+
+
+
+
+
+
-  #
-
-
-
-
+
+
+
+
+
+
+
-  #
-
-
-
+
-  #
-
-
-
+
+
+
+
-  #   end
-  #
-  # The <tt>authenticate_unsafely</tt> method inserts the parameters directly into the query and is thus susceptible to SQL-injection
-  # attacks if the <tt>user_name</tt> and +password+ parameters come directly from a HTTP request. The <tt>authenticate_safely</tt>  and
-  # <tt>authenticate_safely_simply</tt> both will sanitize the <tt>user_name</tt> and +password+ before inserting them in the query, 
-  # which will ensure that an attacker can't escape the query and fake the login (or worse).
-  #
-
-
-
+
-  #
-
-
-
-
+
+
-  #
-Similarly, a simple hash without a statement will generate conditions based on equality with the SQL AND
-operator. For instance:
+  user = User.new(:name => "David", :occupation => "Code Artist")
+  user.name # => "David"
-  #
-
-
+
-  #
-
+
+
+
+
-  #
-  Student.find(:all, :conditions => { :grade => 9..12 })
+And of course you can just create a bare object and specify the attributes after the fact:
-  #
-
+
+
+
-  #
-  # All column values are automatically available through basic accessors on the Active Record object, but some times you
-  # want to specialize this behavior. This can be done by either by overwriting the default accessors (using the same
-  # name as the attribute) calling read_attribute(attr_name) and write_attribute(attr_name, value) to actually change things.
-  # Example:
-  #
-
-
+
-  #
-
-
-
+
+
+
+
-  #
-
-
-
-
+
+
+
-  #
-  # You can alternatively use self[:attribute]=(value) and self[:attribute] instead of write_attribute(:attribute, vaule) and
-  # read_attribute(:attribute) as a shorter form.
-  #
-  # == Accessing attributes before they have been typecasted
-  #
-  # Sometimes you want to be able to read the raw attribute data without having the column-determined typecast run its course first.
-  # That can be done by using the <attribute>_before_type_cast accessors that all attributes have. For example, if your Account model
-  # has a balance attribute, you can call account.balance_before_type_cast or account.id_before_type_cast.
-  #
-  # This is especially useful in validation situations where the user might supply a string for an integer field and you want to display
-  # the original string back in an error message. Accessing the attribute normally would typecast the string to 0, which isn't what you
-  # want.
-  #
-  # == Dynamic attribute-based finders
-  #
-
-
-
-
-
+
+
+
+
+
+
-  #
-like
-<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
-
+
+like <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 
-  # <tt>Person.find_by_user_name_and_password(user_name, password)</tt>.
-  #
-
-
-
+
+
+
+
-  #
-
-
+
+
+
-  #
-  #   # No 'Summer' tag exists
-  #   Tag.find_or_create_by_name("Summer") # equal to Tag.create(:name => "Summer")
@@ -207 +224 @@
-  #   user = User.create(:preferences => { "background" => "black", "display" => large })
-  #   User.find(user.id).preferences # => { "background" => "black", "display" => large }
-  #
-retrieved as a
-
+
+retrieved as a 
-  #
-  #   class User < ActiveRecord::Base
-  #     serialize :preferences, Hash
@@ -219 +236 @@
-  #
-  # == Single table inheritance
-  #
-(can be changed
-
+
+(can be changed 
-  #
-  #   class Company < ActiveRecord::Base; end
-  #   class Firm < Company; end
-  #   class Client < Company; end
-  #   class PriorityClient < Client; end
-  #
-You can then
-
+
+You can then 
-  #
-
-
+
+
+
-  #
-  # Note, all the attributes for all the cases are kept in the same table. Read more:
-  # http://www.martinfowler.com/eaaCatalog/singleTableInheritance.html
-  #
-  # == Connection to multiple databases in different models
-  #
-
-
-
-
+
+
+
+
+
-  #
-
-
+
+
+
-  #
-  # == Exceptions
-  #
@@ -358 +378 @@
-    @@schema_format = :ruby
-
-    class << self # Class methods
-
-
-
+
+
+
+
+
+
-      #   If no record can be found for all of the listed ids, then RecordNotFound will be raised.
-Find 
+
-      #   conditions or merely an order. If no record can matched, nil is returned.
-
+
+
-      #
+      # === Options Hash
+      # 
-      # All approaches accept an option hash as their last parameter. The options are:
-      #
-
+
+
-      # * <tt>:order</tt>: An SQL fragment like "created_at DESC, name".
-      # * <tt>:group</tt>: An attribute name by which the result should be grouped. Uses the GROUP BY SQL-clause.
-      # * <tt>:limit</tt>: An integer determining the limit on the number of rows that should be returned.
-
-
+
+
+
-      #   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.
-      # * <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.
-join, but not
-
-(or even the name
-
+
+join, but not 
+
+(or even the name 
-      # * <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".
-      #
-
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
-      #   Person.find(1)       # returns the object for ID = 1
-      #   Person.find(1, 2, 6) # returns an array for objects with IDs in (1, 2, 6)
-      #   Person.find([7, 17]) # returns an array for objects with IDs in (7, 17)
-      #   Person.find([1])     # returns an array for objects the object with ID = 1
-      #   Person.find(1, :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
-      # to ensure the results are sorted.
-      #
-Examples for find first:
+  # find first
-      #   Person.find(:first) # returns the first object fetched by SELECT * FROM people
-      #   Person.find(:first, :conditions => [ "user_name = ?", user_name])
-      #   Person.find(:first, :order => "created_on DESC", :offset => 5)
-      #
-Examples for find all:
+  # find all
-      #   Person.find(:all) # returns an array of objects for all the rows fetched by SELECT * FROM people
-      #   Person.find(:all, :conditions => [ "category IN (?)", categories], :limit => 50)
-      #   Person.find(:all, :offset => 10, :limit => 10)
-      #   Person.find(:all, :include => [ :account, :friends ])
-      #   Person.find(:all, :group => "category")
-      #
-
-
-
-
-
-
-
-
-
-
+
-      def find(*args)
-        options = extract_options_from_args!(args)
-        validate_find_options(options)
@@ -451 +541 @@
-        false
-      end
-
-
-
+
+
+
+
+
+
+
+
+
+
+
-      def create(attributes = nil)
-        if attributes.is_a?(Array)
-          attributes.collect { |attr| create(attr) }