1 files changed, 11 insertions, 4 deletions
diff --git a/activemodel/lib/active_model/observing.rb b/activemodel/lib/active_model/observing.rb
index c1ac4eb4af..4682ae07ef 100644
--- a/activemodel/lib/active_model/observing.rb
+++ b/activemodel/lib/active_model/observing.rb
@@ -40,7 +40,11 @@ module ActiveModel
         observers.replace(values.flatten)
       end
 
-      # Gets the current observers.
+      # Gets an array of observers observing this model.
+      # The array also provides +enable+ and +disable+ methods
+      # that allow you to selectively enable and disable observers.
+      # (see <tt>ActiveModel::ObserverArray.enable</tt> and
+      # <tt>ActiveModel::ObserverArray.disable</tt> for more on this)
       def observers
         @observers ||= ObserverArray.new(self)
       end
@@ -56,6 +60,8 @@ module ActiveModel
       end
 
       # Add a new observer to the pool.
+      # The new observer needs to respond to 'update', otherwise it
+      # raises an +ArgumentError+ exception.
       def add_observer(observer)
         unless observer.respond_to? :update
           raise ArgumentError, "observer needs to respond to `update'"
@@ -144,8 +150,8 @@ module ActiveModel
   # Observers will by default be mapped to the class with which they share a
   # name. So CommentObserver will be tied to observing Comment, ProductManagerObserver
   # to ProductManager, and so on. If you want to name your observer differently than
-  # the class you're interested in observing, you can use the Observer.observe class
-  # method which takes either the concrete class (Product) or a symbol for that
+  # the class you're interested in observing, you can use the <tt>Observer.observe</tt>
+  # class method which takes either the concrete class (Product) or a symbol for that
   # class (:product):
   #
   #   class AuditObserver < ActiveModel::Observer
@@ -220,7 +226,8 @@ module ActiveModel
       self.class.observed_classes
     end
 
-    # Send observed_method(object) if the method exists.
+    # Send observed_method(object) if the method exists and
+    # the observer is enabled for the given object's class.
     def update(observed_method, object) #:nodoc:
       return unless respond_to?(observed_method)
       return if disabled_for?(object)