update ActiveModel::Model documentation [ci skip]

1 files changed, 37 insertions, 16 deletions

diff --git a/activemodel/lib/active_model/model.rb b/activemodel/lib/active_model/model.rb
index 3af95b09b0..1b2f0e6049 100644
--- a/activemodel/lib/active_model/model.rb
+++ b/activemodel/lib/active_model/model.rb
@@ -2,11 +2,11 @@ module ActiveModel
 
   # == Active Model Basic Model
   #
-  # Includes the required interface for an object to interact with <tt>ActionPack</tt>,
-  # using different <tt>ActiveModel</tt> modules. It includes model name introspections,
-  # conversions, translations and validations. Besides that, it allows you to
-  # initialize the object with a hash of attributes, pretty much like
-  # <tt>ActiveRecord</tt> does.
+  # Includes the required interface for an object to interact with
+  # <tt>ActionPack</tt>, using different <tt>ActiveModel</tt> modules.
+  # It includes model name introspections, conversions, translations and
+  # validations. Besides that, it allows you to initialize the object with a
+  # hash of attributes, pretty much like <tt>ActiveRecord</tt> does.
   #
   # A minimal implementation could be:
   #
@@ -15,13 +15,13 @@ module ActiveModel
   #     attr_accessor :name, :age
   #   end
   #
-  #   person = Person.new(:name => 'bob', :age => '18')
+  #   person = Person.new(name: 'bob', age: '18')
   #   person.name # => 'bob'
-  #   person.age # => 18
+  #   person.age  # => 18
   #
-  # Note that, by default, <tt>ActiveModel::Model</tt> implements <tt>persisted?</tt> to
-  # return <tt>false</tt>, which is the most common case. You may want to override it
-  # in your class to simulate a different scenario:
+  # Note that, by default, <tt>ActiveModel::Model</tt> implements <tt>persisted?</tt>
+  # to return +false+, which is the most common case. You may want to override
+  # it in your class to simulate a different scenario:
   #
   #   class Person
   #     include ActiveModel::Model
@@ -32,11 +32,12 @@ module ActiveModel
   #     end
   #   end
   #
-  #   person = Person.new(:id => 1, :name => 'bob')
+  #   person = Person.new(id: 1, name: 'bob')
   #   person.persisted? # => true
   #
-  # Also, if for some reason you need to run code on <tt>initialize</tt>, make sure you
-  # call super if you want the attributes hash initialization to happen.
+  # Also, if for some reason you need to run code on <tt>initialize</tt>, make
+  # sure you call +super+ if you want the attributes hash initialization to
+  # happen.
   #
   #   class Person
   #     include ActiveModel::Model
@@ -48,11 +49,12 @@ module ActiveModel
   #     end
   #   end
   #
-  #   person = Person.new(:id => 1, :name => 'bob')
+  #   person = Person.new(id: 1, name: 'bob')
   #   person.omg # => true
   #
-  # For more detailed information on other functionalities available, please refer
-  # to the specific modules included in <tt>ActiveModel::Model</tt> (see below).
+  # For more detailed information on other functionalities available, please
+  # refer to the specific modules included in <tt>ActiveModel::Model</tt>
+  # (see below).
   module Model
     def self.included(base)
       base.class_eval do
@@ -63,12 +65,31 @@ module ActiveModel
       end
     end
 
+    # Initializes a new model with the given +params+.
+    #
+    #   class Person
+    #     include ActiveModel::Model
+    #     attr_accessor :name, :age
+    #   end
+    #
+    #   person = Person.new(name: 'bob', age: '18')
+    #   person.name # => "bob"
+    #   person.age  # => 18
     def initialize(params={})
       params.each do |attr, value|
         self.public_send("#{attr}=", value)
       end if params
     end
 
+    # Indicates if the model is persisted. Default is +false+.
+    #
+    #  class Person
+    #    include ActiveModel::Model
+    #    attr_accessor :id, :name
+    #  end
+    #
+    #  person = Person.new(id: 1, name: 'bob')
+    #  person.persisted? # => false
     def persisted?
       false
     end