Add documentation for new observer enable/disable feature.

3 files changed, 53 insertions, 3 deletions

diff --git a/activemodel/CHANGELOG b/activemodel/CHANGELOG
index f29f134783..c26924cf09 100644
--- a/activemodel/CHANGELOG
+++ b/activemodel/CHANGELOG
@@ -15,6 +15,8 @@
 
 * ActiveModel::AttributeMethods allows attributes to be defined on demand [Alexander Uvarov]
 
+* Add support for selectively enabling/disabling observers [Myron Marston]
+
 
 *Rails 3.0.2 (unreleased)*
 
diff --git a/activemodel/lib/active_model/observer_array.rb b/activemodel/lib/active_model/observer_array.rb
index ab7f86007f..5fb73f1c78 100644
--- a/activemodel/lib/active_model/observer_array.rb
+++ b/activemodel/lib/active_model/observer_array.rb
@@ -2,7 +2,7 @@ require 'set'
 
 module ActiveModel
   # Stores the enabled/disabled state of individual observers for
-  # a particular model classes.
+  # a particular model class.
   class ObserverArray < Array
     attr_reader :model_class
     def initialize(model_class, *args)
@@ -10,14 +10,57 @@ module ActiveModel
       super(*args)
     end
 
+    # Returns true if the given observer is disabled for the model class.
     def disabled_for?(observer)
       disabled_observers.include?(observer.class)
     end
 
+    # Disables one or more observers.  This supports multiple forms:
+    #
+    #   ORM.observers.disable :user_observer
+    #     # => disables the UserObserver
+    #
+    #   User.observers.disable AuditTrail
+    #     # => disables the AuditTrail observer for User notifications.
+    #     #    Other models will still notify the AuditTrail observer.
+    #
+    #   ORM.observers.disable :observer_1, :observer_2
+    #     # => disables Observer1 and Observer2 for all models.
+    #
+    #   ORM.observers.disable :all
+    #     # => disables all observers for all models.
+    #
+    #   User.observers.disable :all do
+    #     # all user observers are disabled for
+    #     # just the duration of the block
+    #   end
     def disable(*observers, &block)
       set_enablement(false, observers, &block)
     end
 
+    # Enables one or more observers.  This supports multiple forms:
+    #
+    #   ORM.observers.enable :user_observer
+    #     # => enables the UserObserver
+    #
+    #   User.observers.enable AuditTrail
+    #     # => enables the AuditTrail observer for User notifications.
+    #     #    Other models will not be affected (i.e. they will not
+    #     #    trigger notifications to AuditTrail if previously disabled)
+    #
+    #   ORM.observers.enable :observer_1, :observer_2
+    #     # => enables Observer1 and Observer2 for all models.
+    #
+    #   ORM.observers.enable :all
+    #     # => enables all observers for all models.
+    #
+    #   User.observers.enable :all do
+    #     # all user observers are enabled for
+    #     # just the duration of the block
+    #   end
+    #
+    # Note: all observers are enabled by default.  This method is only
+    # useful when you have previously disabled one or more observers.
     def enable(*observers, &block)
       set_enablement(true, observers, &block)
     end
diff --git a/activemodel/lib/active_model/observing.rb b/activemodel/lib/active_model/observing.rb
index cfe71074a5..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
@@ -222,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)